test0908
/
django
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Removed use of non-standard indentation rules in docs, and the custom transform that supported them. 

Doc writers should be aware that we are now back to normal ReST rules
regarding blockquotes.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16955 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Luke Plant 2011-10-10 17:32:33 +00:00
parent af244e47cc
commit c61987d75a
8 changed files with 777 additions and 797 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
docs/_ext/djangodocs.py
View File

@ -62,7 +62,6 @@ def setup(app):
app.add_config_value('django_next_version', '0.0', True)
app.add_directive('versionadded', VersionDirective)
app.add_directive('versionchanged', VersionDirective)
app.add_transform(SuppressBlockquotes)
app.add_builder(DjangoStandaloneHTMLBuilder)
@ -99,27 +98,6 @@ class VersionDirective(Directive):
return ret
class SuppressBlockquotes(transforms.Transform):
"""
Remove the default blockquotes that encase indented list, tables, etc.
"""
default_priority = 300
suppress_blockquote_child_nodes = (
nodes.bullet_list,
nodes.enumerated_list,
nodes.definition_list,
nodes.literal_block,
nodes.doctest_block,
nodes.line_block,
nodes.table
)
def apply(self):
for node in self.document.traverse(nodes.block_quote):
if len(node.children) == 1 and isinstance(node.children[0], self.suppress_blockquote_child_nodes):
node.replace_self(node.children[0])
class DjangoHTMLTranslator(SmartyPantsHTMLTranslator):
"""
Django-specific reST to HTML tweaks.

62
docs/ref/contrib/admin/index.txt
View File

@ -16,31 +16,31 @@ Overview
There are seven steps in activating the Django admin site:
1. Add ``'django.contrib.admin'`` to your :setting:`INSTALLED_APPS`
1. Add ``'django.contrib.admin'`` to your :setting:`INSTALLED_APPS`
setting.
2. The admin has four dependencies - :mod:`django.contrib.auth`,
2. The admin has four dependencies - :mod:`django.contrib.auth`,
:mod:`django.contrib.contenttypes`,
:mod:`django.contrib.messages` and
:mod:`django.contrib.sessions`. If these applications are not
in your :setting:`INSTALLED_APPS` list, add them.
3. Add ``django.contrib.messages.context_processors.messages`` to
3. Add ``django.contrib.messages.context_processors.messages`` to
:setting:`TEMPLATE_CONTEXT_PROCESSORS` and
:class:`~django.contrib.messages.middleware.MessageMiddleware` to
:setting:`MIDDLEWARE_CLASSES`.
4. Determine which of your application's models should be editable in the
4. Determine which of your application's models should be editable in the
admin interface.
5. For each of those models, optionally create a ``ModelAdmin`` class that
5. For each of those models, optionally create a ``ModelAdmin`` class that
encapsulates the customized admin functionality and options for that
particular model.
6. Instantiate an ``AdminSite`` and tell it about each of your models and
6. Instantiate an ``AdminSite`` and tell it about each of your models and
``ModelAdmin`` classes.
7. Hook the ``AdminSite`` instance into your URLconf.
7. Hook the ``AdminSite`` instance into your URLconf.
Other topics
------------
@ -1735,11 +1735,11 @@ Templates which may be overridden per app or model
Not every template in ``contrib/admin/templates/admin`` may be overridden per
app or per model. The following can:
* ``app_index.html``
* ``change_form.html``
* ``change_list.html``
* ``delete_confirmation.html``
* ``object_history.html``
* ``app_index.html``
* ``change_form.html``
* ``change_list.html``
* ``delete_confirmation.html``
* ``object_history.html``
For those templates that cannot be overridden in this way, you may still
override them for your entire project. Just place the new version in your
@ -1920,28 +1920,28 @@ accessible using Django's :ref:`URL reversing system <naming-url-patterns>`.
The :class:`AdminSite` provides the following named URL patterns:
====================== ======================== =============
Page URL name Parameters
====================== ======================== =============
Index ``index``
Logout ``logout``
Password change ``password_change``
Password change done ``password_change_done``
i18n javascript ``jsi18n``
Application index page ``app_list`` ``app_label``
====================== ======================== =============
====================== ======================== =============
Page URL name Parameters
====================== ======================== =============
Index ``index``
Logout ``logout``
Password change ``password_change``
Password change done ``password_change_done``
i18n javascript ``jsi18n``
Application index page ``app_list`` ``app_label``
====================== ======================== =============
Each :class:`ModelAdmin` instance provides an additional set of named URLs:
====================== =============================================== =============
Page URL name Parameters
====================== =============================================== =============
Changelist ``{{ app_label }}_{{ model_name }}_changelist``
Add ``{{ app_label }}_{{ model_name }}_add``
History ``{{ app_label }}_{{ model_name }}_history`` ``object_id``
Delete ``{{ app_label }}_{{ model_name }}_delete`` ``object_id``
Change ``{{ app_label }}_{{ model_name }}_change`` ``object_id``
====================== =============================================== =============
====================== =============================================== =============
Page URL name Parameters
====================== =============================================== =============
Changelist ``{{ app_label }}_{{ model_name }}_changelist``
Add ``{{ app_label }}_{{ model_name }}_add``
History ``{{ app_label }}_{{ model_name }}_history`` ``object_id``
Delete ``{{ app_label }}_{{ model_name }}_delete`` ``object_id``
Change ``{{ app_label }}_{{ model_name }}_change`` ``object_id``
====================== =============================================== =============
These named URLs are registered with the application namespace ``admin``, and
with an instance namespace corresponding to the name of the Site instance.

18
docs/ref/contrib/comments/example.txt
View File

@ -125,12 +125,12 @@ moderate comments"``) can approve and delete comments. This can also be
done through the ``admin`` as you'll see later. You might also want to
customize the following templates:
* ``flag.html``
* ``flagged.html``
* ``approve.html``
* ``approved.html``
* ``delete.html``
* ``deleted.html``
* ``flag.html``
* ``flagged.html``
* ``approve.html``
* ``approved.html``
* ``delete.html``
* ``deleted.html``
found under the directory structure we saw for ``form.html``.
@ -185,9 +185,9 @@ in-built with :doc:`generic comment moderation
</ref/contrib/comments/moderation>`. The comment moderation has the following
features (all of which or only certain can be enabled):
* Enable comments for a particular model instance.
* Close comments after a particular (user-defined) number of days.
* Email new comments to the site-staff.
* Enable comments for a particular model instance.
* Close comments after a particular (user-defined) number of days.
* Email new comments to the site-staff.
To enable comment moderation, we subclass the :class:`CommentModerator` and
register it with the moderation features we want. Let us suppose we want to

86
docs/ref/contrib/localflavor.txt
View File

@ -36,49 +36,49 @@ Supported countries
Countries currently supported by :mod:`~django.contrib.localflavor` are:
* Argentina_
* Australia_
* Austria_
* Belgium_
* Brazil_
* Canada_
* Chile_
* China_
* Colombia_
* Croatia_
* Czech_
* Ecuador_
* Finland_
* France_
* Germany_
* Iceland_
* India_
* Indonesia_
* Ireland_
* Israel_
* Italy_
* Japan_
* Kuwait_
* Macedonia_
* Mexico_
* `The Netherlands`_
* Norway_
* Peru_
* Poland_
* Portugal_
* Paraguay_
* Romania_
* Russia_
* Slovakia_
* Slovenia_
* `South Africa`_
* Spain_
* Sweden_
* Switzerland_
* Turkey_
* `United Kingdom`_
* `United States of America`_
* Uruguay_
* Argentina_
* Australia_
* Austria_
* Belgium_
* Brazil_
* Canada_
* Chile_
* China_
* Colombia_
* Croatia_
* Czech_
* Ecuador_
* Finland_
* France_
* Germany_
* Iceland_
* India_
* Indonesia_
* Ireland_
* Israel_
* Italy_
* Japan_
* Kuwait_
* Macedonia_
* Mexico_
* `The Netherlands`_
* Norway_
* Peru_
* Poland_
* Portugal_
* Paraguay_
* Romania_
* Russia_
* Slovakia_
* Slovenia_
* `South Africa`_
* Spain_
* Sweden_
* Switzerland_
* Turkey_
* `United Kingdom`_
* `United States of America`_
* Uruguay_
The ``django.contrib.localflavor`` package also includes a ``generic`` subpackage,
containing useful code that is not specific to one particular country or culture.

46
docs/ref/models/querysets.txt
View File

@ -24,28 +24,28 @@ actually occurs until you do something to evaluate the queryset.
You can evaluate a ``QuerySet`` in the following ways:
* **Iteration.** A ``QuerySet`` is iterable, and it executes its database
* **Iteration.** A ``QuerySet`` is iterable, and it executes its database
query the first time you iterate over it. For example, this will print
the headline of all entries in the database::
for e in Entry.objects.all():
print e.headline
* **Slicing.** As explained in :ref:`limiting-querysets`, a ``QuerySet`` can
* **Slicing.** As explained in :ref:`limiting-querysets`, a ``QuerySet`` can
be sliced, using Python's array-slicing syntax. Usually slicing a
``QuerySet`` returns another (unevaluated) ``QuerySet``, but Django will
execute the database query if you use the "step" parameter of slice
syntax.
* **Pickling/Caching.** See the following section for details of what
* **Pickling/Caching.** See the following section for details of what
is involved when `pickling QuerySets`_. The important thing for the
purposes of this section is that the results are read from the database.
* **repr().** A ``QuerySet`` is evaluated when you call ``repr()`` on it.
* **repr().** A ``QuerySet`` is evaluated when you call ``repr()`` on it.
This is for convenience in the Python interactive interpreter, so you can
immediately see your results when using the API interactively.
* **len().** A ``QuerySet`` is evaluated when you call ``len()`` on it.
* **len().** A ``QuerySet`` is evaluated when you call ``len()`` on it.
This, as you might expect, returns the length of the result list.
Note: *Don't* use ``len()`` on ``QuerySet``\s if all you want to do is
@ -54,7 +54,7 @@ You can evaluate a ``QuerySet`` in the following ways:
and Django provides a ``count()`` method for precisely this reason. See
``count()`` below.
* **list().** Force evaluation of a ``QuerySet`` by calling ``list()`` on
* **list().** Force evaluation of a ``QuerySet`` by calling ``list()`` on
it. For example::
entry_list = list(Entry.objects.all())
@ -64,7 +64,7 @@ You can evaluate a ``QuerySet`` in the following ways:
iterating over a ``QuerySet`` will take advantage of your database to
load data and instantiate objects only as you need them.
* **bool().** Testing a ``QuerySet`` in a boolean context, such as using
* **bool().** Testing a ``QuerySet`` in a boolean context, such as using
``bool()``, ``or``, ``and`` or an ``if`` statement, will cause the query
to be executed. If there is at least one result, the ``QuerySet`` is
``True``, otherwise ``False``. For example::
@ -411,7 +411,7 @@ Example::
A few subtleties that are worth mentioning:
* If you have a field called ``foo`` that is a
* If you have a field called ``foo`` that is a
:class:`~django.db.models.ForeignKey`, the default ``values()`` call
will return a dictionary key called ``foo_id``, since this is the name
of the hidden model attribute that stores the actual value (the ``foo``
@ -431,11 +431,11 @@ A few subtleties that are worth mentioning:
>>> Entry.objects.values('blog_id')
[{'blog_id': 1}, ...]
* When using ``values()`` together with :meth:`distinct()`, be aware that
* When using ``values()`` together with :meth:`distinct()`, be aware that
ordering can affect the results. See the note in :meth:`distinct` for
details.
* If you use a ``values()`` clause after an :meth:`extra()` call,
* If you use a ``values()`` clause after an :meth:`extra()` call,
any fields defined by a ``select`` argument in the :meth:`extra()` must
be explicitly included in the ``values()`` call. Any :meth:`extra()` call
made after a ``values()`` call will have its extra selected fields
@ -524,10 +524,10 @@ model.
``datetime.datetime`` object in the result list is "truncated" to the given
``type``.
* ``"year"`` returns a list of all distinct year values for the field.
* ``"month"`` returns a list of all distinct year/month values for the
* ``"year"`` returns a list of all distinct year values for the field.
* ``"month"`` returns a list of all distinct year/month values for the
field.
* ``"day"`` returns a list of all distinct year/month/day values for the
* ``"day"`` returns a list of all distinct year/month/day values for the
field.
``order``, which defaults to ``'ASC'``, should be either ``'ASC'`` or
@ -832,7 +832,8 @@ principle, so you should avoid them if possible.
Specify one or more of ``params``, ``select``, ``where`` or ``tables``. None
of the arguments is required, but you should use at least one of them.
* ``select``
* ``select``
The ``select`` argument lets you put extra fields in the ``SELECT``
clause. It should be a dictionary mapping attribute names to SQL
clauses to use to calculate that attribute.
@ -897,7 +898,8 @@ of the arguments is required, but you should use at least one of them.
tracking of parameters looks for ``%s`` and an escaped ``%`` character
like this isn't detected. That will lead to incorrect results.
* ``where`` / ``tables``
* ``where`` / ``tables``
You can define explicit SQL ``WHERE`` clauses — perhaps to perform
non-explicit joins — by using ``where``. You can manually add tables to
the SQL ``FROM`` clause by using ``tables``.
@ -934,7 +936,7 @@ of the arguments is required, but you should use at least one of them.
alias will be the same each time you construct the queryset in the same
way, so you can rely upon the alias name to not change.
* ``order_by``
* ``order_by``
If you need to order the resulting queryset using some of the new
fields or tables you have included via ``extra()`` use the ``order_by``
@ -956,7 +958,7 @@ of the arguments is required, but you should use at least one of them.
This shows, by the way, that you can make multiple calls to ``extra()``
and it will behave as you expect (adding new constraints each time).
* ``params``
* ``params``
The ``where`` parameter described above may use standard Python
database string placeholders — ``'%s'`` to indicate parameters the
@ -1304,11 +1306,11 @@ are)::
This has a number of caveats though:
* The model's ``save()`` method will not be called, and the ``pre_save`` and
``post_save`` signals will not be sent.
* It does not work with child models in a multi-table inheritance scenario.
* If the model's primary key is an :class:`~django.db.models.AutoField` it
does not retrieve and set the primary key attribute, as ``save()`` does.
* The model's ``save()`` method will not be called, and the ``pre_save`` and
``post_save`` signals will not be sent.
* It does not work with child models in a multi-table inheritance scenario.
* If the model's primary key is an :class:`~django.db.models.AutoField` it
does not retrieve and set the primary key attribute, as ``save()`` does.
count
~~~~~

6
docs/releases/1.0.txt
View File

@ -240,7 +240,7 @@ Caveats with support of certain databases
Django attempts to support as many features as possible on all database
backends. However, not all database backends are alike, and in particular many of the supported database differ greatly from version to version. It's a good idea to checkout our :doc:`notes on supported database </ref/databases>`:
- :ref:`mysql-notes`
- :ref:`sqlite-notes`
- :ref:`oracle-notes`
- :ref:`mysql-notes`
- :ref:`sqlite-notes`
- :ref:`oracle-notes`

34
docs/topics/auth.txt
View File

@ -14,10 +14,10 @@ Overview
The auth system consists of:
* Users
* Permissions: Binary (yes/no) flags designating whether a user may perform
* Users
* Permissions: Binary (yes/no) flags designating whether a user may perform
a certain task.
* Groups: A generic way of applying labels and permissions to more than one
* Groups: A generic way of applying labels and permissions to more than one
user.
Installation
@ -26,11 +26,11 @@ Installation
Authentication support is bundled as a Django application in
``django.contrib.auth``. To install it, do the following:
1. Put ``'django.contrib.auth'`` and ``'django.contrib.contenttypes'`` in
1. Put ``'django.contrib.auth'`` and ``'django.contrib.contenttypes'`` in
your :setting:`INSTALLED_APPS` setting.
(The :class:`~django.contrib.auth.models.Permission` model in
:mod:`django.contrib.auth` depends on :mod:`django.contrib.contenttypes`.)
2. Run the command ``manage.py syncdb``.
2. Run the command ``manage.py syncdb``.
Note that the default :file:`settings.py` file created by
:djadmin:`django-admin.py startproject <startproject>` includes
@ -715,27 +715,27 @@ Sent when a user logs in successfully.
Arguments sent with this signal:
``sender``
``sender``
As above: the class of the user that just logged in.
``request``
``request``
The current :class:`~django.http.HttpRequest` instance.
``user``
``user``
The user instance that just logged in.
.. data:: django.contrib.auth.signals.user_logged_out
Sent when the logout method is called.
``sender``
``sender``
As above: the class of the user that just logged out or ``None``
if the user was not authenticated.
``request``
``request``
The current :class:`~django.http.HttpRequest` instance.
``user``
``user``
The user instance that just logged out or ``None`` if the
user was not authenticated.
@ -1354,12 +1354,12 @@ code.
The Django admin site uses permissions as follows:
* Access to view the "add" form and add an object is limited to users with
* Access to view the "add" form and add an object is limited to users with
the "add" permission for that type of object.
* Access to view the change list, view the "change" form and change an
* Access to view the change list, view the "change" form and change an
object is limited to users with the "change" permission for that type of
object.
* Access to delete an object is limited to users with the "delete"
* Access to delete an object is limited to users with the "delete"
permission for that type of object.
Permissions are set globally per type of object, not per specific object
@ -1389,9 +1389,9 @@ Assuming you have an application with an
:attr:`~django.db.models.Options.app_label` ``foo`` and a model named ``Bar``,
to test for basic permissions you should use:
* add: ``user.has_perm('foo.add_bar')``
* change: ``user.has_perm('foo.change_bar')``
* delete: ``user.has_perm('foo.delete_bar')``
* add: ``user.has_perm('foo.add_bar')``
* change: ``user.has_perm('foo.change_bar')``
* delete: ``user.has_perm('foo.delete_bar')``
.. _custom-permissions:

42
docs/topics/templates.txt
View File

@ -129,7 +129,7 @@ them in the :ref:`built-in filter reference <ref-templates-builtins-filters>`.
To give you a taste of what's available, here are some of the more commonly
used template filters:
:tfilter:`default`
:tfilter:`default`
If a variable is false or empty, use given default. Otherwise, use the
value of the variable
@ -140,7 +140,7 @@ used template filters:
If ``value`` isn't provided or is empty, the above will display
"``nothing``".
:tfilter:`length`
:tfilter:`length`
Returns the length of the value. This works for both strings and lists;
for example::
@ -148,7 +148,7 @@ used template filters:
If ``value`` is ``['a', 'b', 'c', 'd']``, the output will be ``4``.
:tfilter:`striptags`
:tfilter:`striptags`
Strips all [X]HTML tags. For example::
{{ value|striptags }}
@ -183,7 +183,7 @@ them in the :ref:`built-in tag reference <ref-templates-builtins-tags>`. To give
you a taste of what's available, here are some of the more commonly used
tags:
:ttag:`for`
:ttag:`for`
Loop over each item in an array. For example, to display a list of athletes
provided in ``athlete_list``::
@ -193,7 +193,7 @@ tags:
{% endfor %}
</ul>
:ttag:`if` and ``else``
:ttag:`if` and ``else``
Evaluates a variable, and if that variable is "true" the contents of the
block are displayed::
@ -214,7 +214,7 @@ tags:
Athlete: {{ athlete_list.0.name }}
{% endif %}
:ttag:`block` and :ttag:`extends`
:ttag:`block` and :ttag:`extends`
Set up `template inheritance`_ (see below), a powerful way
of cutting down on "boilerplate" in templates.
@ -344,13 +344,13 @@ tag in a parent template is always used as a fallback.
You can use as many levels of inheritance as needed. One common way of using
inheritance is the following three-level approach:
* Create a ``base.html`` template that holds the main look-and-feel of your
* Create a ``base.html`` template that holds the main look-and-feel of your
site.
* Create a ``base_SECTIONNAME.html`` template for each "section" of your
* Create a ``base_SECTIONNAME.html`` template for each "section" of your
site. For example, ``base_news.html``, ``base_sports.html``. These
templates all extend ``base.html`` and include section-specific
styles/design.
* Create individual templates for each type of page, such as a news
* Create individual templates for each type of page, such as a news
article or blog entry. These templates extend the appropriate section
template.
@ -359,26 +359,26 @@ content areas, such as section-wide navigation.
Here are some tips for working with inheritance:
* If you use :ttag:`{% extends %}<extends>` in a template, it must be the first template
* If you use :ttag:`{% extends %}<extends>` in a template, it must be the first template
tag in that template. Template inheritance won't work, otherwise.
* More :ttag:`{% block %}<block>` tags in your base templates are better. Remember,
* More :ttag:`{% block %}<block>` tags in your base templates are better. Remember,
child templates don't have to define all parent blocks, so you can fill
in reasonable defaults in a number of blocks, then only define the ones
you need later. It's better to have more hooks than fewer hooks.
* If you find yourself duplicating content in a number of templates, it
* If you find yourself duplicating content in a number of templates, it
probably means you should move that content to a ``{% block %}`` in a
parent template.
* If you need to get the content of the block from the parent template,
* If you need to get the content of the block from the parent template,
the ``{{ block.super }}`` variable will do the trick. This is useful
if you want to add to the contents of a parent block instead of
completely overriding it. Data inserted using ``{{ block.super }}`` will
not be automatically escaped (see the `next section`_), since it was
already escaped, if necessary, in the parent template.
* For extra readability, you can optionally give a *name* to your
* For extra readability, you can optionally give a *name* to your
``{% endblock %}`` tag. For example::
{% block content %}
@ -437,25 +437,25 @@ do potentially bad things. This type of security exploit is called a
To avoid this problem, you have two options:
* One, you can make sure to run each untrusted variable through the
* One, you can make sure to run each untrusted variable through the
:tfilter:`escape` filter (documented below), which converts potentially
harmful HTML characters to unharmful ones. This was the default solution
in Django for its first few years, but the problem is that it puts the
onus on *you*, the developer / template author, to ensure you're escaping
everything. It's easy to forget to escape data.
* Two, you can take advantage of Django's automatic HTML escaping. The
* Two, you can take advantage of Django's automatic HTML escaping. The
remainder of this section describes how auto-escaping works.
By default in Django, every template automatically escapes the output
of every variable tag. Specifically, these five characters are
escaped:
* ``<`` is converted to ``&lt;``
* ``>`` is converted to ``&gt;``
* ``'`` (single quote) is converted to ``&#39;``
* ``"`` (double quote) is converted to ``&quot;``
* ``&`` is converted to ``&amp;``
* ``<`` is converted to ``&lt;``
* ``>`` is converted to ``&gt;``
* ``'`` (single quote) is converted to ``&#39;``
* ``"`` (double quote) is converted to ``&quot;``
* ``&`` is converted to ``&amp;``
Again, we stress that this behavior is on by default. If you're using Django's
template system, you're protected.