mirror of
https://github.com/django/django.git
synced 2025-08-31 07:47:37 +00:00
Fixed #30573 -- Rephrased documentation to avoid words that minimise the involved difficulty.
This patch does not remove all occurrences of the words in question. Rather, I went through all of the occurrences of the words listed below, and judged if they a) suggested the reader had some kind of knowledge/experience, and b) if they added anything of value (including tone of voice, etc). I left most of the words alone. I looked at the following words: - simply/simple - easy/easier/easiest - obvious - just - merely - straightforward - ridiculous Thanks to Carlton Gibson for guidance on how to approach this issue, and to Tim Bell for providing the idea. But the enormous lion's share of thanks go to Adam Johnson for his patient and helpful review.
This commit is contained in:
Tobias Kunze
Mariusz Felisiak
parent
addabc492b
commit
4a954cfd11
149 changed files with 1101 additions and 1157 deletions
|
|
@ -10,8 +10,9 @@ in Django that you'd like to see fixed, or maybe there's a small feature you
|
|||
want added.
|
||||
|
||||
Contributing back to Django itself is the best way to see your own concerns
|
||||
addressed. This may seem daunting at first, but it's really pretty simple.
|
||||
We'll walk you through the entire process, so you can learn by example.
|
||||
addressed. This may seem daunting at first, but it's a well-traveled path with
|
||||
documentation, tooling, and a community to support you. We'll walk you through
|
||||
the entire process, so you can learn by example.
|
||||
|
||||
Who's this tutorial for?
|
||||
------------------------
|
||||
|
|
@ -387,7 +388,7 @@ Running Django's test suite for the second time
|
|||
===============================================
|
||||
|
||||
Once you've verified that your patch and your test are working correctly, it's
|
||||
a good idea to run the entire Django test suite just to verify that your change
|
||||
a good idea to run the entire Django test suite to verify that your change
|
||||
hasn't introduced any bugs into other areas of Django. While successfully
|
||||
passing the entire test suite doesn't guarantee your code is bug free, it does
|
||||
help identify many bugs and regressions that might otherwise go unnoticed.
|
||||
|
|
@ -592,7 +593,7 @@ If you just want to get started already (and nobody would blame you!), try
|
|||
taking a look at the list of `easy tickets that need patches`__ and the
|
||||
`easy tickets that have patches which need improvement`__. If you're familiar
|
||||
with writing tests, you can also look at the list of
|
||||
`easy tickets that need tests`__. Just remember to follow the guidelines about
|
||||
`easy tickets that need tests`__. Remember to follow the guidelines about
|
||||
claiming tickets that were mentioned in the link to Django's documentation on
|
||||
:doc:`claiming tickets and submitting patches
|
||||
</internals/contributing/writing-code/submitting-patches>`.
|
||||
|
|
|
|||
|
|
@ -4,8 +4,8 @@ Quick install guide
|
|||
|
||||
Before you can use Django, you'll need to get it installed. We have a
|
||||
:doc:`complete installation guide </topics/install>` that covers all the
|
||||
possibilities; this guide will guide you to a simple, minimal installation
|
||||
that'll work while you walk through the introduction.
|
||||
possibilities; this guide will guide you to a minimal installation that'll work
|
||||
while you walk through the introduction.
|
||||
|
||||
Install Python
|
||||
==============
|
||||
|
|
@ -37,7 +37,7 @@ the :ref:`database installation information <database-installation>`.
|
|||
Install Django
|
||||
==============
|
||||
|
||||
You've got three easy options to install Django:
|
||||
You've got three options to install Django:
|
||||
|
||||
* :ref:`Install an official release <installing-official-release>`. This
|
||||
is the best approach for most users.
|
||||
|
|
|
|||
|
|
@ -144,8 +144,8 @@ A dynamic admin interface: it's not just scaffolding -- it's the whole house
|
|||
|
||||
Once your models are defined, Django can automatically create a professional,
|
||||
production ready :doc:`administrative interface </ref/contrib/admin/index>` --
|
||||
a website that lets authenticated users add, change and delete objects. It's
|
||||
as easy as registering your model in the admin site:
|
||||
a website that lets authenticated users add, change and delete objects. The
|
||||
only step required is to register your model in the admin site:
|
||||
|
||||
.. code-block:: python
|
||||
:caption: mysite/news/models.py
|
||||
|
|
@ -169,7 +169,7 @@ as easy as registering your model in the admin site:
|
|||
|
||||
The philosophy here is that your site is edited by a staff, or a client, or
|
||||
maybe just you -- and you don't want to have to deal with creating backend
|
||||
interfaces just to manage content.
|
||||
interfaces only to manage content.
|
||||
|
||||
One typical workflow in creating Django apps is to create models and get the
|
||||
admin sites up and running as fast as possible, so your staff (or clients) can
|
||||
|
|
@ -183,9 +183,9 @@ application. Django encourages beautiful URL design and doesn't put any cruft
|
|||
in URLs, like ``.php`` or ``.asp``.
|
||||
|
||||
To design URLs for an app, you create a Python module called a :doc:`URLconf
|
||||
</topics/http/urls>`. A table of contents for your app, it contains a simple
|
||||
mapping between URL patterns and Python callback functions. URLconfs also serve
|
||||
to decouple URLs from Python code.
|
||||
</topics/http/urls>`. A table of contents for your app, it contains a mapping
|
||||
between URL patterns and Python callback functions. URLconfs also serve to
|
||||
decouple URLs from Python code.
|
||||
|
||||
Here's what a URLconf might look like for the ``Reporter``/``Article``
|
||||
example above:
|
||||
|
|
@ -315,12 +315,12 @@ Here's what the "base.html" template, including the use of :doc:`static files
|
|||
</html>
|
||||
|
||||
Simplistically, it defines the look-and-feel of the site (with the site's logo),
|
||||
and provides "holes" for child templates to fill. This makes a site redesign as
|
||||
easy as changing a single file -- the base template.
|
||||
and provides "holes" for child templates to fill. This means that a site redesign
|
||||
can be done by changing a single file -- the base template.
|
||||
|
||||
It also lets you create multiple versions of a site, with different base
|
||||
templates, while reusing child templates. Django's creators have used this
|
||||
technique to create strikingly different mobile versions of sites -- simply by
|
||||
technique to create strikingly different mobile versions of sites by only
|
||||
creating a new base template.
|
||||
|
||||
Note that you don't have to use Django's template system if you prefer another
|
||||
|
|
@ -340,15 +340,14 @@ features:
|
|||
* A :doc:`caching framework </topics/cache>` that integrates with memcached
|
||||
or other backends.
|
||||
|
||||
* A :doc:`syndication framework </ref/contrib/syndication>` that makes
|
||||
creating RSS and Atom feeds as easy as writing a small Python class.
|
||||
* A :doc:`syndication framework </ref/contrib/syndication>` that lets you
|
||||
create RSS and Atom feeds by writing a small Python class.
|
||||
|
||||
* More attractive automatically-generated admin features -- this overview
|
||||
barely scratched the surface.
|
||||
|
||||
The next obvious steps are for you to `download Django`_, read :doc:`the
|
||||
tutorial </intro/tutorial01>` and join `the community`_. Thanks for your
|
||||
interest!
|
||||
The next steps are for you to `download Django`_, read :doc:`the tutorial
|
||||
</intro/tutorial01>` and join `the community`_. Thanks for your interest!
|
||||
|
||||
.. _download Django: https://www.djangoproject.com/download/
|
||||
.. _the community: https://www.djangoproject.com/community/
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ Reusability is the way of life in Python. `The Python Package Index (PyPI)
|
|||
<https://pypi.org/>`_ has a vast range of packages you can use in your own
|
||||
Python programs. Check out `Django Packages <https://djangopackages.org>`_ for
|
||||
existing reusable apps you could incorporate in your project. Django itself is
|
||||
also just a Python package. This means that you can take existing Python
|
||||
also a normal Python package. This means that you can take existing Python
|
||||
packages or Django apps and compose them into your own web project. You only
|
||||
need to write the parts that make your project unique.
|
||||
|
||||
|
|
@ -41,8 +41,8 @@ projects and ready to publish for others to install and use.
|
|||
bar``. For a directory (like ``polls``) to form a package, it must contain
|
||||
a special file ``__init__.py``, even if this file is empty.
|
||||
|
||||
A Django *application* is just a Python package that is specifically
|
||||
intended for use in a Django project. An application may use common Django
|
||||
A Django *application* is a Python package that is specifically intended
|
||||
for use in a Django project. An application may use common Django
|
||||
conventions, such as having ``models``, ``tests``, ``urls``, and ``views``
|
||||
submodules.
|
||||
|
||||
|
|
@ -148,8 +148,8 @@ this. For a small app like polls, this process isn't too difficult.
|
|||
Polls
|
||||
=====
|
||||
|
||||
Polls is a simple Django app to conduct Web-based polls. For each
|
||||
question, visitors can choose between a fixed number of answers.
|
||||
Polls is a Django app to conduct Web-based polls. For each question,
|
||||
visitors can choose between a fixed number of answers.
|
||||
|
||||
Detailed documentation is in the "docs" directory.
|
||||
|
||||
|
|
@ -206,7 +206,7 @@ this. For a small app like polls, this process isn't too difficult.
|
|||
packages=find_packages(),
|
||||
include_package_data=True,
|
||||
license='BSD License', # example license
|
||||
description='A simple Django app to conduct Web-based polls.',
|
||||
description='A Django app to conduct Web-based polls.',
|
||||
long_description=README,
|
||||
url='https://www.example.com/',
|
||||
author='Your Name',
|
||||
|
|
|
|||
|
|
@ -90,9 +90,8 @@ Let's look at what :djadmin:`startproject` created::
|
|||
|
||||
These files are:
|
||||
|
||||
* The outer :file:`mysite/` root directory is just a container for your
|
||||
project. Its name doesn't matter to Django; you can rename it to anything
|
||||
you like.
|
||||
* The outer :file:`mysite/` root directory is a container for your project. Its
|
||||
name doesn't matter to Django; you can rename it to anything you like.
|
||||
|
||||
* :file:`manage.py`: A command-line utility that lets you interact with this
|
||||
Django project in various ways. You can read all the details about
|
||||
|
|
@ -207,7 +206,7 @@ rather than creating directories.
|
|||
|
||||
What's the difference between a project and an app? An app is a Web
|
||||
application that does something -- e.g., a Weblog system, a database of
|
||||
public records or a simple poll app. A project is a collection of
|
||||
public records or a small poll app. A project is a collection of
|
||||
configuration and apps for a particular website. A project can contain
|
||||
multiple apps. An app can be in multiple projects.
|
||||
|
||||
|
|
|
|||
|
|
@ -123,16 +123,16 @@ additional metadata.
|
|||
place and automatically derive things from it.
|
||||
|
||||
This includes the migrations - unlike in Ruby On Rails, for example, migrations
|
||||
are entirely derived from your models file, and are essentially just a
|
||||
are entirely derived from your models file, and are essentially a
|
||||
history that Django can roll through to update your database schema to
|
||||
match your current models.
|
||||
|
||||
In our simple poll app, we'll create two models: ``Question`` and ``Choice``.
|
||||
A ``Question`` has a question and a publication date. A ``Choice`` has two
|
||||
In our poll app, we'll create two models: ``Question`` and ``Choice``. A
|
||||
``Question`` has a question and a publication date. A ``Choice`` has two
|
||||
fields: the text of the choice and a vote tally. Each ``Choice`` is associated
|
||||
with a ``Question``.
|
||||
|
||||
These concepts are represented by simple Python classes. Edit the
|
||||
These concepts are represented by Python classes. Edit the
|
||||
:file:`polls/models.py` file so it looks like this:
|
||||
|
||||
.. code-block:: python
|
||||
|
|
@ -151,9 +151,9 @@ These concepts are represented by simple Python classes. Edit the
|
|||
choice_text = models.CharField(max_length=200)
|
||||
votes = models.IntegerField(default=0)
|
||||
|
||||
The code is straightforward. Each model is represented by a class that
|
||||
subclasses :class:`django.db.models.Model`. Each model has a number of class
|
||||
variables, each of which represents a database field in the model.
|
||||
Here, each model is represented by a class that subclasses
|
||||
:class:`django.db.models.Model`. Each model has a number of class variables,
|
||||
each of which represents a database field in the model.
|
||||
|
||||
Each field is represented by an instance of a :class:`~django.db.models.Field`
|
||||
class -- e.g., :class:`~django.db.models.CharField` for character fields and
|
||||
|
|
@ -245,11 +245,11 @@ some changes to your models (in this case, you've made new ones) and that
|
|||
you'd like the changes to be stored as a *migration*.
|
||||
|
||||
Migrations are how Django stores changes to your models (and thus your
|
||||
database schema) - they're just files on disk. You can read the migration
|
||||
for your new model if you like; it's the file
|
||||
``polls/migrations/0001_initial.py``. Don't worry, you're not expected to read
|
||||
them every time Django makes one, but they're designed to be human-editable
|
||||
in case you want to manually tweak how Django changes things.
|
||||
database schema) - they're files on disk. You can read the migration for your
|
||||
new model if you like; it's the file ``polls/migrations/0001_initial.py``.
|
||||
Don't worry, you're not expected to read them every time Django makes one, but
|
||||
they're designed to be human-editable in case you want to manually tweak how
|
||||
Django changes things.
|
||||
|
||||
There's a command that will run the migrations for you and manage your database
|
||||
schema automatically - that's called :djadmin:`migrate`, and we'll come to it in a
|
||||
|
|
@ -311,7 +311,7 @@ Note the following:
|
|||
(Yes, you can override this, as well.)
|
||||
|
||||
* The foreign key relationship is made explicit by a ``FOREIGN KEY``
|
||||
constraint. Don't worry about the ``DEFERRABLE`` parts; that's just telling
|
||||
constraint. Don't worry about the ``DEFERRABLE`` parts; it's telling
|
||||
PostgreSQL to not enforce the foreign key until the end of the transaction.
|
||||
|
||||
* It's tailored to the database you're using, so database-specific field types
|
||||
|
|
@ -321,7 +321,7 @@ Note the following:
|
|||
single quotes.
|
||||
|
||||
* The :djadmin:`sqlmigrate` command doesn't actually run the migration on your
|
||||
database - it just prints it to the screen so that you can see what SQL
|
||||
database - instead, it prints it to the screen so that you can see what SQL
|
||||
Django thinks is required. It's useful for checking what Django is going to
|
||||
do or if you have database administrators who require SQL scripts for
|
||||
changes.
|
||||
|
|
@ -640,9 +640,9 @@ Make the poll app modifiable in the admin
|
|||
|
||||
But where's our poll app? It's not displayed on the admin index page.
|
||||
|
||||
Just one thing to do: we need to tell the admin that ``Question``
|
||||
objects have an admin interface. To do this, open the :file:`polls/admin.py`
|
||||
file, and edit it to look like this:
|
||||
Only one more thing to do: we need to tell the admin that ``Question`` objects
|
||||
have an admin interface. To do this, open the :file:`polls/admin.py` file, and
|
||||
edit it to look like this:
|
||||
|
||||
.. code-block:: python
|
||||
:caption: polls/admin.py
|
||||
|
|
|
|||
|
|
@ -40,16 +40,16 @@ In our poll application, we'll have the following four views:
|
|||
question.
|
||||
|
||||
In Django, web pages and other content are delivered by views. Each view is
|
||||
represented by a simple Python function (or method, in the case of class-based
|
||||
views). Django will choose a view by examining the URL that's requested (to be
|
||||
precise, the part of the URL after the domain name).
|
||||
represented by a Python function (or method, in the case of class-based views).
|
||||
Django will choose a view by examining the URL that's requested (to be precise,
|
||||
the part of the URL after the domain name).
|
||||
|
||||
Now in your time on the web you may have come across such beauties as
|
||||
"ME2/Sites/dirmod.asp?sid=&type=gen&mod=Core+Pages&gid=A6CD4967199A42D9B65B1B".
|
||||
You will be pleased to know that Django allows us much more elegant
|
||||
*URL patterns* than that.
|
||||
|
||||
A URL pattern is simply the general form of a URL - for example:
|
||||
A URL pattern is the general form of a URL - for example:
|
||||
``/newsarchive/<year>/<month>/``.
|
||||
|
||||
To get from a URL to a view, Django uses what are known as 'URLconfs'. A
|
||||
|
|
@ -181,7 +181,7 @@ directory called ``polls``, and within that create a file called
|
|||
``index.html``. In other words, your template should be at
|
||||
``polls/templates/polls/index.html``. Because of how the ``app_directories``
|
||||
template loader works as described above, you can refer to this template within
|
||||
Django simply as ``polls/index.html``.
|
||||
Django as ``polls/index.html``.
|
||||
|
||||
.. admonition:: Template namespacing
|
||||
|
||||
|
|
@ -190,7 +190,7 @@ Django simply as ``polls/index.html``.
|
|||
but it would actually be a bad idea. Django will choose the first template
|
||||
it finds whose name matches, and if you had a template with the same name
|
||||
in a *different* application, Django would be unable to distinguish between
|
||||
them. We need to be able to point Django at the right one, and the easiest
|
||||
them. We need to be able to point Django at the right one, and the best
|
||||
way to ensure this is by *namespacing* them. That is, by putting those
|
||||
templates inside *another* directory named for the application itself.
|
||||
|
||||
|
|
@ -455,4 +455,5 @@ to point at the namespaced detail view:
|
|||
<li><a href="{% url 'polls:detail' question.id %}">{{ question.question_text }}</a></li>
|
||||
|
||||
When you're comfortable with writing views, read :doc:`part 4 of this tutorial
|
||||
</intro/tutorial04>` to learn about simple form processing and generic views.
|
||||
</intro/tutorial04>` to learn the basics about form processing and generic
|
||||
views.
|
||||
|
|
|
|||
|
|
@ -3,11 +3,11 @@ Writing your first Django app, part 4
|
|||
=====================================
|
||||
|
||||
This tutorial begins where :doc:`Tutorial 3 </intro/tutorial03>` left off. We're
|
||||
continuing the Web-poll application and will focus on simple form processing and
|
||||
continuing the Web-poll application and will focus on form processing and
|
||||
cutting down our code.
|
||||
|
||||
Write a simple form
|
||||
===================
|
||||
Write a minimal form
|
||||
====================
|
||||
|
||||
Let's update our poll detail template ("polls/detail.html") from the last
|
||||
tutorial, so that the template contains an HTML ``<form>`` element:
|
||||
|
|
@ -42,17 +42,17 @@ A quick rundown:
|
|||
``method="get"``) is very important, because the act of submitting this
|
||||
form will alter data server-side. Whenever you create a form that alters
|
||||
data server-side, use ``method="post"``. This tip isn't specific to
|
||||
Django; it's just good Web development practice.
|
||||
Django; it's good Web development practice in general.
|
||||
|
||||
* ``forloop.counter`` indicates how many times the :ttag:`for` tag has gone
|
||||
through its loop
|
||||
|
||||
* Since we're creating a POST form (which can have the effect of modifying
|
||||
data), we need to worry about Cross Site Request Forgeries.
|
||||
Thankfully, you don't have to worry too hard, because Django comes with
|
||||
a very easy-to-use system for protecting against it. In short, all POST
|
||||
forms that are targeted at internal URLs should use the
|
||||
:ttag:`{% csrf_token %}<csrf_token>` template tag.
|
||||
Thankfully, you don't have to worry too hard, because Django comes with a
|
||||
helpful system for protecting against it. In short, all POST forms that are
|
||||
targeted at internal URLs should use the :ttag:`{% csrf_token %}<csrf_token>`
|
||||
template tag.
|
||||
|
||||
Now, let's create a Django view that handles the submitted data and does
|
||||
something with it. Remember, in :doc:`Tutorial 3 </intro/tutorial03>`, we
|
||||
|
|
@ -121,8 +121,8 @@ This code includes a few things we haven't covered yet in this tutorial:
|
|||
|
||||
As the Python comment above points out, you should always return an
|
||||
:class:`~django.http.HttpResponseRedirect` after successfully dealing with
|
||||
POST data. This tip isn't specific to Django; it's just good Web
|
||||
development practice.
|
||||
POST data. This tip isn't specific to Django; it's good Web development
|
||||
practice in general.
|
||||
|
||||
* We are using the :func:`~django.urls.reverse` function in the
|
||||
:class:`~django.http.HttpResponseRedirect` constructor in this example.
|
||||
|
|
@ -196,7 +196,7 @@ Use generic views: Less code is better
|
|||
======================================
|
||||
|
||||
The ``detail()`` (from :doc:`Tutorial 3 </intro/tutorial03>`) and ``results()``
|
||||
views are very simple -- and, as mentioned above, redundant. The ``index()``
|
||||
views are very short -- and, as mentioned above, redundant. The ``index()``
|
||||
view, which displays a list of polls, is similar.
|
||||
|
||||
These views represent a common case of basic Web development: getting data from
|
||||
|
|
@ -208,8 +208,8 @@ Generic views abstract common patterns to the point where you don't even need
|
|||
to write Python code to write an app.
|
||||
|
||||
Let's convert our poll app to use the generic views system, so we can delete a
|
||||
bunch of our own code. We'll just have to take a few steps to make the
|
||||
conversion. We will:
|
||||
bunch of our own code. We'll have to take a few steps to make the conversion.
|
||||
We will:
|
||||
|
||||
#. Convert the URLconf.
|
||||
|
||||
|
|
@ -331,8 +331,8 @@ However, for ListView, the automatically generated context variable is
|
|||
``question_list``. To override this we provide the ``context_object_name``
|
||||
attribute, specifying that we want to use ``latest_question_list`` instead.
|
||||
As an alternative approach, you could change your templates to match
|
||||
the new default context variables -- but it's a lot easier to just
|
||||
tell Django to use the variable you want.
|
||||
the new default context variables -- but it's a lot easier to tell Django to
|
||||
use the variable you want.
|
||||
|
||||
Run the server, and use your new polling app based on generic views.
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ Introducing automated testing
|
|||
What are automated tests?
|
||||
-------------------------
|
||||
|
||||
Tests are simple routines that check the operation of your code.
|
||||
Tests are routines that check the operation of your code.
|
||||
|
||||
Testing operates at different levels. Some tests might apply to a tiny detail
|
||||
(*does a particular model method return values as expected?*) while others
|
||||
|
|
@ -51,7 +51,7 @@ interactions between components.
|
|||
A change in any of those components could have unexpected consequences on the
|
||||
application's behavior. Checking that it still 'seems to work' could mean
|
||||
running through your code's functionality with twenty different variations of
|
||||
your test data just to make sure you haven't broken something - not a good use
|
||||
your test data to make sure you haven't broken something - not a good use
|
||||
of your time.
|
||||
|
||||
That's especially true when automated tests could do this for you in seconds.
|
||||
|
|
@ -83,9 +83,9 @@ Tests make your code more attractive
|
|||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You might have created a brilliant piece of software, but you will find that
|
||||
many other developers will simply refuse to look at it because it lacks tests;
|
||||
without tests, they won't trust it. Jacob Kaplan-Moss, one of Django's
|
||||
original developers, says "Code without tests is broken by design."
|
||||
many other developers will refuse to look at it because it lacks tests; without
|
||||
tests, they won't trust it. Jacob Kaplan-Moss, one of Django's original
|
||||
developers, says "Code without tests is broken by design."
|
||||
|
||||
That other developers want to see tests in your software before they take it
|
||||
seriously is yet another reason for you to start writing tests.
|
||||
|
|
@ -108,7 +108,7 @@ Some programmers follow a discipline called "`test-driven development`_"; they
|
|||
actually write their tests before they write their code. This might seem
|
||||
counter-intuitive, but in fact it's similar to what most people will often do
|
||||
anyway: they describe a problem, then create some code to solve it. Test-driven
|
||||
development simply formalizes the problem in a Python test case.
|
||||
development formalizes the problem in a Python test case.
|
||||
|
||||
More often, a newcomer to testing will create some code and later decide that
|
||||
it should have some tests. Perhaps it would have been better to write some
|
||||
|
|
@ -270,9 +270,9 @@ After identifying a bug, we wrote a test that exposes it and corrected the bug
|
|||
in the code so our test passes.
|
||||
|
||||
Many other things might go wrong with our application in the future, but we can
|
||||
be sure that we won't inadvertently reintroduce this bug, because simply
|
||||
running the test will warn us immediately. We can consider this little portion
|
||||
of the application pinned down safely forever.
|
||||
be sure that we won't inadvertently reintroduce this bug, because running the
|
||||
test will warn us immediately. We can consider this little portion of the
|
||||
application pinned down safely forever.
|
||||
|
||||
More comprehensive tests
|
||||
------------------------
|
||||
|
|
@ -308,7 +308,7 @@ more comprehensively:
|
|||
And now we have three tests that confirm that ``Question.was_published_recently()``
|
||||
returns sensible values for past, recent, and future questions.
|
||||
|
||||
Again, ``polls`` is a simple application, but however complex it grows in the
|
||||
Again, ``polls`` is a minimal application, but however complex it grows in the
|
||||
future and whatever other code it interacts with, we now have some guarantee
|
||||
that the method we have written tests for will behave in expected ways.
|
||||
|
||||
|
|
@ -324,8 +324,8 @@ A test for a view
|
|||
-----------------
|
||||
|
||||
When we fixed the bug above, we wrote the test first and then the code to fix
|
||||
it. In fact that was a simple example of test-driven development, but it
|
||||
doesn't really matter in which order we do the work.
|
||||
it. In fact that was an example of test-driven development, but it doesn't
|
||||
really matter in which order we do the work.
|
||||
|
||||
In our first test, we focused closely on the internal behavior of the code. For
|
||||
this test, we want to check its behavior as it would be experienced by a user
|
||||
|
|
|
|||
|
|
@ -11,11 +11,10 @@ to serve additional files — such as images, JavaScript, or CSS — necessary t
|
|||
render the complete web page. In Django, we refer to these files as "static
|
||||
files".
|
||||
|
||||
For small projects, this isn't a big deal, because you can just keep the
|
||||
static files somewhere your web server can find it. However, in bigger
|
||||
projects -- especially those comprised of multiple apps -- dealing with the
|
||||
multiple sets of static files provided by each application starts to get
|
||||
tricky.
|
||||
For small projects, this isn't a big deal, because you can keep the static
|
||||
files somewhere your web server can find it. However, in bigger projects --
|
||||
especially those comprised of multiple apps -- dealing with the multiple sets
|
||||
of static files provided by each application starts to get tricky.
|
||||
|
||||
That's what ``django.contrib.staticfiles`` is for: it collects static files
|
||||
from each of your applications (and any other places you specify) into a
|
||||
|
|
@ -39,8 +38,8 @@ Within the ``static`` directory you have just created, create another directory
|
|||
called ``polls`` and within that create a file called ``style.css``. In other
|
||||
words, your stylesheet should be at ``polls/static/polls/style.css``. Because
|
||||
of how the ``AppDirectoriesFinder`` staticfile finder works, you can refer to
|
||||
this static file in Django simply as ``polls/style.css``, similar to how you
|
||||
reference the path for templates.
|
||||
this static file in Django as ``polls/style.css``, similar to how you reference
|
||||
the path for templates.
|
||||
|
||||
.. admonition:: Static file namespacing
|
||||
|
||||
|
|
@ -50,8 +49,8 @@ reference the path for templates.
|
|||
first static file it finds whose name matches, and if you had a static file
|
||||
with the same name in a *different* application, Django would be unable to
|
||||
distinguish between them. We need to be able to point Django at the right
|
||||
one, and the easiest way to ensure this is by *namespacing* them. That is,
|
||||
by putting those static files inside *another* directory named for the
|
||||
one, and the best way to ensure this is by *namespacing* them. That is, by
|
||||
putting those static files inside *another* directory named for the
|
||||
application itself.
|
||||
|
||||
Put the following code in that stylesheet (``polls/static/polls/style.css``):
|
||||
|
|
|
|||
|
|
@ -79,7 +79,7 @@ OK, we have our Question admin page, but a ``Question`` has multiple
|
|||
Yet.
|
||||
|
||||
There are two ways to solve this problem. The first is to register ``Choice``
|
||||
with the admin just as we did with ``Question``. That's easy:
|
||||
with the admin just as we did with ``Question``:
|
||||
|
||||
.. code-block:: python
|
||||
:caption: polls/admin.py
|
||||
|
|
@ -159,8 +159,8 @@ that you can't remove the original three slots. This image shows an added slot:
|
|||
|
||||
One small problem, though. It takes a lot of screen space to display all the
|
||||
fields for entering related ``Choice`` objects. For that reason, Django offers a
|
||||
tabular way of displaying inline related objects; you just need to change
|
||||
the ``ChoiceInline`` declaration to read:
|
||||
tabular way of displaying inline related objects. To use it, change the
|
||||
``ChoiceInline`` declaration to read:
|
||||
|
||||
.. code-block:: python
|
||||
:caption: polls/admin.py
|
||||
|
|
@ -201,8 +201,8 @@ object:
|
|||
# ...
|
||||
list_display = ('question_text', 'pub_date')
|
||||
|
||||
Just for good measure, let's also include the ``was_published_recently()``
|
||||
method from :doc:`Tutorial 2 </intro/tutorial02>`:
|
||||
For good measure, let's also include the ``was_published_recently()`` method
|
||||
from :doc:`Tutorial 2 </intro/tutorial02>`:
|
||||
|
||||
.. code-block:: python
|
||||
:caption: polls/admin.py
|
||||
|
|
@ -284,9 +284,8 @@ Customize the admin look and feel
|
|||
Clearly, having "Django administration" at the top of each admin page is
|
||||
ridiculous. It's just placeholder text.
|
||||
|
||||
That's easy to change, though, using Django's template system. The Django admin
|
||||
is powered by Django itself, and its interfaces use Django's own template
|
||||
system.
|
||||
You can change it, though, using Django's template system. The Django admin is
|
||||
powered by Django itself, and its interfaces use Django's own template system.
|
||||
|
||||
.. _ref-customizing-your-projects-templates:
|
||||
|
||||
|
|
@ -346,7 +345,7 @@ template directory in the source code of Django itself
|
|||
|
||||
$ python -c "import django; print(django.__path__)"
|
||||
|
||||
Then, just edit the file and replace
|
||||
Then, edit the file and replace
|
||||
``{{ site_header|default:_('Django administration') }}`` (including the curly
|
||||
braces) with your own site's name as you see fit. You should end up with
|
||||
a section of code like:
|
||||
|
|
@ -369,9 +368,8 @@ template language will be evaluated to produce the final HTML page, just like
|
|||
we saw in :doc:`Tutorial 3 </intro/tutorial03>`.
|
||||
|
||||
Note that any of Django's default admin templates can be overridden. To
|
||||
override a template, just do the same thing you did with ``base_site.html`` --
|
||||
copy it from the default directory into your custom directory, and make
|
||||
changes.
|
||||
override a template, do the same thing you did with ``base_site.html`` -- copy
|
||||
it from the default directory into your custom directory, and make changes.
|
||||
|
||||
Customizing your *application's* templates
|
||||
------------------------------------------
|
||||
|
|
|
|||
|
|
@ -13,9 +13,9 @@ Well, we've always been big fans of learning by doing. At this point you should
|
|||
know enough to start a project of your own and start fooling around. As you need
|
||||
to learn new tricks, come back to the documentation.
|
||||
|
||||
We've put a lot of effort into making Django's documentation useful, easy to
|
||||
read and as complete as possible. The rest of this document explains more about
|
||||
how the documentation works so that you can get the most out of it.
|
||||
We've put a lot of effort into making Django's documentation useful, clear and
|
||||
as complete as possible. The rest of this document explains more about how the
|
||||
documentation works so that you can get the most out of it.
|
||||
|
||||
(Yes, this is documentation about documentation. Rest assured we have no plans
|
||||
to write a document about how to read the document about documentation.)
|
||||
|
|
@ -74,8 +74,8 @@ different needs:
|
|||
* Finally, there's some "specialized" documentation not usually relevant to
|
||||
most developers. This includes the :doc:`release notes </releases/index>` and
|
||||
:doc:`internals documentation </internals/index>` for those who want to add
|
||||
code to Django itself, and a :doc:`few other things that simply don't fit
|
||||
elsewhere </misc/index>`.
|
||||
code to Django itself, and a :doc:`few other things that don't fit elsewhere
|
||||
</misc/index>`.
|
||||
|
||||
|
||||
How documentation is updated
|
||||
|
|
@ -155,7 +155,7 @@ Django document:
|
|||
As HTML, locally
|
||||
----------------
|
||||
|
||||
You can get a local copy of the HTML documentation following a few easy steps:
|
||||
You can get a local copy of the HTML documentation following a few steps:
|
||||
|
||||
* Django's documentation uses a system called Sphinx__ to convert from
|
||||
plain text to HTML. You'll need to install Sphinx by either downloading
|
||||
|
|
@ -165,8 +165,7 @@ You can get a local copy of the HTML documentation following a few easy steps:
|
|||
|
||||
$ python -m pip install Sphinx
|
||||
|
||||
* Then, just use the included ``Makefile`` to turn the documentation into
|
||||
HTML:
|
||||
* Then, use the included ``Makefile`` to turn the documentation into HTML:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue