Context Navigation

Back to Ticket #9502

Ticket #9502: 9502-r9891.diff

File 9502-r9891.diff, 160.4 KB (added by Ramiro Morales, 15 years ago)
Patch for trunk updated to post r9890

docs/faq/admin.txt

diff --git a/docs/faq/admin.txt b/docs/faq/admin.txt

-              a
 sent out by Django doesn't match the domain in your browser. Try these two
 things:
     * Set the ``SESSION_COOKIE_DOMAIN`` setting in your admin config file
+    * Set the :setting:`SESSION_COOKIE_DOMAIN` setting in your admin config file
       to match your domain. For example, if you're going to
       "http://www.example.com/admin/" in your browser, in
       "myproject.settings" you should set ``SESSION_COOKIE_DOMAIN = 'www.example.com'``.
 …
       don't have dots in them. If you're running the admin site on "localhost"
       or another domain that doesn't have a dot in it, try going to
       "localhost.localdomain" or "127.0.0.1". And set
       ``SESSION_COOKIE_DOMAIN`` accordingly.
+      :setting:`SESSION_COOKIE_DOMAIN` accordingly.
 I can't log in. When I enter a valid username and password, it brings up the login page again, with a "Please enter a correct username and password" error.
 -----------------------------------------------------------------------------------------------------------------------------------------------------------
 …
 My "list_filter" contains a ManyToManyField, but the filter doesn't display.
 ----------------------------------------------------------------------------
 Django won't bother displaying the filter for a ``ManyToManyField`` if there
 are fewer than two related objects.
+Django won't bother displaying the filter for a :class:`ManyToManyField` if
+there are fewer than two related objects.
 For example, if your ``list_filter`` includes ``sites``, and there's only one
 site in your database, it won't display a "Site" filter. In that case,

docs/faq/models.txt

diff --git a/docs/faq/models.txt b/docs/faq/models.txt

-              a
 How can I see the raw SQL queries Django is running?
 ----------------------------------------------------
 Make sure your Django ``DEBUG`` setting is set to ``True``. Then, just do
+Make sure your Django :setting:`DEBUG` setting is set to ``True``. Then, just do
 this::
     >>> from django.db import connection
 …
     [{'sql': 'SELECT polls_polls.id,polls_polls.question,polls_polls.pub_date FROM polls_polls',
     'time': '0.002'}]
+``connection.queries`` is only available if ``DEBUG`` is ``True``. It's a list
+of dictionaries in order of query execution. Each dictionary has the following::
+:data:`connection.queries` is only available if :setting:`DEBUG` is ``True``.
+It's a list of dictionaries in order of query execution. Each dictionary has
+the following::
     ``sql`` -- The raw SQL statement
     ``time`` -- How long the statement took to execute, in seconds.
 ``connection.queries`` includes all SQL statements -- INSERTs, UPDATES,
+:data:`connection.queries` includes all SQL statements -- INSERTs, UPDATES,
 SELECTs, etc. Each time your app hits the database, the query will be recorded.
 Can I use Django with a pre-existing database?
 …
 Django isn't known to leak memory. If you find your Django processes are
 allocating more and more memory, with no sign of releasing it, check to make
 sure your ``DEBUG`` setting is set to ``False``. If ``DEBUG`` is ``True``, then
 Django saves a copy of every SQL statement it has executed.
+sure your :setting:`DEBUG` setting is set to ``False``. If ``DEBUG`` is
+``True``, then Django saves a copy of every SQL statement it has executed.
 (The queries are saved in ``django.db.connection.queries``. See
+(The queries are saved in :data:`django.db.connection.queries`. See
 `How can I see the raw SQL queries Django is running?`_.)
 To fix the problem, set ``DEBUG`` to ``False``.
+To fix the problem, set :setting:`DEBUG` to ``False``.
 If you need to clear the query list manually at any point in your functions,
 just call ``reset_queries()``, like this::
+just call :func:`reset_queries`, like this::
     from django import db
     db.reset_queries()

docs/howto/custom-file-storage.txt

diff --git a/docs/howto/custom-file-storage.txt b/docs/howto/custom-file-storage.txt

-              a
 **Required**.
 Called by ``Storage.open()``, this is the actual mechanism the storage class
+Called by :meth:`Storage.open`, this is the actual mechanism the storage class
 uses to open the file. This must return a ``File`` object, though in most cases,
 you'll want to return some subclass here that implements logic specific to the
 backend storage system.
 …
 ``_save(name, content)``
 ~~~~~~~~~~~~~~~~~~~~~~~~
 Called by ``Storage.save()``. The ``name`` will already have gone through
+``get_valid_name()`` and ``get_available_name()``, and the ``content`` will be a
 ``File`` object itself. No return value is expected.
+Called by :meth:`Storage.save`. The ``name`` will already have gone through
+:meth:`get_valid_name` and :meth:`get_available_name`, and the ``content`` will
+be a :class:`File` object itself. No return value is expected.
 ``get_valid_name(name)``
 ------------------------
 …
 server, after having any path information removed. Override this to customize
 how non-standard characters are converted to safe filenames.
 The code provided on ``Storage`` retains only alpha-numeric characters, periods
+and underscores from the original filename, removing everything else.
+The code provided on :class:`Storage` retains only alpha-numeric characters,
+periods and underscores from the original filename, removing everything else.n
 ``get_available_name(name)``
 ----------------------------
 …
 Returns a filename that is available in the storage mechanism, possibly taking
 the provided filename into account. The ``name`` argument passed to this method
 will have already cleaned to a filename valid for the storage system, according
 to the ``get_valid_name()`` method described above.
+to the :meth:`get_valid_name` method described above.
 The code provided on ``Storage`` simply appends underscores to the filename
+The code provided on :class:`Storage` simply appends underscores to the filename
 until it finds one that's available in the destination directory.

docs/howto/custom-management-commands.txt

diff --git a/docs/howto/custom-management-commands.txt b/docs/howto/custom-management-commands.txt

-              a
         views.py
 In this example, the ``explode`` command will be made available to any project
+that includes the ``blog`` application in ``settings.INSTALLED_APPS``.
+that includes the ``blog`` application in
+:setting:`settings.INSTALLED_APPS<INSTALLED_APPS>`.
 The ``explode.py`` module has only one requirement -- it must define a class
 called ``Command`` that extends ``django.core.management.base.BaseCommand``.
 For more details on how to define your own commands, look at the code for the
+existing ``django-admin.py`` commands, in ``/django/core/management/commands``.
+ No newline at end of file
+existing ``django-admin.py`` commands, in ``/django/core/management/commands``.

docs/howto/custom-model-fields.txt

diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt

-              a
 Alternatively, you may have a complex Python object that can somehow be
 serialized to fit into a standard database column type. This is another case
 where a ``Field`` subclass will help you use your object with your models.
+where a :class:`Field` subclass will help you use your object with your models.
 Our example object
 ------------------
 …
             self.east = east
             self.south = south
             self.west = west
         # ... (other possibly useful methods omitted) ...
 .. _Bridge: http://en.wikipedia.org/wiki/Contract_bridge
 …
       :class:`ForeignKey`). For advanced use only.
     * :attr:`~django.db.models.Field.default`
     * :attr:`~django.db.models.Field.editable`
     * :attr:`~django.db.models.Field.serialize`: If ``False``, the field will
+    * :attr:`~django.db.models.Field.serialize`: If ``False``, the field will
       not be serialized when the model is passed to Django's :ref:`serializers
       <topics-serialization>`. Defaults to ``True``.
     * :attr:`~django.db.models.Field.prepopulate_from`
 …
 If you aim to build a database-agnostic application, you should account for
 differences in database column types. For example, the date/time column type
 in PostgreSQL is called ``timestamp``, while the same column in MySQL is called
 ``datetime``. The simplest way to handle this in a ``db_type()`` method is to
 import the Django settings module and check the :setting:`DATABASE_ENGINE` setting.
 For example::
+``datetime``. The simplest way to handle this in a :meth:`db_type` method is to
+import the Django settings module and check the :setting:`DATABASE_ENGINE`
+setting. For example::
     class MyDateField(models.Field):
         def db_type(self):
 …
 .. method:: get_db_prep_save(self, value)
 Same as the above, but called when the Field value must be *saved* to the
 database. As the default implementation just calls ``get_db_prep_value``, you
+shouldn't need to implement this method unless your custom field need a special
+conversion when being saved that is not the same as the used for normal query
 parameters (which is implemented by ``get_db_prep_value``).
+database. As the default implementation just calls :meth:`get_db_prep_value`,
+you shouldn't need to implement this method unless your custom field need a
+special conversion when being saved that is not the same as the used for normal
+query parameters (which is implemented by :meth:`get_db_prep_value`).
 Preprocessing values before saving
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 …
 Prepares the ``value`` for passing to the database when used in a lookup (a
 ``WHERE`` constraint in SQL). The ``lookup_type`` will be one of the valid
+Django filter lookups: ``exact``, ``iexact``, ``contains``, ``icontains``,
+``gt``, ``gte``, ``lt``, ``lte``, ``in``, ``startswith``, ``istartswith``,
+``endswith``, ``iendswith``, ``range``, ``year``, ``month``, ``day``,
+``isnull``, ``search``, ``regex``, and ``iregex``.
+Django filter lookups: :lookup:`exact`, :lookup:`iexact`, :lookup:`contains`,
+:lookup:`icontains`, :lookup:`gt`, :lookup:`gte`, :lookup:`lt`, :lookup:`lte`,
+:lookup:`in`, :lookup:`startswith`, :lookup:`istartswith`, :lookup:`endswith`,
+:lookup:`iendswith`, :lookup:`range`, :lookup:`year`, :lookup:`month`,
+:lookup:`day`, :lookup:`isnull`, :lookup:`search`, :lookup:`regex`, and
+:lookup:`iregex`.
 Your method must be prepared to handle all of these ``lookup_type`` values and
 should raise either a ``ValueError`` if the ``value`` is of the wrong sort (a
 list when you were expecting an object, for example) or a ``TypeError`` if
+should raise either a :exc:`ValueError` if the ``value`` is of the wrong sort
+(a list when you were expecting an object, for example) or a ``TypeError`` if
 your field does not support that type of lookup. For many fields, you can get
 by with handling the lookup types that need special handling for your field
 and pass the rest of the :meth:`get_db_prep_lookup` method of the parent class.
+If you needed to implement ``get_db_prep_save()``, you will usually need to
+implement ``get_db_prep_lookup()``. If you don't, ``get_db_prep_value`` will be
+called by the default implementation, to manage ``exact``, ``gt``, ``gte``,
+``lt``, ``lte``, ``in`` and ``range`` lookups.
+If you needed to implement :meth:`get_db_prep_save`, you will usually need to
+implement :meth:`get_db_prep_lookup`. If you don't, :meth:`get_db_prep_value`
+will be called by the default implementation, to manage :lookup:`exact`,
+:lookup:`gt`, :lookup:`gte`, :lookup:`lt`, :lookup:`lte`, :lookup:`in` and
+:lookup:`range` lookups.
 You may also want to implement this method to limit the lookup types that could
 be used with your custom field type.
 Note that, for ``range`` and ``in`` lookups, ``get_db_prep_lookup`` will receive
+a list of objects (presumably of the right type) and will need to convert them
 to a list of things of the right type for passing to the database. Most of the
+time, you can reuse ``get_db_prep_value()``, or at least factor out some common
 pieces.
+Note that, for :lookup:`range` and :lookup:`in` lookups,
+:meth:`get_db_prep_lookup` will receive a list of objects (presumably of the
+right type) and will need to convert them to a list of things of the right type
+for passing to the database. Most of the time, you can reuse
+:meth:`get_db_prep_value`, or at least factor out some common pieces.
 For example, the following code implements ``get_db_prep_lookup`` to limit the
 accepted lookup types to ``exact`` and ``in``::
+For example, the following code implements :meth:`get_db_prep_lookup` to limit
+the accepted lookup types to :lookup:`exact` and ``in``::
     class HandField(models.Field):
         # ...
 …
 In addition to the above methods, fields that deal with files have a few other
 special requirements which must be taken into account. The majority of the
 mechanics provided by ``FileField``, such as controlling database storage and
 retrieval, can remain unchanged, leaving subclasses to deal with the challenge
 of supporting a particular type of file.
+mechanics provided by :class:`FileField`, such as controlling database storage
+and retrieval, can remain unchanged, leaving subclasses to deal with the
+challenge of supporting a particular type of file.
 Django provides a ``File`` class, which is used as a proxy to the file's
+Django provides a :class:`File` class, which is used as a proxy to the file's
 contents and operations. This can be subclassed to customize how the file is
 accessed, and what methods are available. It lives at
+``django.db.models.fields.files``, and its default behavior is explained in the
 :ref:`file documentation <ref-files-file>`.
+:mod:`django.db.models.fields.files`, and its default behavior is explained in
+the :ref:`file documentation <ref-files-file>`.
+Once a subclass of ``File`` is created, the new ``FileField`` subclass must be
+told to use it. To do so, simply assign the new ``File`` subclass to the special
+``attr_class`` attribute of the ``FileField`` subclass.
+Once a subclass of :class:`File` is created, the new :class:`FileField`
+subclass must be told to use it. To do so, simply assign the new :class:`File`
+subclass to the special :attr:`attr_class` attribute of the ``FileField``
+subclass.
 A few suggestions
 ------------------
 …
 In addition to the above details, there are a few guidelines which can greatly
 improve the efficiency and readability of the field's code.
 . The source for Django's own ``ImageField`` (in
+. The source for Django's own :class:`ImageField` (in
        ``django/db/models/fields/files.py``) is a great example of how to
        subclass ``FileField`` to support a particular type of file, as it
        incorporates all of the techniques described above.

docs/howto/custom-template-tags.txt

diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt

-              a
 the given Python module name, not the name of the app.
 To be a valid tag library, the module must contain a module-level variable
 named ``register`` that is a ``template.Library`` instance, in which all the
 tags and filters are registered. So, near the top of your module, put the
+named ``register`` that is a :class:`template.Library` instance, in which all
+the tags and filters are registered. So, near the top of your module, put the
 following::
     from django import template
 …
         return value.lower()
 This way, you'll be able to pass, say, an integer to this filter, and it
 won't cause an ``AttributeError`` (because integers don't have ``lower()``
+won't cause an :exc:`AttributeError` (because integers don't have ``lower()``
 methods).
 Registering custom filters
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 Once you've written your filter definition, you need to register it with
+your ``Library`` instance, to make it available to Django's template language::
+your :class:`Library` instance, to make it available to Django's templatei
+language::
     register.filter('cut', cut)
     register.filter('lower', lower)
 The ``Library.filter()`` method takes two arguments:
+The :meth:`Library.filter` method takes two arguments:
 . The name of the filter -- a string.
 . The compilation function -- a Python function (not the name of the
        function as a string).
 If you're using Python 2.4 or above, you can use ``register.filter()`` as a
+If you're using Python 2.4 or above, you can use :func:`register.filter` as a
 decorator instead::
     @register.filter(name='cut')
 …
       They're commonly used for output that contains raw HTML that is intended
       to be interpreted as-is on the client side.
       Internally, these strings are of type ``SafeString`` or ``SafeUnicode``.
       They share a common base class of ``SafeData``, so you can test
       for them using code like::
+      Internally, these strings are of type :class:`SafeString` ori
+      :class:`SafeUnicode`. They share a common base class of
+      :class:`SafeData`, so you can test for them using code like::
           if isinstance(value, SafeData):
               # Do something with the "safe" string.
 …
       These strings are only escaped once, however, even if auto-escaping
       applies.
       Internally, these strings are of type ``EscapeString`` or
       ``EscapeUnicode``. Generally you don't have to worry about these; they
       exist for the implementation of the ``escape`` filter.
+      Internally, these strings are of type :class:`EscapeString` or
+      :class:`EscapeUnicode`. Generally you don't have to worry about these;
+      they exist for the implementation of the ``escape`` filter.
 Template filter code falls into one of two situations:
 …
        introduce any possibility of unsafe HTML."
        The reason ``is_safe`` is necessary is because there are plenty of
        normal string operations that will turn a ``SafeData`` object back into
        a normal ``str`` or ``unicode`` object and, rather than try to catch
        them all, which would be very difficult, Django repairs the damage after
        the filter has completed.
+       normal string operations that will turn a :class:`SafeData` object back
+       into a normal ``str`` or ``unicode`` object and, rather than try to
+       catch tem all, which would be very difficult, Django repairs the damage
+       after the filter has completed.
        For example, suppose you have a filter that adds the string ``xx`` to the
        end of any input. Since this introduces no dangerous HTML characters to
 …
        ``autoescape`` keyword argument mean that our function will know whether
        automatic escaping is in effect when the filter is called. We use
        ``autoescape`` to decide whether the input data needs to be passed
        through ``django.utils.html.conditional_escape`` or not. (In the latter
        case, we just use the identity function as the "escape" function.) The
        ``conditional_escape()`` function is like ``escape()`` except it only
        escapes input that is **not** a ``SafeData`` instance. If a ``SafeData``
        instance is passed to ``conditional_escape()``, the data is returned
        unchanged.
+       through :func:`django.utils.html.conditional_escape` or not. (In the
+       latter case, we just use the identity function as the "escape"
+       function.) The :func:`conditional_escape` function is like
+       :func:`escape` except it only escapes input that is **not** a
+       :class:`SafeData` instance. If a ``SafeData`` instance is passed to
+       ``conditional_escape()``, the data is returned unchanged.
        Finally, in the above example, we remember to mark the result as safe
        so that our HTML is inserted directly into the template without further
 …
 how the compilation works and how the rendering works.
 When Django compiles a template, it splits the raw template text into
 ''nodes''. Each node is an instance of ``django.template.Node`` and has
 a ``render()`` method. A compiled template is, simply, a list of ``Node``
+''nodes''. Each node is an instance of :class:`django.template.Node` and has
+a ``render()`` method. A compiled template is, simply, a list of :class:`Node`
 objects. When you call ``render()`` on a compiled template object, the template
 calls ``render()`` on each ``Node`` in its node list, with the given context.
 The results are all concatenated together to form the output of the template.
 …
 .. _`strftime syntax`: http://docs.python.org/library/time.html#time.strftime
 The parser for this function should grab the parameter and create a ``Node``
 object::
+The parser for this function should grab the parameter and create a
+:class:`Node` object::
     from django import template
     def do_current_time(parser, token):
 …
     * ``token.contents`` is a string of the raw contents of the tag. In our
       example, it's ``'current_time "%Y-%m-%d %I:%M %p"'``.
     * The ``token.split_contents()`` method separates the arguments on spaces
+    * The :meth:`token.split_contents` method separates the arguments on spaces
       while keeping quoted strings together. The more straightforward
       ``token.contents.split()`` wouldn't be as robust, as it would naively
+      :func:`token.contents.split` wouldn't be as robust, as it would naively
       split on *all* spaces, including those within quoted strings. It's a good
       idea to always use ``token.split_contents()``.
+      idea to always use :meth:`token.split_contents`.
     * This function is responsible for raising
       ``django.template.TemplateSyntaxError``, with helpful messages, for
+      :exc:`django.template.TemplateSyntaxError`, with helpful messages, for
       any syntax error.
     * The ``TemplateSyntaxError`` exceptions use the ``tag_name`` variable.
+    * The :exc:`TemplateSyntaxError` exceptions use the ``tag_name`` variable.
       Don't hard-code the tag's name in your error messages, because that
       couples the tag's name to your function. ``token.contents.split()[0]``
       will ''always'' be the name of your tag -- even when the tag has no
 …
 Writing the renderer
 ~~~~~~~~~~~~~~~~~~~~
 The second step in writing custom tags is to define a ``Node`` subclass that
 has a ``render()`` method.
+The second step in writing custom tags is to define a :class:`Node` subclass
+that has a :meth:`render` method.
 Continuing the above example, we need to define ``CurrentTimeNode``::
 …
 Also, if your template tag creates a new context for performing some
 sub-rendering, set the auto-escape attribute to the current context's value.
 The ``__init__`` method for the ``Context`` class takes a parameter called
+The ``__init__`` method for the :class:`Context` class takes a parameter called
 ``autoescape`` that you can use for this purpose. For example::
     def render(self, context):
 …
 Registering the tag
 ~~~~~~~~~~~~~~~~~~~
 Finally, register the tag with your module's ``Library`` instance, as explained
 in "Writing custom template filters" above. Example::
+Finally, register the tag with your module's :class:`Library` instance, as
+explained in "Writing custom template filters" above. Example::
     register.tag('current_time', do_current_time)
 …
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Although you can pass any number of arguments to a template tag using
 ``token.split_contents()``, the arguments are all unpacked as
+:meth:`token.split_contents`, the arguments are all unpacked as
 string literals. A little more work is required in order to pass dynamic
 content (a template variable) to a template tag as an argument.
 While the previous examples have formatted the current time into a string and
 returned the string, suppose you wanted to pass in a ``DateTimeField`` from an
 object and have the template tag format that date-time:
+returned the string, suppose you wanted to pass in a :class:`DateTimeField`
+from an object and have the template tag format that date-time:
 .. code-block:: html+django
     <p>This post was last updated at {% format_time blog_entry.date_updated "%Y-%m-%d %I:%M %p" %}.</p>
 Initially, ``token.split_contents()`` will return three values:
+Initially, :meth:`token.split_contents` will return three values:
 . The tag name ``format_time``.
 . The string "blog_entry.date_updated" (without the surrounding quotes).
 …
 .. versionchanged:: 1.0
     Variable resolution has changed in the 1.0 release of Django. ``template.resolve_variable()``
     has been deprecated in favor of a new ``template.Variable`` class.
+    has been deprecated in favor of a new :class:`template.Variable` class.
 You also have to change the renderer to retrieve the actual contents of the
 ``date_updated`` property of the ``blog_entry`` object.  This can be
 accomplished by using the ``Variable()`` class in ``django.template``.
+accomplished by using the :class:`Variable` class in :mod:`django.template`.
 To use the ``Variable`` class, simply instantiate it with the name of the
+To use the :class:`Variable` class, simply instantiate it with the name of the
 variable to be resolved, and then call ``variable.resolve(context)``. So,
 for example::
 …
             except template.VariableDoesNotExist:
                 return ''
 Variable resolution will throw a ``VariableDoesNotExist`` exception if it cannot
 resolve the string passed to it in the current context of the page.
+Variable resolution will throw a :exc:`VariableDoesNotExist` exception if it
+cannot resolve the string passed to it in the current context of the page.
 Shortcut for simple tags
 ~~~~~~~~~~~~~~~~~~~~~~~~
 Many template tags take a number of arguments -- strings or a template variables
 -- and return a string after doing some processing based solely on
+Many template tags take a number of arguments -- strings or a template
+variables -- and return a string after doing some processing based solely on
 the input argument and some external information. For example, the
 ``current_time`` tag we wrote above is of this variety: we give it a format
 string, it returns the time as a string.
 To ease the creation of the types of tags, Django provides a helper function,
 ``simple_tag``. This function, which is a method of
 ``django.template.Library``, takes a function that accepts any number of
+:class:`django.template.Library`, takes a function that accepts any number of
 arguments, wraps it in a ``render`` function and the other necessary bits
 mentioned above and registers it with the template system.
 …
 Another common type of template tag is the type that displays some data by
 rendering *another* template. For example, Django's admin interface uses custom
 template tags to display the buttons along the bottom of the "add/change" form
 pages. Those buttons always look the same, but the link targets change depending
+on the object being edited -- so they're a perfect case for using a small
+template that is filled with details from the current object. (In the admin's
 case, this is the ``submit_row`` tag.)
+pages. Those buttons always look the same, but the link targets change
+depending on the object being edited -- so they're a perfect case for using a
+small template that is filled with details from the current object. (In the
+admin's case, this is the ``submit_row`` tag.)
 These sorts of tags are called "inclusion tags".
 …
     </ul>
 Now, create and register the inclusion tag by calling the ``inclusion_tag()``
 method on a ``Library`` object. Following our example, if the above template is
+in a file called ``results.html`` in a directory that's searched by the template
 loader, we'd register the tag like this::
+method on a :class:`Library` object. Following our example, if the above
+template is in a file called ``results.html`` in a directory that's searched by
+the template loader, we'd register the tag like this::
     # Here, register is a django.template.Library instance, as before
     register.inclusion_tag('results.html')(show_results)
 …
 (Note that the first parameter to the function *must* be called ``context``.)
 In that ``register.inclusion_tag()`` line, we specified ``takes_context=True``
+and the name of the template. Here's what the template ``link.html`` might look
 like:
+In that :func:`register.inclusion_tag` line, we specified
+``takes_context=True`` and the name of the template. Here's what the template
+``link.html`` might look like:
 .. code-block:: html+django
 …
             return ''
 ``parser.parse()`` takes a tuple of names of block tags ''to parse until''. It
 returns an instance of ``django.template.NodeList``, which is a list of
 all ``Node`` objects that the parser encountered ''before'' it encountered
+returns an instance of :class:`django.template.NodeList`, which is a list of
+all :class:`Node` objects that the parser encountered ''before'' it encountered
 any of the tags named in the tuple.
 In ``"nodelist = parser.parse(('endcomment',))"`` in the above example,
 …
 After ``parser.parse()`` is called, the parser hasn't yet "consumed" the
 ``{% endcomment %}`` tag, so the code needs to explicitly call
 ``parser.delete_first_token()``.
+:func:`parser.delete_first_token`.
 ``CommentNode.render()`` simply returns an empty string. Anything between
 ``{% comment %}`` and ``{% endcomment %}`` is ignored.

docs/howto/deployment/fastcgi.txt

diff --git a/docs/howto/deployment/fastcgi.txt b/docs/howto/deployment/fastcgi.txt

-              a
 In the cases where Django cannot work out the prefix correctly and where you
 want the original value to be used in URLs, you can set the
 ``FORCE_SCRIPT_NAME`` setting in your main ``settings`` file. This sets the
+:setting:`FORCE_SCRIPT_NAME` setting in your main ``settings`` file. This sets the
 script name uniformly for every URL served via that settings file. Thus you'll
 need to use different settings files if you want different sets of URLs to
 have different script names in this case, but that is a rare situation.

docs/howto/static-files.txt

diff --git a/docs/howto/static-files.txt b/docs/howto/static-files.txt

-              a
 This code is straightforward. It imports the settings and checks the value of
 the :setting:`DEBUG` setting. If it evaluates to ``True``, then ``site_media``
 will be associated with the ``django.views.static.serve`` view. If not, then the
+will be associated with the :func:`django.views.static.serve` view. If not, then the
 view won't be made available.
 Of course, the catch here is that you'll have to remember to set ``DEBUG=False``

docs/internals/contributing.txt

diff --git a/docs/internals/contributing.txt b/docs/internals/contributing.txt

-              a
     ./runtests.py --settings=path.to.django.settings
 Yes, the unit tests need a settings module, but only for database connection
 info, with the ``DATABASE_ENGINE`` setting.
+info, with the :setting:`DATABASE_ENGINE` setting.
 If you're using the ``sqlite3`` database backend, no further settings are
 needed. A temporary database will be created in memory when running the tests.
 …
 You will also need to ensure that your database uses UTF-8 as the default
 character set. If your database server doesn't use UTF-8 as a default charset,
 you will need to include a value for ``TEST_DATABASE_CHARSET`` in your settings
+you will need to include a value for :setting:`TEST_DATABASE_CHARSET` in your settings
 file.
 If you want to run the full suite of tests, you'll need to install a number of

docs/intro/tutorial01.txt

diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt

-              a
 create a ``mysite`` directory in your current directory.
 .. admonition:: Mac OS X permissions
    If you're using Mac OS X, you may see the message "permission denied" when
    you try to run ``django-admin.py startproject``. This is because, on
    Unix-based systems like OS X, a file must be marked as "executable" before it
    can be run as a program. To do this, open Terminal.app and navigate (using
    the ``cd`` command) to the directory where :ref:`django-admin.py
    <ref-django-admin>` is installed, then run the command
+   <ref-django-admin>` is installed, then run the command
    ``chmod +x django-admin.py``.
 .. note::
 …
     * :file:`__init__.py`: An empty file that tells Python that this directory
       should be considered a Python package. (Read `more about packages`_ in the
       official Python docs if you're a Python beginner.)
     * :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
       :file:`manage.py` in :ref:`ref-django-admin`.
     * :file:`settings.py`: Settings/configuration for this Django project.
       :ref:`topics-settings` will tell you all about how settings work.
     * :file:`urls.py`: The URL declarations for this Django project; a "table of
       contents" of your Django-powered site. You can read more about URLs in
       :ref:`topics-http-urls`.
 …
     on port 8000. If you want to change the server's port, pass it as a
     command-line argument. For instance, this command starts the server on port
 :
     .. code-block:: bash
         python manage.py runserver 8080
 …
     * :setting:`DATABASE_ENGINE` -- Either 'postgresql_psycopg2', 'mysql' or
       'sqlite3'. Other backends are :setting:`also available <DATABASE_ENGINE>`.
     * :setting:`DATABASE_NAME` -- The name of your database. If you're using
       SQLite, the database will be a file on your computer; in that case,
+      ``DATABASE_NAME`` should be the full absolute path, including filename, of
+      that file. If the file doesn't exist, it will automatically be created
+      when you synchronize the database for the first time (see below).
+      When specifying the path, always use forward slashes, even on Windows
+      :setting:`DATABASE_NAME` should be the full absolute path, including
+      filename, of that file. If the file doesn't exist, it will automatically
+      be created when you synchronize the database for the first time (see
+      below).
+      When specifying the path, always use forward slashes, even on Windows
       (e.g. ``C:/homes/user/mysite/sqlite3.db``).
     * :setting:`DATABASE_USER` -- Your database username (not used for SQLite).
     * :setting:`DATABASE_PASSWORD` -- Your database password (not used for
       SQLite).
     * :setting:`DATABASE_HOST` -- The host your database is on. Leave this as an
       empty string if your database server is on the same physical machine (not
       used for SQLite).
 …
 prompt, but also because objects' representations are used throughout Django's
 automatically-generated admin.
 .. admonition:: Why :meth:`~django.db.models.Model.__unicode__` and not
+.. admonition:: Why :meth:`~django.db.models.Model.__unicode__` and not
                 :meth:`django.db.models.Model.__str__`?
     If you're familiar with Python, you might be in the habit of adding

docs/misc/api-stability.txt

diff --git a/docs/misc/api-stability.txt b/docs/misc/api-stability.txt

-              a
    - All the public APIs -- everything documented in the linked documents below,
      and all methods that don't begin with an underscore -- will not be moved or
      renamed without providing backwards-compatible aliases.
    - If new features are added to these APIs -- which is quite possible --
      they will not break or change the meaning of existing methods. In other
      words, "stable" does not (necessarily) mean "complete."
    - If, for some reason, an API declared stable must be removed or replaced, it
      will be declared deprecated but will remain in the API for at least two
      minor version releases. Warnings will be issued when the deprecated method
      is called.
      See :ref:`official-releases` for more details on how Django's version
      numbering scheme works, and how features will be deprecated.
    - We'll only break backwards compatibility of these APIs if a bug or
      security hole makes it completely unavoidable.
 …
     - :ref:`Authorization <topics-auth>`
     - :ref:`Caching <topics-cache>`.
     - :ref:`Model definition, managers, querying and transactions
       <topics-db-index>`
     - :ref:`Sending e-mail <topics-email>`.
     - :ref:`File handling and storage <topics-files>`
     - :ref:`Forms <topics-forms-index>`
     - :ref:`HTTP request/response handling <topics-http-index>`, including file
       uploads, middleware, sessions, URL resolution, view, and shortcut APIs.
     - :ref:`Generic views <topics-http-generic-views>`.
     - :ref:`Internationalization <topics-i18n>`.
     - :ref:`Pagination <topics-pagination>`
     - :ref:`Serialization <topics-serialization>`
     - :ref:`Signals <topics-signals>`
     - :ref:`Templates <topics-templates>`, including the language, Python-level
       :ref:`template APIs <ref-templates-index>`, and :ref:`custom template tags
       and libraries <howto-custom-template-tags>`. We may add new template
       tags in the future and the names may inadvertently clash with
       external template tags. Before adding any such tags, we'll ensure that
       Django raises an error if it tries to load tags with duplicate names.
     - :ref:`Testing <topics-testing>`
     - :ref:`django-admin utility <ref-django-admin>`.
     - :ref:`Built-in middleware <ref-middleware>`
     - :ref:`Request/response objects <ref-request-response>`.
     - :ref:`Settings <ref-settings>`. Note, though that while the :ref:`list of
       built-in settings <ref-settings>` can be considered complete we may -- and
       probably will -- add new settings in future versions. This is one of those
       places where "'stable' does not mean 'complete.'"
     - :ref:`Built-in signals <ref-signals>`. Like settings, we'll probably add
       new signals in the future, but the existing ones won't break.
     - :ref:`Unicode handling <ref-unicode>`.
     - Everything covered by the :ref:`HOWTO guides <howto-index>`.
 ``django.utils``
 ----------------
+Most of the modules in ``django.utils`` are designed for internal use. Only the following parts of ``django.utils`` can be considered stable:
+Most of the modules in :mod:`django.utils` are designed for internal use. Only
+the following parts of :mod:`django.utils` can be considered stable:
     - ``django.utils.cache``
     - ``django.utils.datastructures.SortedDict`` -- only this single class; the
       rest of the module is for internal use.
     - ``django.utils.encoding``
     - ``django.utils.feedgenerator``
     - ``django.utils.http``
     - ``django.utils.safestring``
     - ``django.utils.translation``
     - ``django.utils.tzinfo``
+    - :mod:`django.utils.cache`
+    - :class:`django.utils.datastructures.SortedDict` -- only this single
+      class; the rest of the module is for internal use.
+    - :mod:`django.utils.encoding`
+    - :mod:`django.utils.feedgenerator`
+    - :mod:`django.utils.http`
+    - :mod:`django.utils.safestring`
+    - :mod:`django.utils.translation`
+    - :mod:`django.utils.tzinfo`
 Exceptions
 ==========
 …
 If we become aware of a security problem -- hopefully by someone following our
 :ref:`security reporting policy <reporting-security-issues>` -- we'll do
+everything necessary to fix it. This might mean breaking backwards compatibility; security trumps the compatibility guarantee.
+everything necessary to fix it. This might mean breaking backwards
+compatibility; security trumps the compatibility guarantee.
 Contributed applications (``django.contrib``)
 ---------------------------------------------
 …
 releases. As the web evolves, Django must evolve with it.
 However, any changes to contrib apps will come with an important guarantee:
+we'll make sure it's always possible to use an older version of a contrib app if
+we need to make changes. Thus, if Django 1.5 ships with a backwards-incompatible
+``django.contrib.flatpages``, we'll make sure you can still use the Django 1.4
+version alongside Django 1.5. This will continue to allow for easy upgrades.
+we'll make sure it's always possible to use an older version of a contrib app
+if we need to make changes. Thus, if Django 1.5 ships with a
+backwards-incompatible ``django.contrib.flatpages``, we'll make sure you can
+still use the Django 1.4 version alongside Django 1.5. This will continue to
+allow for easy upgrades.
+Historically, apps in ``django.contrib`` have been more stable than the core, so
+in practice we probably won't have to ever make this exception. However, it's
+worth noting if you're building apps that depend on ``django.contrib``.
+Historically, apps in :mod:`django.contrib` have been more stable than the
+core, so in practice we probably won't have to ever make this exception.
+However, it's worth noting if you're building apps that depend on
+:mod:`django.contrib`.
 APIs marked as internal
 -----------------------
 …
     - Some documentation refers to internals and mentions them as such. If the
       documentation says that something is internal, we reserve the right to
       change it.
     - Functions, methods, and other objects prefixed by a leading underscore
       (``_``). This is the standard Python way of indicating that something is
       private; if any method starts with a single ``_``, it's an internal API.

docs/misc/design-philosophies.txt

diff --git a/docs/misc/design-philosophies.txt b/docs/misc/design-philosophies.txt

-              a
     The `discussion of DRY on the Portland Pattern Repository`__
     __ http://c2.com/cgi/wiki?DontRepeatYourself
 .. _explicit-is-better-than-implicit:
 Explicit is better than implicit
 …
 This is why developers need to call ``save()`` explicitly, rather than the
 framework saving things behind the scenes silently.
 This is also why the ``select_related()`` ``QuerySet`` method exists. It's an
 optional performance booster for the common case of selecting "every related
+This is also why the ``select_related()`` :class:`QuerySet` method exists. It's
+an optional performance booster for the common case of selecting "every related
 object."
 Terse, powerful syntax

docs/ref/contrib/admin.txt

diff --git a/docs/ref/contrib/admin.txt b/docs/ref/contrib/admin.txt

-              a
 There are five steps in activating the Django admin site:
 . Add ``django.contrib.admin`` to your ``INSTALLED_APPS`` setting.
+. Add ``django.contrib.admin`` to your :setting:`INSTALLED_APPS` setting.
 . Determine which of your application's models should be editable in the
        admin interface.
 …
 dictionary of information about the fieldset, including a list of fields to be
 displayed in it.
+A full example, taken from the ``django.contrib.flatpages.FlatPage`` model::
+A full example, taken from the :class:`django.contrib.flatpages.FlatPage`
+model::
     class FlatPageAdmin(admin.ModelAdmin):
         fieldsets = (
 …
 Use this option as an alternative to ``fieldsets`` if the layout does not
 matter and if you want to only show a subset of the available fields in the
 form. For example, you could define a simpler version of the admin form for
 the ``django.contrib.flatpages.FlatPage`` model as follows::
+the :class:`django.contrib.flatpages.FlatPage` model as follows::
     class FlatPageAdmin(admin.ModelAdmin):
         fields = ('url', 'title', 'content')
 …
 field should be either a ``BooleanField``, ``CharField``, ``DateField``,
 ``DateTimeField``, ``IntegerField`` or ``ForeignKey``.
 This example, taken from the ``django.contrib.auth.models.User`` model, shows
 how both ``list_display`` and ``list_filter`` work::
+This example, taken from the :class:`django.contrib.auth.models.User` model,
+shows how both ``list_display`` and ``list_filter`` work::
     class UserAdmin(admin.ModelAdmin):
         list_display = ('username', 'email', 'first_name', 'last_name', 'is_staff')
 …
         radio_fields = {"group": admin.VERTICAL}
 You have the choice of using ``HORIZONTAL`` or ``VERTICAL`` from the
 ``django.contrib.admin`` module.
+:mod:`django.contrib.admin` module.
 Don't include a field in ``radio_fields`` unless it's a ``ForeignKey`` or has
 ``choices`` set.
 …
+            }
             js = ("my_code.js",)
 Keep in mind that this will be prepended with ``MEDIA_URL``. The same rules
 apply as :ref:`regular media definitions on forms <topics-forms-media>`.
+Keep in mind that this will be prepended with :setting:`MEDIA_URL`. The same
+rules apply as :ref:`regular media definitions on forms <topics-forms-media>`.
 Adding custom validation to the admin
 -------------------------------------
 …
 If you want to allow editing and creating ``Image`` instance on the ``Product``
 add/change views you can simply use ``GenericInlineModelAdmin`` provided by
 ``django.contrib.contenttypes.generic``. In your ``admin.py`` for this
+:mod:`django.contrib.contenttypes.generic`. In your ``admin.py`` for this
 example app::
     from django.contrib import admin
 …
     admin.site.register(Product, ProductAdmin)
+``django.contrib.contenttypes.generic`` provides both a ``GenericTabularInline``
+and ``GenericStackedInline`` and behave just like any other inline. See the
+:mod:`django.contrib.contenttypes.generic` provides both a
+``GenericTabularInline`` and ``GenericStackedInline`` and behave just like any
+other inline. See the
 :ref:`contenttypes documentation <ref-contrib-contenttypes>` for more specific
 information.
 …
 ==========================
 It is relatively easy to override many of the templates which the admin module
 uses to generate the various pages of an admin site. You can even override a few
 of these templates for a specific app, or a specific model.
+uses to generate the various pages of an admin site. You can even override a
+few of these templates for a specific app, or a specific model.
 Set up your projects admin template directories
 -----------------------------------------------
 …
 The admin template files are located in the ``contrib/admin/templates/admin``
 directory.
 In order to override one or more of them, first create an ``admin`` directory in
+your project's ``templates`` directory. This can be any of the directories you
 specified in ``TEMPLATE_DIRS``.
+In order to override one or more of them, first create an ``admin`` directory
+in your project's ``templates`` directory. This can be any of the directories
+you specified in :setting:`TEMPLATE_DIRS`.
 Within this ``admin`` directory, create sub-directories named after your app.
 Within these app subdirectories create sub-directories named after your models.
 Note, that the admin app will lowercase the model name when looking for the
 directory, so make sure you name the directory in all lowercase if you are going
 to run your app on a case-sensitive filesystem.
+directory, so make sure you name the directory in all lowercase if you are
+going to run your app on a case-sensitive filesystem.
 To override an admin template for a specific app, copy and edit the template
 from the ``django/contrib/admin/templates/admin`` directory, and save it to one
 …
 necessary nor advisable to replace an entire template. It is almost always
 better to override only the section of the template which you need to change.
 To continue the example above, we want to add a new link next to the ``History``
+tool for the ``Page`` model. After looking at ``change_form.html`` we determine
+that we only need to override the ``object-tools`` block. Therefore here is our
 new ``change_form.html`` :
+To continue the example above, we want to add a new link next to the
+``History`` tool for the ``Page`` model. After looking at ``change_form.html``
+we determine that we only need to override the ``object-tools`` block.
+Therefore here is our new ``change_form.html``:
 .. code-block:: html+django
 …
     Some of the admin templates, such as ``change_list_request.html`` are used
     to render custom inclusion tags. These may be overridden, but in such cases
+    you are probably better off creating your own version of the tag in question
+    and giving it a different name. That way you can use it selectively.
+    you are probably better off creating your own version of the tag in
+    question and giving it a different name. That way you can use it
+    selectively.
 Root and login templates
 ------------------------
 If you wish to change the index or login templates, you are better off creating
 your own ``AdminSite`` instance (see below), and changing the ``index_template``
 or ``login_template`` properties.
+your own ``AdminSite`` instance (see below), and changing the
+``index_template`` or ``login_template`` properties.
 ``AdminSite`` objects
 =====================
 A Django administrative site is represented by an instance of
 ``django.contrib.admin.sites.AdminSite``; by default, an instance of
+:class:`django.contrib.admin.sites.AdminSite`; by default, an instance of
 this class is created as ``django.contrib.admin.site`` and you can
 register your models and ``ModelAdmin`` instances with it.
 …
+    )
 Above we used ``admin.autodiscover()`` to automatically load the
 ``INSTALLED_APPS`` admin.py modules.
+:setting:`INSTALLED_APPS` admin.py modules.
 In this example, we register the ``AdminSite`` instance
 ``myproject.admin.admin_site`` at the URL ``/myadmin/`` ::

docs/ref/contrib/index.txt

diff --git a/docs/ref/contrib/index.txt b/docs/ref/contrib/index.txt

-              a
     For most of these add-ons -- specifically, the add-ons that include either
     models or template tags -- you'll need to add the package name (e.g.,
     ``'django.contrib.admin'``) to your ``INSTALLED_APPS`` setting and re-run
     ``manage.py syncdb``.
+    ``'django.contrib.admin'``) to your :setting:`INSTALLED_APPS` setting and
+    re-run ``manage.py syncdb``.
 .. _"batteries included" philosophy: http://docs.python.org/tut/node12.html#batteries-included
 …
 ===========
 A collection of various Django snippets that are useful only for a particular
 country or culture. For example, ``django.contrib.localflavor.us.forms``
+country or culture. For example, :mod:`django.contrib.localflavor.us.forms`
 contains a ``USZipCodeField`` that you can use to validate U.S. zip codes.
 See the :ref:`localflavor documentation <ref-contrib-localflavor>`.

docs/ref/contrib/localflavor.txt

diff --git a/docs/ref/contrib/localflavor.txt b/docs/ref/contrib/localflavor.txt

-              a
     * `United Kingdom`_
     * `United States of America`_
 The ``django.contrib.localflavor`` package also includes a ``generic`` subpackage,
 containing useful code that is not specific to one particular country or
 culture. Currently, it defines date and datetime input fields based on those
+from :ref:`forms <topics-forms-index>`, but with non-US default formats.
 Here's an example of how to use them::
+The :mod:`django.contrib.localflavor` package also includes a ``generic``
+subpackage, containing useful code that is not specific to one particular
+country or culture. Currently, it defines date and datetime input fields based
+on those from :ref:`forms <topics-forms-index>`, but with non-US default
+formats. Here's an example of how to use them::
     from django import forms
     from django.contrib.localflavor import generic
 …
 .. class:: ar.forms.ARPostalCodeField
     A form field that validates input as either a classic four-digit Argentinian
     postal code or a CPA_.
+    A form field that validates input as either a classic four-digit
+    Argentinian postal code or a CPA_.
 .. _CPA: http://www.correoargentino.com.ar/consulta_cpa/home.php
 .. class:: ar.forms.ARDNIField
     A form field that validates input as a Documento Nacional de Identidad (DNI)
     number.
+    A form field that validates input as a Documento Nacional de Identidad
+    (DNI) number.
 .. class:: ar.forms.ARCUITField
 …
 .. class:: au.forms.AUPhoneNumberField
     A form field that validates input as an Australian phone number. Valid numbers
     have ten digits.
+    A form field that validates input as an Australian phone number. Valid
+    numbers have ten digits.
 .. class:: au.forms.AUStateSelect
     A ``Select`` widget that uses a list of Australian states/territories as its
     choices.
+    A ``Select`` widget that uses a list of Australian states/territories as
+    its choices.
 Austria (``at``)
 ================
 …
 .. class:: at.forms.ATStateSelect
     A ``Select`` widget that uses a list of Austrian states as its choices.
+    A ``Select`` widget that uses a list of Austrian states as its choices.
 .. class:: at.forms.ATSocialSecurityNumberField
+    A form field that validates its input as an Austrian social security number.
+    A form field that validates its input as an Austrian social security
+    number.
 Brazil (``br``)
 ===============
 .. class:: br.forms.BRPhoneNumberField
     A form field that validates input as a Brazilian phone number, with the format
     XX-XXXX-XXXX.
+    A form field that validates input as a Brazilian phone number, with the
+    format XX-XXXX-XXXX.
 .. class:: br.forms.BRZipCodeField
 …
 .. class:: ca.forms.CAPhoneNumberField
     A form field that validates input as a Canadian phone number, with the format
     XXX-XXX-XXXX.
+    A form field that validates input as a Canadian phone number, with the
+    format XXX-XXX-XXXX.
 .. class:: ca.forms.CAPostalCodeField
     A form field that validates input as a Canadian postal code, with the format
     XXX XXX.
+    A form field that validates input as a Canadian postal code, with the
+    format XXX XXX.
 .. class:: ca.forms.CAProvinceField
+    A form field that validates input as a Canadian province name or abbreviation.
+    A form field that validates input as a Canadian province name or
+    abbreviation.
 .. class:: ca.forms.CASocialInsuranceNumberField
     A form field that validates input as a Canadian Social Insurance Number (SIN).
     A valid number must have the format XXX-XXX-XXX and pass a `Luhn mod-10
     checksum`_.
+    A form field that validates input as a Canadian Social Insurance Number
+    (SIN). A valid number must have the format XXX-XXX-XXX and pass a
+    `Luhn mod-10 checksum`_.
 .. _Luhn mod-10 checksum: http://en.wikipedia.org/wiki/Luhn_algorithm
 .. class:: ca.forms.CAProvinceSelect
     A ``Select`` widget that uses a list of Canadian provinces and territories as
     its choices.
+    A ``Select`` widget that uses a list of Canadian provinces and territories
+    as its choices.
 Chile (``cl``)
 ==============
 .. class:: cl.forms.CLRutField
     A form field that validates input as a Chilean national identification number
     ('Rol Unico Tributario' or RUT). The valid format is XX.XXX.XXX-X.
+    A form field that validates input as a Chilean national identification
+    number ('Rol Unico Tributario' or RUT). The valid format is XX.XXX.XXX-X.
 .. class:: cl.forms.CLRegionSelect
 …
 .. class:: jp.forms.JPPrefectureSelect
+    A ``Select`` widget that uses a list of Japanese prefectures as its choices.
+    A ``Select`` widget that uses a list of Japanese prefectures as its
+    choices.
 Mexico (``mx``)
 ===============
 …
 .. class:: no.forms.NOMunicipalitySelect
     A ``Select`` widget that uses a list of Norwegian municipalities (fylker) as
     its choices.
+    A ``Select`` widget that uses a list of Norwegian municipalities (fylker)
+    as its choices.
 Peru (``pe``)
 =============
 …
 .. class:: pt.forms.PEDepartmentSelect
+    A ``Select`` widget that uses a list of Peruvian Departments as its choices.
+    A ``Select`` widget that uses a list of Peruvian Departments as its
+    choices.
 Poland (``pl``)
 ===============
 .. class:: pl.forms.PLNationalIdentificationNumberField
     A form field that validates input as a Polish national identification number
     (PESEL_).
+    A form field that validates input as a Polish national identification
+    number (PESEL_).
 .. _PESEL: http://en.wikipedia.org/wiki/PESEL
 …
     A form field that validates its input as a Romanian county (judet) name or
     abbreviation. It normalizes the input to the standard vehicle registration
     abbreviation for the given county. This field will only accept names written
     with diacritics; consider using ROCountySelect as an alternative.
+    abbreviation for the given county. This field will only accept names
+    written with diacritics; consider using ROCountySelect as an alternative.
 .. class:: ro.forms.ROCountySelect
 …
 .. class:: ro.forms.ROIBANField
     A form field that validates its input as a Romanian International Bank
+    A form field that validates its input as a Romanian International Bank
     Account Number (IBAN). The valid format is ROXX-XXXX-XXXX-XXXX-XXXX-XXXX,
     with or without hyphens.
 …
 .. class:: us.models.PhoneNumberField
     A :class:`CharField` that checks that the value is a valid U.S.A.-style phone
     number (in the format ``XXX-XXX-XXXX``).
+    A :class:`CharField` that checks that the value is a valid U.S.A.-style
+    phone number (in the format ``XXX-XXX-XXXX``).
 .. class:: us.models.USStateField

docs/ref/contrib/webdesign.txt

diff --git a/docs/ref/contrib/webdesign.txt b/docs/ref/contrib/webdesign.txt

-              a
    :synopsis: Helpers and utilities targeted primarily at Web *designers*
               rather than Web *developers*.
 The ``django.contrib.webdesign`` package, part of the
+The :mod:`django.contrib.webdesign` package, part of the
 :ref:`"django.contrib" add-ons <ref-contrib-index>`, provides various Django
 helpers that are particularly useful to Web *designers* (as opposed to
 developers).

docs/ref/databases.txt

diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt

-              a
 non-unique) with the default collation.
 In many cases, this default will not be a problem. However, if you really want
 case-sensitive comparisons on a particular column or table, you would change
+the column or table to use the ``utf8_bin`` collation. The main thing to be
 aware of in this case is that if you are using MySQLdb 1.2.2, the database backend in Django will then return
+bytestrings (instead of unicode strings) for any character fields it returns
+receive from the database. This is a strong variation from Django's normal
+practice of *always* returning unicode strings. It is up to you, the
+developer, to handle the fact that you will receive bytestrings if you
+configure your table(s) to use ``utf8_bin`` collation. Django itself should work
+smoothly with such columns, but if your code must be prepared to call
+``django.utils.encoding.smart_unicode()`` at times if it really wants to work
 with consistent data -- Django will not do this for you (the database backend
 layer and the model population layer are separated internally so the database
+layer doesn't know it needs to make this conversion in this one particular
 case).
+case-sensitive comparisons on a particular column or table, you would change the
+column or table to use the ``utf8_bin`` collation. The main thing to be aware of
+in this case is that if you are using MySQLdb 1.2.2, the database backend in
+Django will then return bytestrings (instead of unicode strings) for any
+character fields it returns receive from the database. This is a strong
+variation from Django's normal practice of *always* returning unicode strings.
+It is up to you, the developer, to handle the fact that you will receive
+bytestrings if you configure your table(s) to use ``utf8_bin`` collation. Django
+itself should work smoothly with such columns, but if your code must be prepared
+to call ``django.utils.encoding.smart_unicode()`` at times if it really wants to
+work with consistent data -- Django will not do this for you (the database
+backend layer and the model population layer are separated internally so the
+database layer doesn't know it needs to make this conversion in this one
+particular case).
 If you're using MySQLdb 1.2.1p2, Django's standard
 :class:`~django.db.models.CharField` class will return unicode strings even
 …
        :setting:`DATABASE_PORT`
 . MySQL option files.
+In other words, if you set the name of the database in ``DATABASE_OPTIONS``,
+this will take precedence over ``DATABASE_NAME``, which would override
+anything in a `MySQL option file`_.
+In other words, if you set the name of the database in
+:setting:`DATABASE_OPTIONS`, this will take precedence over
+:setting:`DATABASE_NAME`, which would override anything in a `MySQL option
+file`_.
 Here's a sample configuration which uses a MySQL option file::
 …
 modules.
 However, in the case of Windows, the official binary distribution of the stable
 release of Python 2.5 (2.5.2, as of this writing) includes SQLite 3.3.4, so the bug can
+make itself evident in that platform. There are (as of Django 1.0) even three
 tests in the Django test suite that will fail when run under this setup.  As
 described above, this can be solved by downloading and installing a newer
+release of Python 2.5 (2.5.2, as of this writing) includes SQLite 3.3.4, so the
+bug can make itself evident in that platform. There are (as of Django 1.0) even
+three tests in the Django test suite that will fail when run under this setup.
+As described above, this can be solved by downloading and installing a newer
 version of ``pysqlite2`` (``pysqlite-2.x.x.win32-py2.5.exe``) that includes and
 uses a newer version of SQLite. Python 2.6 ships with a newer version of
 SQLite and is not affected by this issue.
+uses a newer version of SQLite. Python 2.6 ships with a newer version of SQLite
+and is not affected by this issue.
 If you are in such platform and find yourself in the need to update
 ``pysqlite``/SQLite, you will also need to manually modify the
 …
     DATABASE_HOST = 'dbprod01ned.mycompany.com'
     DATABASE_PORT = '1540'
 You should supply both :setting:`DATABASE_HOST` and :setting:`DATABASE_PORT`, or leave both
 as empty strings.
+You should supply both :setting:`DATABASE_HOST` and :setting:`DATABASE_PORT`, or
+leave both as empty strings.
 Tablespace options
 ------------------

docs/ref/django-admin.txt

diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt

-              a
 ---------
 Many subcommands take a list of "app names." An "app name" is the basename of
+the package containing your models. For example, if your ``INSTALLED_APPS``
+contains the string ``'mysite.blog'``, the app name is ``blog``.
+the package containing your models. For example, if your
+:setting:`INSTALLED_APPS` contains the string ``'mysite.blog'``, the app name is
+``blog``.
 Determining the version
 -----------------------
 …
 it when running interactively.
 This command is only available if Django's :ref:`authentication system
 <topics-auth>` (``django.contrib.auth``) is installed.
+<topics-auth>` (:mod:`django.contrib.auth`) is installed.
 dbshell
 -------
 …
 .. django-admin:: dbshell
 Runs the command-line client for the database engine specified in your
+``DATABASE_ENGINE`` setting, with the connection parameters specified in your
 ``DATABASE_USER``, ``DATABASE_PASSWORD``, etc., settings.
+:setting:`DATABASE_ENGINE` setting, with the connection parameters specified in
+your :setting:`DATABASE_USER`, :setting:`DATABASE_PASSWORD`, etc., settings.
     * For PostgreSQL, this runs the ``psql`` command-line client.
     * For MySQL, this runs the ``mysql`` command-line client.
 …
 settings.
 Settings that don't appear in the defaults are followed by ``"###"``. For
 example, the default settings don't define ``ROOT_URLCONF``, so
+example, the default settings don't define :setting:`ROOT_URLCONF`, so
 ``ROOT_URLCONF`` is followed by ``"###"`` in the output of ``diffsettings``.
 Note that Django's default settings live in ``django/conf/global_settings.py``,
 …
 ---------
 Introspects the database tables in the database pointed-to by the
+``DATABASE_NAME`` setting and outputs a Django model module (a ``models.py``
 file) to standard output.
+:setting:`DATABASE_NAME` setting and outputs a Django model module (a
+``models.py`` file) to standard output.
 Use this if you have a legacy database with which you'd like to use Django.
 The script will inspect the database and create a model for each table within
 …
 Django will search in three locations for fixtures:
 . In the ``fixtures`` directory of every installed application
 . In any directory named in the ``FIXTURE_DIRS`` setting
+. In any directory named in the :setting:`FIXTURE_DIRS` setting
 . In the literal path named by the fixture
 Django will load any and all fixtures it finds in these locations that match
 …
 would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed
 application,  ``<dirname>/foo/bar/mydata.json`` for each directory in
 ``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``.
+:setting:`FIXTURE_DIRS`, and the literal path ``foo/bar/mydata.json``.
 Note that the order in which fixture files are processed is undefined. However,
 all fixture data is installed as a single transaction, so data in
 …
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 By default, the development server doesn't serve any static files for your site
 (such as CSS files, images, things under ``MEDIA_URL`` and so forth). If
+(such as CSS files, images, things under :setting:`MEDIA_URL` and so forth). If
 you want to configure Django to serve static media, read :ref:`howto-static-files`.
 Turning off auto-reload
 …
 syncdb
 ------
 Creates the database tables for all apps in ``INSTALLED_APPS`` whose tables
 have not already been created.
+Creates the database tables for all apps in :setting:`INSTALLED_APPS` whose
+tables have not already been created.
 Use this command when you've added new applications to your project and want to
 install them in the database. This includes any apps shipped with Django that
 might be in ``INSTALLED_APPS`` by default. When you start a new project, run
 this command to install the default apps.
+might be in :setting:`INSTALLED_APPS` by default. When you start a new project,
+run this command to install the default apps.
 .. admonition:: Syncdb will not alter existing tables
 …
    to match, use the ``sql`` command to display the new SQL structure and
    compare that to your existing table schema to work out the changes.
 If you're installing the ``django.contrib.auth`` application, ``syncdb`` will
+If you're installing the :mod:`django.contrib.auth` application, ``syncdb`` will
 give you the option of creating a superuser immediately.
 ``syncdb`` will also search for and install any fixture named ``initial_data``
 …
 --addrport [port number or ipaddr:port]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Use ``--addrport`` to specify a different port, or IP address and port, from
+the default of 127.0.0.1:8000. This value follows exactly the same format and
 serves exactly the same function as the argument to the ``runserver`` subcommand.
+Use ``--addrport`` to specify a different port, or IP address and port, from the
+default of 127.0.0.1:8000. This value follows exactly the same format and serves
+exactly the same function as the argument to the ``runserver`` subcommand.
 Examples:
 …
 validate
 --------
 Validates all installed models (according to the ``INSTALLED_APPS`` setting)
 and prints validation errors to standard output.
+Validates all installed models (according to the :setting:`INSTALLED_APPS`
+setting) and prints validation errors to standard output.
 Default options
 ===============

docs/ref/forms/api.txt

diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt

-              a
 Accessing "clean" data
 ----------------------
 Each ``Field`` in a ``Form`` class is responsible not only for validating data,
+but also for "cleaning" it -- normalizing it to a consistent format. This is a
+nice feature, because it allows data for a particular field to be input in
 a variety of ways, always resulting in consistent output.
+Each :class:`Field` in a :class:`Form` class is responsible not only for
+validating data, but also for "cleaning" it -- normalizing it to a consistent
+format. This is a nice feature, because it allows data for a particular field to
+be input in a variety of ways, always resulting in consistent output.
 For example, ``DateField`` normalizes input into a Python ``datetime.date``
+For example, :class:`DateField` normalizes input into a Python ``datetime.date``
 object. Regardless of whether you pass it a string in the format
 ``'1994-07-15'``, a ``datetime.date`` object or a number of other formats,
 ``DateField`` will always normalize it to a ``datetime.date`` object as long as
 it's valid.
 Once you've created a ``Form`` instance with a set of data and validated it,
+you can access the clean data via the ``cleaned_data`` attribute of the ``Form``
 object::
+Once you've created a :class:`Form` instance with a set of data and validated
+it, you can access the clean data via the :attr:`cleaned_data` attribute of the
+``Form`` object::
     >>> data = {'subject': 'hello',
     ...         'message': 'Hi there',
 …
     {'cc_myself': True, 'message': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'}
 .. versionchanged:: 1.0
     The ``cleaned_data`` attribute was called ``clean_data`` in earlier releases.
+    The :attr:`cleaned_data` attribute was called ``clean_data`` in earlier releases.
 Note that any text-based field -- such as ``CharField`` or ``EmailField`` --
+always cleans the input into a Unicode string. We'll cover the encoding
 implications later in this document.
+Note that any text-based field -- such as :class:`CharField` or
+:class:`EmailField` -- always cleans the input into a Unicode string. We'll
+cover the encoding implications later in this document.
 If your data does *not* validate, your ``Form`` instance will not have a
 ``cleaned_data`` attribute::
+If your data does *not* validate, your :class:`Form` instance will not have a
+:attr:`cleaned_data` attribute::
     >>> data = {'subject': '',
     ...         'message': 'Hi there',
 …
     ...
     AttributeError: 'ContactForm' object has no attribute 'cleaned_data'
 ``cleaned_data`` will always *only* contain a key for fields defined in the
+``Form``, even if you pass extra data when you define the ``Form``. In this
+example, we pass a bunch of extra fields to the ``ContactForm`` constructor,
 but ``cleaned_data`` contains only the form's fields::
+:attr:`cleaned_data` will always *only* contain a key for fields defined in the
+:class:`Form`, even if you pass extra data when you define the :class:`Form`. In
+this example, we pass a bunch of extra fields to the ``ContactForm``
+constructor, but :attr:`cleaned_data` contains only the form's fields::
     >>> data = {'subject': 'hello',
     ...         'message': 'Hi there',
 …
     >>> f.cleaned_data # Doesn't contain extra_field_1, etc.
     {'cc_myself': True, 'message': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'}
+``cleaned_data`` will include a key and value for *all* fields defined in the
+``Form``, even if the data didn't include a value for fields that are not
+required. In this example, the data dictionary doesn't include a value for the
+``nick_name`` field, but ``cleaned_data`` includes it, with an empty value::
+:attr:`cleaned_data` will include a key and value for *all* fields defined in
+the :class:`Form`, even if the data didn't include a value for fields that are
+not required. In this example, the data dictionary doesn't include a value for
+the ``nick_name`` field, but :attr:`cleaned_data` includes it, with an empty
+value::
     >>> class OptionalPersonForm(Form):
     ...     first_name = CharField()
 …
     >>> f.cleaned_data
     {'nick_name': u'', 'first_name': u'John', 'last_name': u'Lennon'}
+In this above example, the ``cleaned_data`` value for ``nick_name`` is set to an
+empty string, because ``nick_name`` is ``CharField``, and ``CharField``\s treat
+empty values as an empty string. Each field type knows what its "blank" value
+is -- e.g., for ``DateField``, it's ``None`` instead of the empty string. For
+full details on each field's behavior in this case, see the "Empty value" note
+for each field in the "Built-in ``Field`` classes" section below.
+In this above example, the :attr:`cleaned_data` value for ``nick_name`` is set
+to an empty string, because ``nick_name`` is :class:`CharField`, and
+:class:`CharField`\s treat empty values as an empty string. Each field type
+knows what its "blank" value is -- e.g., for :class:`DateField`, it's ``None``
+instead of the empty string. For full details on each field's behavior in this
+case, see the "Empty value" note for each field in the "Built-in :class:`Field`
+classes" section below.
 You can write code to perform validation for particular form fields (based on
 their name) or for the form as a whole (considering combinations of various
 …
 Outputting forms as HTML
 ------------------------
 The second task of a ``Form`` object is to render itself as HTML. To do so,
+The second task of a :class:`Form` object is to render itself as HTML. To do so,
 simply ``print`` it::
     >>> f = ContactForm()
 …
       ``</table>`` tags, nor does it include the ``<form>`` and ``</form>``
       tags or an ``<input type="submit">`` tag. It's your job to do that.
     * Each field type has a default HTML representation. ``CharField`` and
       ``EmailField`` are represented by an ``<input type="text">``.
       ``BooleanField`` is represented by an ``<input type="checkbox">``. Note
       these are merely sensible defaults; you can specify which HTML to use for
       a given field by using widgets, which we'll explain shortly.
+    * Each field type has a default HTML representation. :class:`CharField` and
+      :class:`EmailField` are represented by an ``<input type="text">``.
+      :class:`BooleanField` is represented by an ``<input type="checkbox">``.
+      Note these are merely sensible defaults; you can specify which HTML to use
+      for a given field by using widgets, which we'll explain shortly.
     * The HTML ``name`` for each tag is taken directly from its attribute name
       in the ``ContactForm`` class.
 …
 ``as_p()``
 ~~~~~~~~~~
 ``Form.as_p()`` renders the form as a series of ``<p>`` tags, with each ``<p>``
+:meth:`Form.as_p` renders the form as a series of ``<p>`` tags, with each ``<p>``
 containing one field::
     >>> f = ContactForm()
 …
 ``as_ul()``
 ~~~~~~~~~~~
 ``Form.as_ul()`` renders the form as a series of ``<li>`` tags, with each
+:meth:`Form.as_ul` renders the form as a series of ``<li>`` tags, with each
 ``<li>`` containing one field. It does *not* include the ``<ul>`` or ``</ul>``,
 so that you can specify any HTML attributes on the ``<ul>`` for flexibility::
 …
 ``as_table()``
 ~~~~~~~~~~~~~~
 Finally, ``Form.as_table()`` outputs the form as an HTML ``<table>``. This is
+Finally, :meth:`Form.as_table` outputs the form as an HTML ``<table>``. This is
 exactly the same as ``print``. In fact, when you ``print`` a form object, it
 calls its ``as_table()`` method behind the scenes::
+calls its :meth:`as_table` method behind the scenes::
     >>> f = ContactForm()
     >>> f.as_table()
 …
 This behavior is configurable, though, if you want to change the ``id``
 convention or remove HTML ``id`` attributes and ``<label>`` tags entirely.
+Use the ``auto_id`` argument to the ``Form`` constructor to control the label
+and ``id`` behavior. This argument must be ``True``, ``False`` or a string.
+Use the ``auto_id`` argument to the :class:`Form` constructor to control the
+label and ``id`` behavior. This argument must be ``True``, ``False`` or a
+string.
 If ``auto_id`` is ``False``, then the form output will not include ``<label>``
 tags nor ``id`` attributes::
 …
 Notes on field ordering
 ~~~~~~~~~~~~~~~~~~~~~~~
 In the ``as_p()``, ``as_ul()`` and ``as_table()`` shortcuts, the fields are
 displayed in the order in which you define them in your form class. For
+In the :meth:`as_p`, :meth:`as_ul` and :meth:`as_table` shortcuts, the fields
+are displayed in the order in which you define them in your form class. For
 example, in the ``ContactForm`` example, the fields are defined in the order
 ``subject``, ``message``, ``sender``, ``cc_myself``. To reorder the HTML
 output, just change the order in which those fields are listed in the class.
+``subject``, ``message``, ``sender``, ``cc_myself``. To reorder the HTML output,
+just change the order in which those fields are listed in the class.
 How errors are displayed
 ~~~~~~~~~~~~~~~~~~~~~~~~
 If you render a bound ``Form`` object, the act of rendering will automatically
+run the form's validation if it hasn't already happened, and the HTML output
+will include the validation errors as a ``<ul class="errorlist">`` near the
+field. The particular positioning of the error messages depends on the output
 method you're using::
+If you render a bound :class:`Form` object, the act of rendering will
+automatically run the form's validation if it hasn't already happened, and the
+HTML output will include the validation errors as a ``<ul class="errorlist">``
+near the field. The particular positioning of the error messages depends on the
+output method you're using::
     >>> data = {'subject': '',
     ...         'message': 'Hi there',
 …
 Customizing the error list format
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 By default, forms use ``django.forms.util.ErrorList`` to format validation
+By default, forms use :class:`django.forms.util.ErrorList` to format validation
 errors. If you'd like to use an alternate class for displaying errors, you can
 pass that in at construction time::
 …
 More granular output
 ~~~~~~~~~~~~~~~~~~~~
+The ``as_p()``, ``as_ul()`` and ``as_table()`` methods are simply shortcuts for
+lazy developers -- they're not the only way a form object can be displayed.
+The :meth:`as_p`, :meth:`as_ul` and :meth:`as_table` methods are simply
+shortcuts for lazy developers -- they're not the only way a form object can be
+displayed.
 To display the HTML for a single field in your form, use dictionary lookup
 syntax using the field's name as the key, and print the resulting object::
 …
     >>> print f['message']
     <input type="text" name="message" id="id_message" />
 For a field's list of errors, access the field's ``errors`` attribute. This
+For a field's list of errors, access the field's :attr:`errors` attribute. This
 is a list-like object that is displayed as an HTML ``<ul class="errorlist">``
 when printed::
 …
 .. versionadded:: 1.0
 Dealing with forms that have ``FileField`` and ``ImageField`` fields
+Dealing with forms that have :class:`FileField` and :class:`ImageField` fields
 is a little more complicated than a normal form.
 Firstly, in order to upload files, you'll need to make sure that your
 …
 Secondly, when you use the form, you need to bind the file data. File
 data is handled separately to normal form data, so when your form
 contains a ``FileField`` and ``ImageField``, you will need to specify
+contains a :class:`FileField` and :class:`ImageField`, you will need to specify
 a second argument when you bind your form. So if we extend our
 ContactForm to include an ``ImageField`` called ``mugshot``, we
+ContactForm to include an :class:`ImageField` called ``mugshot``, we
 need to bind the file data containing the mugshot image::
     # Bound form with an image field
 …
     >>> file_data = {'mugshot': SimpleUploadedFile('face.jpg', <file data>)}
     >>> f = ContactFormWithMugshot(data, file_data)
 In practice, you will usually specify ``request.FILES`` as the source
 of file data (just like you use ``request.POST`` as the source of
+In practice, you will usually specify :attr:`request.FILES` as the source
+of file data (just like you use :attr:`request.POST` as the source of
 form data)::
     # Bound form with an image field, data from the request
 …
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 If you're writing reusable views or templates, you may not know ahead of time
 whether your form is a multipart form or not. The ``is_multipart()`` method
+whether your form is a multipart form or not. The :meth:`is_multipart` method
 tells you whether the form requires multipart encoding for submission::
     >>> f = ContactFormWithMugshot()
 …
 Subclassing forms
 -----------------
 If you have multiple ``Form`` classes that share fields, you can use
+If you have multiple :class:`Form` classes that share fields, you can use
 subclassing to remove redundancy.
 When you subclass a custom ``Form`` class, the resulting subclass will
+When you subclass a custom :class:`Form` class, the resulting subclass will
 include all fields of the parent class(es), followed by the fields you define
 in the subclass.
 …
 .. attribute:: Form.prefix
 You can put several Django forms inside one ``<form>`` tag. To give each
 ``Form`` its own namespace, use the ``prefix`` keyword argument::
+:class:`Form` its own namespace, use the ``prefix`` keyword argument::
     >>> mother = PersonForm(prefix="mother")
     >>> father = PersonForm(prefix="father")

docs/ref/forms/fields.txt

diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt

-              a
 .. attribute:: URLField.validator_user_agent
     String used as the user-agent used when checking for a URL's existence.
     Defaults to the value of the ``URL_VALIDATOR_USER_AGENT`` setting.
+    Defaults to the value of the :setting:`URL_VALIDATOR_USER_AGENT` setting.
 Slightly complex built-in ``Field`` classes
 -------------------------------------------

docs/ref/generic-views.txt

diff --git a/docs/ref/generic-views.txt b/docs/ref/generic-views.txt

-              a
 "Simple" generic views
 ======================
 The ``django.views.generic.simple`` module contains simple views to handle a
+The :mod:`django.views.generic.simple` module contains simple views to handle a
 couple of common cases: rendering a template when no view logic is needed,
 and issuing a redirect.
 …
       just before rendering the template.
     * ``mimetype``: The MIME type to use for the resulting document. Defaults
       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
+      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
 **Example:**
 …
       page. This lets you override the default template name (see below).
     * ``template_loader``: The template loader to use when loading the
       template. By default, it's ``django.template.loader``.
+      template. By default, it's :mod:`django.template.loader`.
     * ``extra_context``: A dictionary of values to add to the template
       context. By default, this is an empty dictionary. If a value in the
 …
       the view's template.
     * ``mimetype``: The MIME type to use for the resulting document. Defaults
       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
+      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
     * ``allow_future``: A boolean specifying whether to include "future"
       objects on this page, where "future" means objects in which the field
 …
       page. This lets you override the default template name (see below).
     * ``template_loader``: The template loader to use when loading the
       template. By default, it's ``django.template.loader``.
+      template. By default, it's :mod:`django.template.loader`.
     * ``extra_context``: A dictionary of values to add to the template
       context. By default, this is an empty dictionary. If a value in the
 …
       this is ``False``.
     * ``mimetype``: The MIME type to use for the resulting document. Defaults
       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
+      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
     * ``allow_future``: A boolean specifying whether to include "future"
       objects on this page, where "future" means objects in which the field
 …
       page. This lets you override the default template name (see below).
     * ``template_loader``: The template loader to use when loading the
       template. By default, it's ``django.template.loader``.
+      template. By default, it's :mod:`django.template.loader`.
     * ``extra_context``: A dictionary of values to add to the template
       context. By default, this is an empty dictionary. If a value in the
 …
       determining the variable's name.
     * ``mimetype``: The MIME type to use for the resulting document. Defaults
       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
+      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
     * ``allow_future``: A boolean specifying whether to include "future"
       objects on this page, where "future" means objects in which the field
 …
       page. This lets you override the default template name (see below).
     * ``template_loader``: The template loader to use when loading the
       template. By default, it's ``django.template.loader``.
+      template. By default, it's :mod:`django.template.loader`.
     * ``extra_context``: A dictionary of values to add to the template
       context. By default, this is an empty dictionary. If a value in the
 …
       determining the variable's name.
     * ``mimetype``: The MIME type to use for the resulting document. Defaults
       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
+      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
     * ``allow_future``: A boolean specifying whether to include "future"
       objects on this page, where "future" means objects in which the field
 …
       page. This lets you override the default template name (see below).
     * ``template_loader``: The template loader to use when loading the
       template. By default, it's ``django.template.loader``.
+      template. By default, it's :mod:`django.template.loader`.
     * ``extra_context``: A dictionary of values to add to the template
       context. By default, this is an empty dictionary. If a value in the
 …
       determining the variable's name.
     * ``mimetype``: The MIME type to use for the resulting document. Defaults
       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
+      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
     * ``allow_future``: A boolean specifying whether to include "future"
       objects on this page, where "future" means objects in which the field
 …
       It's a bit of a brain-bender, but it's useful in some cases.
     * ``template_loader``: The template loader to use when loading the
       template. By default, it's ``django.template.loader``.
+      template. By default, it's :mod:`django.template.loader`.
     * ``extra_context``: A dictionary of values to add to the template
       context. By default, this is an empty dictionary. If a value in the
 …
       to use in the template context. By default, this is ``'object'``.
     * ``mimetype``: The MIME type to use for the resulting document. Defaults
       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
+      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
     * ``allow_future``: A boolean specifying whether to include "future"
       objects on this page, where "future" means objects in which the field
 …
       page. This lets you override the default template name (see below).
     * ``template_loader``: The template loader to use when loading the
       template. By default, it's ``django.template.loader``.
+      template. By default, it's :mod:`django.template.loader`.
     * ``extra_context``: A dictionary of values to add to the template
       context. By default, this is an empty dictionary. If a value in the
 …
       determining the variable's name.
     * ``mimetype``: The MIME type to use for the resulting document. Defaults
       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
+      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
 **Template name:**
 …
       It's a bit of a brain-bender, but it's useful in some cases.
     * ``template_loader``: The template loader to use when loading the
       template. By default, it's ``django.template.loader``.
+      template. By default, it's :mod:`django.template.loader`.
     * ``extra_context``: A dictionary of values to add to the template
       context. By default, this is an empty dictionary. If a value in the
 …
       to use in the template context. By default, this is ``'object'``.
     * ``mimetype``: The MIME type to use for the resulting document. Defaults
       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
+      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
 **Template name:**
 …
       page. This lets you override the default template name (see below).
     * ``template_loader``: The template loader to use when loading the
       template. By default, it's ``django.template.loader``.
+      template. By default, it's :mod:`django.template.loader`.
     * ``extra_context``: A dictionary of values to add to the template
       context. By default, this is an empty dictionary. If a value in the
 …
       page. This lets you override the default template name (see below).
     * ``template_loader``: The template loader to use when loading the
       template. By default, it's ``django.template.loader``.
+      template. By default, it's :mod:`django.template.loader`.
     * ``extra_context``: A dictionary of values to add to the template
       context. By default, this is an empty dictionary. If a value in the
 …
       page. This lets you override the default template name (see below).
     * ``template_loader``: The template loader to use when loading the
       template. By default, it's ``django.template.loader``.
+      template. By default, it's :mod:`django.template.loader`.
     * ``extra_context``: A dictionary of values to add to the template
       context. By default, this is an empty dictionary. If a value in the

docs/ref/request-response.txt

diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt

-              a
 When a page is requested, Django creates an :class:`HttpRequest` object that
 contains metadata about the request. Then Django loads the appropriate view,
 passing the :class:`HttpRequest` as the first argument to the view function. Each
 view is responsible for returning an :class:`HttpResponse` object.
+passing the :class:`HttpRequest` as the first argument to the view function.
+Each view is responsible for returning an :class:`HttpResponse` object.
 This document explains the APIs for :class:`HttpRequest` and :class:`HttpResponse`
 objects.
+This document explains the APIs for :class:`HttpRequest` and
+:class:`HttpResponse` objects.
 HttpRequest objects
 ===================
 …
     .. versionadded:: 1.0
     A string representing the current encoding used to decode form submission
     data (or ``None``, which means the ``DEFAULT_CHARSET`` setting is used).
     You can write to this attribute to change the encoding used when accessing
     the form data. Any subsequent attribute accesses (such as reading from
     ``GET`` or ``POST``) will use the new ``encoding`` value.  Useful if you
     know the form data is not in the ``DEFAULT_CHARSET`` encoding.
+    data (or ``None``, which means the :setting:`DEFAULT_CHARSET` setting is
+    used).  You can write to this attribute to change the encoding used when
+    accessing the form data. Any subsequent attribute accesses (such as reading
+    from ``GET`` or ``POST``) will use the new ``encoding`` value.  Useful if
+    you know the form data is not in the ``DEFAULT_CHARSET`` encoding.
 .. attribute:: HttpRequest.GET
     A dictionary-like object containing all given HTTP GET parameters. See the
     ``QueryDict`` documentation below.
+    :class:`QueryDict` documentation below.
 .. attribute:: HttpRequest.POST
     A dictionary-like object containing all given HTTP POST parameters. See the
     ``QueryDict`` documentation below.
+    :class:`QueryDict` documentation below.
     It's possible that a request can come in via POST with an empty ``POST``
     dictionary -- if, say, a form is requested via the POST HTTP method but
 …
     A dictionary-like object containing all uploaded files. Each key in
     ``FILES`` is the ``name`` from the ``<input type="file" name="" />``. Each
     value in ``FILES`` is an ``UploadedFile`` object containing the following
     attributes:
+    value in ``FILES`` is an :class:`UploadedFile` object containing the
+    following attributes:
         * ``read(num_bytes=None)`` -- Read a number of bytes from the file.
         * ``name`` -- The name of the uploaded file.
         * ``size`` -- The size, in bytes, of the uploaded file.
+        * ``chunks(chunk_size=None)`` -- A generator that yields sequential chunks of data.
+        * ``chunks(chunk_size=None)`` -- A generator that yields sequential
+          chunks of data.
     See :ref:`topics-files` for more information.
 …
 .. attribute:: HttpRequest.user
     A ``django.contrib.auth.models.User`` object representing the currently
+    A :class:`django.contrib.auth.models.User` object representing the currently
     logged-in user. If the user isn't currently logged in, ``user`` will be set
     to an instance of ``django.contrib.auth.models.AnonymousUser``. You
     can tell them apart with ``is_authenticated()``, like so::
+    to an instance of :class:`django.contrib.auth.models.AnonymousUser`. You
+    can tell them apart with :meth:`is_authenticated`, like so::
         if request.user.is_authenticated():
             # Do something for logged-in users.
 …
     Not defined by Django itself, but will be read if other code (e.g., a custom
     middleware class) sets it. When present, this will be used as the root
     URLconf for the current request, overriding the ``ROOT_URLCONF`` setting.
     See :ref:`how-django-processes-a-request` for details.
+    URLconf for the current request, overriding the :setting:`ROOT_URLCONF`
+    setting.  See :ref:`how-django-processes-a-request` for details.
 Methods
 -------
 …
    .. versionadded:: 1.0
+   Returns ``True`` if the request was made via an ``XMLHttpRequest``, by checking
+   the ``HTTP_X_REQUESTED_WITH`` header for the string ``'XMLHttpRequest'``. The
+   following major JavaScript libraries all send this header:
+   Returns ``True`` if the request was made via an ``XMLHttpRequest``, by
+   checking the ``HTTP_X_REQUESTED_WITH`` header for the string
+   ``'XMLHttpRequest'``. The following major JavaScript libraries all send this
+   header:
        * jQuery
        * Dojo
 …
 .. class:: QueryDict
 In an :class:`HttpRequest` object, the ``GET`` and ``POST`` attributes are instances
+of ``django.http.QueryDict``. :class:`QueryDict` is a dictionary-like
 class customized to deal with multiple values for the same key. This is
+necessary because some HTML form elements, notably
 ``<select multiple="multiple">``, pass multiple values for the same key.
+In an :class:`HttpRequest` object, the ``GET`` and ``POST`` attributes are
+instances of ``django.http.QueryDict``. ``QueryDict`` is a dictionary-like class
+customized to deal with multiple values for the same key. This is necessary
+because some HTML form elements, notably ``<select multiple="multiple">``, pass
+multiple values for the same key.
 ``QueryDict`` instances are immutable, unless you create a ``copy()`` of them.
 That means you can't change attributes of ``request.POST`` and ``request.GET``
 …
 Methods
 -------
 :class:`QueryDict` implements all the standard dictionary methods, because it's
+``QueryDict`` implements all the standard dictionary methods, because it's
 a subclass of dictionary. Exceptions are outlined here:
 .. method:: QueryDict.__getitem__(key)
 …
     Just like the standard dictionary ``setdefault()`` method, except it uses
     ``__setitem__`` internally.
 .. method:: QueryDict.update(other_dict)
+.. method:: QueryDict.update(other_dict)
     Takes either a ``QueryDict`` or standard dictionary. Just like the standard
     dictionary ``update()`` method, except it *appends* to the current
 …
     Like :meth:`items()`, except it includes all values, as a list, for each
     member of the dictionary. For example::
          >>> q = QueryDict('a=1&a=2&a=3')
          >>> q.lists()
          [('a', ['1', '2', '3'])]
 .. method:: QueryDict.urlencode()
     Returns a string of the data in query-string format.
 …
 .. class:: HttpResponse
 In contrast to :class:`HttpRequest` objects, which are created automatically by
 Django, :class:`HttpResponse` objects are your responsibility. Each view you
+Django, ``HttpResponse`` objects are your responsibility. Each view you
 write is responsible for instantiating, populating and returning an
 :class:`HttpResponse`.
+``HttpResponse``.
 The :class:`HttpResponse` class lives in the ``django.http`` module.
+The ``HttpResponse`` class lives in the :mod:`django.http` module.
 Usage
 -----
 …
 ~~~~~~~~~~~~~~~
 Typical usage is to pass the contents of the page, as a string, to the
 :class:`HttpResponse` constructor::
+``HttpResponse`` constructor::
     >>> response = HttpResponse("Here's the text of the Web page.")
     >>> response = HttpResponse("Text only, please.", mimetype="text/plain")
 …
 hard-coded strings. If you use this technique, follow these guidelines:
     * The iterator should return strings.
     * If an :class:`HttpResponse` has been initialized with an iterator as its
       content, you can't use the class:`HttpResponse` instance as a file-like
+    * If an ``HttpResponse`` has been initialized with an iterator as its
+      content, you can't use the ``HttpResponse`` instance as a file-like
       object. Doing so will raise ``Exception``.
 Setting headers
 …
 -------
 .. method:: HttpResponse.__init__(content='', mimetype=None, status=200, content_type=DEFAULT_CONTENT_TYPE)
     Instantiates an ``HttpResponse`` object with the given page content (a
     string) and MIME type. The ``DEFAULT_CONTENT_TYPE`` is ``'text/html'``.
+    string) and MIME type. The :setting:`DEFAULT_CONTENT_TYPE` is ``'text/html'``.
     ``content`` can be an iterator or a string. If it's an iterator, it should
     return strings, and those strings will be joined together to form the
 …
     encoding, which makes it more than just a MIME type specification.
     If ``mimetype`` is specified (not ``None``), that value is used.
     Otherwise, ``content_type`` is used. If neither is given, the
     ``DEFAULT_CONTENT_TYPE`` setting is used.
+    :setting:`DEFAULT_CONTENT_TYPE` setting is used.
 .. method:: HttpResponse.__setitem__(header, value)
 …
 .. method:: HttpResponse.write(content)
     This method makes an :class:`HttpResponse` instance a file-like object.
+    This method makes an ``HttpResponse`` instance a file-like object.
 .. method:: HttpResponse.flush()
     This method makes an :class:`HttpResponse` instance a file-like object.
+    This method makes an ``HttpResponse`` instance a file-like object.
 .. method:: HttpResponse.tell()
     This method makes an :class:`HttpResponse` instance a file-like object.
+    This method makes an ``HttpResponse`` instance a file-like object.
 .. _HTTP Status code: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10
 …
 HttpResponse subclasses
 -----------------------
 Django includes a number of ``HttpResponse`` subclasses that handle different
+types of HTTP responses. Like ``HttpResponse``, these subclasses live in
 :mod:`django.http`.
+Django includes a number of :class:`HttpResponse` subclasses that handle
+different types of HTTP responses. Like ``HttpResponse``, these subclasses live
+in :mod:`django.http`.
 .. class:: HttpResponseRedirect
     The constructor takes a single argument -- the path to redirect to. This
     can be a fully qualified URL (e.g. ``'http://www.yahoo.com/search/'``) or an
     absolute URL with no domain (e.g. ``'/search/'``). Note that this returns
     an HTTP status code 302.
+    The constructor takes a single argument -- the path to redirect to. This can
+    be a fully qualified URL (e.g. ``'http://www.yahoo.com/search/'``) or an
+    absolute URL with no domain (e.g. ``'/search/'``). Note that this returns an
+    HTTP status code 302.
 .. class:: HttpResponsePermanentRedirect

docs/ref/settings.txt

diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt

-              a
 The URL prefix for admin media -- CSS, JavaScript and images used by
 the Django administrative interface. Make sure to use a trailing
 slash, and to have this be different from the ``MEDIA_URL`` setting
+slash, and to have this be different from the :setting:`MEDIA_URL` setting
 (since the same URL cannot be mapped onto two different sets of
 files).
 …
 Whether to append trailing slashes to URLs. This is only used if
 ``CommonMiddleware`` is installed (see :ref:`topics-http-middleware`). See also
 ``PREPEND_WWW``.
+:setting:`PREPEND_WWW`.
 .. setting:: AUTHENTICATION_BACKENDS
 …
 Default: ``''`` (Empty string)
 The name of the database to use. For SQLite, it's the full path to the database
 file. When specifying the path, always use forward slashes, even on Windows
+file. When specifying the path, always use forward slashes, even on Windows
 (e.g. ``C:/homes/user/mysite/sqlite3.db``).
 .. setting:: DATABASE_OPTIONS
 …
 default port. Not used with SQLite.
 .. setting:: DATABASE_USER
 DATABASE_USER
 -------------
 …
 and ``MONTH_DAY_FORMAT``.
 .. setting:: DATETIME_FORMAT
 DATETIME_FORMAT
 ---------------
 …
 .. warning::
     **Always prefix the mode with a 0.**
     If you're not familiar with file modes, please note that the leading
     ``0`` is very important: it indicates an octal number, which is the
     way that modes must be specified. If you try to use ``644``, you'll
     get totally incorrect behavior.
+.. _documentation for os.chmod: http://docs.python.org/lib/os-file-dir.html
+.. _documentation for os.chmod: http://docs.python.org/lib/os-file-dir.html
 .. setting:: FIXTURE_DIRS
 …
 If you define a custom ``LANGUAGES`` setting, it's OK to mark the languages as
 translation strings (as in the default value displayed above) -- but use a
 "dummy" ``gettext()`` function, not the one in ``django.utils.translation``.
 You should *never* import ``django.utils.translation`` from within your
+"dummy" ``gettext()`` function, not the one in :mod:`django.utils.translation`.
+You should *never* import :mod:`django.utils.translation` from within your
 settings file, because that module in itself depends on the settings, and that
 would cause a circular import.
 …
 .. versionadded:: 1.0
 Default: ``django.contrib.sessions.backends.db``
+Default: :mod:`django.contrib.sessions.backends.db`
 Controls where Django stores session data. Valid values are:
 …
     Django cannot reliably use alternate time zones in a Windows environment.
     If you're running Django on Windows, this variable must be set to match the
     system timezone.
 .. _See available choices: http://www.postgresql.org/docs/8.1/static/datetime-keywords.html#DATETIME-TIMEZONE-SET-TABLE
 .. setting:: URL_VALIDATOR_USER_AGENT

docs/ref/templates/api.txt

diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt

-              a
 To cut down on the repetitive nature of loading and rendering
 templates, Django provides a shortcut function which largely
 automates the process: ``render_to_string()`` in
 ``django.template.loader``, which loads a template, renders it and
+:mod:`django.template.loader`, which loads a template, renders it and
 returns the resulting string::
     from django.template.loader import render_to_string

docs/ref/templates/builtins.txt

diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt

-              a
 -------------------------------
 Django comes with a couple of other template-tag libraries that you have to
 enable explicitly in your ``INSTALLED_APPS`` setting and enable in your
+enable explicitly in your :setting:`INSTALLED_APPS` setting and enable in your
 template with the ``{% load %}`` tag.
 django.contrib.humanize

docs/ref/unicode.txt

diff --git a/docs/ref/unicode.txt b/docs/ref/unicode.txt

-              a
 Conversion functions
 ~~~~~~~~~~~~~~~~~~~~
 The ``django.utils.encoding`` module contains a few functions that are handy
+The :mod:`django.utils.encoding` module contains a few functions that are handy
 for converting back and forth between Unicode and bytestrings.
     * ``smart_unicode(s, encoding='utf-8', strings_only=False, errors='strict')``
 …
 E-mail
 ======
 Django's e-mail framework (in ``django.core.mail``) supports Unicode
+Django's e-mail framework (in :mod:`django.core.mail`) supports Unicode
 transparently. You can use Unicode data in the message bodies and any headers.
 However, you're still obligated to respect the requirements of the e-mail
 specifications, so, for example, e-mail addresses should use only ASCII

docs/topics/auth.txt

diff --git a/docs/topics/auth.txt b/docs/topics/auth.txt

-              a
 ============
 Authentication support is bundled as a Django application in
 ``django.contrib.auth``. To install it, do the following:
+:mod:`django.contrib.auth`. To install it, do the following:
 . Put ``'django.contrib.auth'`` in your :setting:`INSTALLED_APPS` setting.
 . Run the command ``manage.py syncdb``.
 …
 .. function:: views.login()
     Here's what ``django.contrib.auth.views.login`` does:
+    Here's what :func:`django.contrib.auth.views.login` does:
         * If called via ``GET``, it displays a login form that POSTs to the
           same URL. More on this in a bit.
 …
 Default permissions
 -------------------
 When ``django.contrib.auth`` is listed in your :setting:`INSTALLED_APPS`
+When :mod:`django.contrib.auth` is listed in your :setting:`INSTALLED_APPS`
 setting, it will ensure that three default permissions -- add, change and
 delete -- are created for each Django model defined in one of your installed
 applications.
 These permissions will be created when you run :djadmin:`manage.py syncdb
 <syncdb>`; the first time you run ``syncdb`` after adding
 ``django.contrib.auth`` to :setting:`INSTALLED_APPS`, the default permissions
+:mod:`django.contrib.auth` to :setting:`INSTALLED_APPS`, the default permissions
 will be created for all previously-installed models, as well as for any new
 models being installed at that time. Afterward, it will create default
 permissions for new models each time you run :djadmin:`manage.py syncdb

docs/topics/cache.txt

diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt

-              a
 or directly in memory. This is an important decision that affects your cache's
 performance; yes, some cache types are faster than others.
 Your cache preference goes in the ``CACHE_BACKEND`` setting in your settings
 file. Here's an explanation of all available values for CACHE_BACKEND.
+Your cache preference goes in the :setting:`CACHE_BACKEND` setting in your
+settings file. Here's an explanation of all available values for CACHE_BACKEND.
 Memcached
 ---------
 …
       "Client APIs" section.
 .. versionadded:: 1.0
     The ``cmemcache`` option is new in 1.0. Previously, only
     ``python-memcached`` was supported.
 To use Memcached with Django, set ``CACHE_BACKEND`` to
+To use Memcached with Django, set :setting:`CACHE_BACKEND` to
 ``memcached://ip:port/``, where ``ip`` is the IP address of the Memcached
 daemon and ``port`` is the port on which Memcached is running.
 …
 One excellent feature of Memcached is its ability to share cache over multiple
 servers. To take advantage of this feature, include all server addresses in
 ``CACHE_BACKEND``, separated by semicolons. In this example, the cache is
+:setting:`CACHE_BACKEND`, separated by semicolons. In this example, the cache is
 shared over Memcached instances running on IP address 172.19.26.240 and
 .19.26.242, both on port 11211::
 …
 in your database that is in the proper format that Django's database-cache
 system expects.
 Once you've created that database table, set your ``CACHE_BACKEND`` setting to
+``"db://tablename"``, where ``tablename`` is the name of the database table.
 In this example, the cache table's name is ``my_cache_table``::
+Once you've created that database table, set your :setting:`CACHE_BACKEND`
+setting to ``"db://tablename"``, where ``tablename`` is the name of the database
+table.  In this example, the cache table's name is ``my_cache_table``::
     CACHE_BACKEND = 'db://my_cache_table'
 …
 ------------------
 To store cached items on a filesystem, use the ``"file://"`` cache type for
+``CACHE_BACKEND``. For example, to store cached data in ``/var/tmp/django_cache``,
 use this setting::
+:setting:`CACHE_BACKEND`. For example, to store cached data in
+``/var/tmp/django_cache``, use this setting::
     CACHE_BACKEND = 'file:///var/tmp/django_cache'
 …
 If you want the speed advantages of in-memory caching but don't have the
 capability of running Memcached, consider the local-memory cache backend. This
 cache is multi-process and thread-safe. To use it, set ``CACHE_BACKEND`` to
 ``"locmem:///"``. For example::
+cache is multi-process and thread-safe. To use it, set :setting:`CACHE_BACKEND`
+to ``"locmem:///"``. For example::
     CACHE_BACKEND = 'locmem:///'
 Note that each process will have its own private cache instance, which means no
 cross-process caching is possible. This obviously also means the local memory
 cache isn't particularly memory-efficient, so it's probably not a good choice
 …
 various places but a development/test environment on which you don't want to
 cache. As a result, your development environment won't use caching and your
 production environment still will. To activate dummy caching, set
 ``CACHE_BACKEND`` like so::
+:setting:`CACHE_BACKEND` like so::
     CACHE_BACKEND = 'dummy:///'
 …
 While Django includes support for a number of cache backends out-of-the-box,
 sometimes you might want to use a customized cache backend. To use an external
 cache backend with Django, use a Python import path as the scheme portion (the
 part before the initial colon) of the ``CACHE_BACKEND`` URI, like so::
+part before the initial colon) of the :setting:`CACHE_BACKEND` URI, like so::
     CACHE_BACKEND = 'path.to.backend://'
 …
 -----------------------
 All caches may take arguments. They're given in query-string style on the
 ``CACHE_BACKEND`` setting. Valid arguments are:
+:setting:`CACHE_BACKEND` setting. Valid arguments are:
     timeout
         Default timeout, in seconds, to use for the cache. Defaults to 5
 …
 ==================
 .. versionchanged:: 1.0
+    (previous versions of Django only provided a single ``CacheMiddleware`` instead
+    of the two pieces described below).
+    (previous versions of Django only provided a single ``CacheMiddleware``
+    instead of the two pieces described below).
 Once the cache is set up, the simplest way to use caching is to cache your
 entire site. You'll need to add
 ``'django.middleware.cache.UpdateCacheMiddleware'`` and
 ``'django.middleware.cache.FetchFromCacheMiddleware'`` to your
 ``MIDDLEWARE_CLASSES`` setting, as in this example::
+:setting:`MIDDLEWARE_CLASSES` setting, as in this example::
     MIDDLEWARE_CLASSES = (
         'django.middleware.cache.UpdateCacheMiddleware',
 …
 Then, add the following required settings to your Django settings file:
 * ``CACHE_MIDDLEWARE_SECONDS`` -- The number of seconds each page should be
   cached.
 * ``CACHE_MIDDLEWARE_KEY_PREFIX`` -- If the cache is shared across multiple
   sites using the same Django installation, set this to the name of the site,
   or some other string that is unique to this Django instance, to prevent key
   collisions. Use an empty string if you don't care.
+* :setting:`CACHE_MIDDLEWARE_SECONDS` -- The number of seconds each page should
+  be cached.
+* :setting:`CACHE_MIDDLEWARE_KEY_PREFIX` -- If the cache is shared across
+  multiple sites using the same Django installation, set this to the name of
+  the site, or some other string that is unique to this Django instance, to
+  prevent key collisions. Use an empty string if you don't care.
 The cache middleware caches every page that doesn't have GET or POST
 parameters. Optionally, if the ``CACHE_MIDDLEWARE_ANONYMOUS_ONLY`` setting is
+The cache middleware caches every page that doesn't have GET or POST parameters.
+Optionally, if the :setting:`CACHE_MIDDLEWARE_ANONYMOUS_ONLY` setting is
 ``True``, only anonymous requests (i.e., not those made by a logged-in user)
 will be cached. This is a simple and effective way of disabling caching for any
 user-specific pages (include Django's admin interface). Note that if you use
+``CACHE_MIDDLEWARE_ANONYMOUS_ONLY``, you should make sure you've activated
 ``AuthenticationMiddleware``.
+:setting:`CACHE_MIDDLEWARE_ANONYMOUS_ONLY`, you should make sure you've
+activated ``AuthenticationMiddleware``.
 Additionally, the cache middleware automatically sets a few headers in each
 ``HttpResponse``:
 …
 * Sets the ``Last-Modified`` header to the current date/time when a fresh
   (uncached) version of the page is requested.
 * Sets the ``Expires`` header to the current date/time plus the defined
   ``CACHE_MIDDLEWARE_SECONDS``.
+  :setting:`CACHE_MIDDLEWARE_SECONDS`.
 * Sets the ``Cache-Control`` header to give a max age for the page -- again,
   from the ``CACHE_MIDDLEWARE_SECONDS`` setting.
+  from the :setting:`CACHE_MIDDLEWARE_SECONDS` setting.
 See :ref:`topics-http-middleware` for more on middleware.
 …
 If a view sets its own cache expiry time (i.e. it has a ``max-age`` section in
 its ``Cache-Control`` header) then the page will be cached until the expiry
 time, rather than ``CACHE_MIDDLEWARE_SECONDS``. Using the decorators in
 ``django.views.decorators.cache`` you can easily set a view's expiry time
+time, rather than :setting:`CACHE_MIDDLEWARE_SECONDS`. Using the decorators in
+:mod:`django.views.decorators.cache` you can easily set a view's expiry time
 (using the ``cache_control`` decorator) or disable caching for a view (using
 the ``never_cache`` decorator). See the `using other headers`__ section for
 more on these decorators.
 …
 ==================
 A more granular way to use the caching framework is by caching the output of
 individual views. ``django.views.decorators.cache`` defines a ``cache_page``
+individual views. :mod:`django.views.decorators.cache` defines a ``cache_page``
 decorator that will automatically cache the view's response for you. It's easy
 to use::
 …
     {% endcache %}
 Sometimes you might want to cache multiple copies of a fragment depending on
 some dynamic data that appears inside the fragment. For example, you might want a
+separate cached copy of the sidebar used in the previous example for every user
+of your site. Do this by passing additional arguments to the ``{% cache %}``
 template tag to uniquely identify the cache fragment::
+some dynamic data that appears inside the fragment. For example, you might want
+a separate cached copy of the sidebar used in the previous example for every
+user of your site. Do this by passing additional arguments to the ``{% cache
+%}`` template tag to uniquely identify the cache fragment::
     {% load cache %}
     {% cache 500 sidebar request.user.username %}
 …
 intensive database query. In cases like this, you can use the low-level cache
 API to store objects in the cache with any level of granularity you like.
 The cache API is simple. The cache module, ``django.core.cache``, exports a
 ``cache`` object that's automatically created from the ``CACHE_BACKEND``
+The cache API is simple. The cache module, :mod:`django.core.cache`, exports a
+``cache`` object that's automatically created from the :setting:`CACHE_BACKEND`
 setting::
     >>> from django.core.cache import cache
 …
     'hello, world!'
 The ``timeout_seconds`` argument is optional and defaults to the ``timeout``
 argument in the ``CACHE_BACKEND`` setting (explained above).
+argument in the :setting:`CACHE_BACKEND` setting (explained above).
 If the object doesn't exist in the cache, ``cache.get()`` returns ``None``::
 …
 For explanation of Cache-Control HTTP directives, see the `Cache-Control spec`_.
 (Note that the caching middleware already sets the cache header's max-age with
 the value of the ``CACHE_MIDDLEWARE_SETTINGS`` setting. If you use a custom
 ``max_age`` in a ``cache_control`` decorator, the decorator will take
+the value of the :setting:`CACHE_MIDDLEWARE_SETTINGS` setting. If you use a
+custom ``max_age`` in a ``cache_control`` decorator, the decorator will take
 precedence, and the header values will be merged correctly.)
 If you want to use headers to disable caching altogether,
 ``django.views.decorators.cache.never_cache`` is a view decorator that adds
+headers to ensure the response won't be cached by browsers or other caches. Example::
+headers to ensure the response won't be cached by browsers or other caches.
+Example::
     from django.views.decorators.cache import never_cache
     @never_cache
 …
 ===========================
 If you use caching middleware, it's important to put each half in the right
 place within the ``MIDDLEWARE_CLASSES`` setting. That's because the cache
+place within the :setting:`MIDDLEWARE_CLASSES` setting. That's because the cache
 middleware needs to know which headers by which to vary the cache storage.
 Middleware always adds something to the ``Vary`` response header when it can.

docs/topics/db/transactions.txt

diff --git a/docs/topics/db/transactions.txt b/docs/topics/db/transactions.txt

-              a
 transactions.
 To activate this feature, just add the ``TransactionMiddleware`` middleware to
 your ``MIDDLEWARE_CLASSES`` setting::
+your :setting:`MIDDLEWARE_CLASSES` setting::
     MIDDLEWARE_CLASSES = (
         'django.contrib.sessions.middleware.SessionMiddleware',
 …
 =================================================
 Control freaks can totally disable all transaction management by setting
+``DISABLE_TRANSACTION_MANAGEMENT`` to ``True`` in the Django settings file.
+:setting:`DISABLE_TRANSACTION_MANAGEMENT` to ``True`` in the Django settings
+file.
 If you do this, Django won't provide any automatic transaction management
 whatsoever. Middleware will no longer implicitly commit transactions, and

docs/topics/email.txt

diff --git a/docs/topics/email.txt b/docs/topics/email.txt

-              a
 Django provides a couple of light wrappers over it, to make sending e-mail
 extra quick.
 The code lives in a single module: ``django.core.mail``.
+The code lives in a single module: :mod:`django.core.mail`.
 .. _smtplib library: http://docs.python.org/library/smtplib.html
 …
 .. note::
     The character set of e-mail sent with ``django.core.mail`` will be set to
+    The character set of e-mail sent with :mod:`django.core.mail` will be set to
     the value of your :setting:`DEFAULT_CHARSET` setting.
 send_mail()
 …
       possible exceptions, all of which are subclasses of ``SMTPException``.
     * ``auth_user``: The optional username to use to authenticate to the SMTP
       server. If this isn't provided, Django will use the value of the
       ``EMAIL_HOST_USER`` setting.
+      :setting:`EMAIL_HOST_USER` setting.
     * ``auth_password``: The optional password to use to authenticate to the
       SMTP server. If this isn't provided, Django will use the value of the
       ``EMAIL_HOST_PASSWORD`` setting.
+      :setting:`EMAIL_HOST_PASSWORD` setting.
 .. _smtplib docs: http://docs.python.org/library/smtplib.html
 …
 Django's ``send_mail()`` and ``send_mass_mail()`` functions are actually thin
 wrappers that make use of the ``EmailMessage`` and ``SMTPConnection`` classes
 in ``django.core.mail``.  If you ever need to customize the way Django sends
+in :mod:`django.core.mail`.  If you ever need to customize the way Django sends
 e-mail, you can subclass these two classes to suit your needs.
 .. note::

docs/topics/files.txt

diff --git a/docs/topics/files.txt b/docs/topics/files.txt

-              a
 -------------------------------------
 Django ships with a built-in ``FileSystemStorage`` class (defined in
 ``django.core.files.storage``) which implements basic local filesystem file
+:mod:`django.core.files.storage`) which implements basic local filesystem file
 storage. Its initializer takes two arguments:
 ======================  ===================================================
 …
 ======================  ===================================================
 ``location``            Optional. Absolute path to the directory that will
                         hold the files. If omitted, it will be set to the
                         value of your ``MEDIA_ROOT`` setting.
+                        value of your :setting:`MEDIA_ROOT` setting.
 ``base_url``            Optional. URL that serves the files stored at this
                         location. If omitted, it will default to the value
                         of your ``MEDIA_URL`` setting.
+                        of your :setting:`MEDIA_URL` setting.
 ======================  ===================================================
 For example, the following code will store uploaded files under
 ``/media/photos`` regardless of what your ``MEDIA_ROOT`` setting is::
+``/media/photos`` regardless of what your :setting:`MEDIA_ROOT` setting is::
     from django.db import models
     from django.core.files.storage import FileSystemStorage

docs/topics/forms/index.txt

diff --git a/docs/topics/forms/index.txt b/docs/topics/forms/index.txt

-              a
 .. highlightlang:: html+django
 ``django.forms`` is Django's form-handling library.
+:mod:`django.forms` is Django's form-handling library.
 While it is possible to process form submissions just using Django's
 :class:`~django.http.HttpRequest` class, using the form library takes care of a
 …
 The library is decoupled from the other Django components, such as the database
 layer, views and templates. It relies only on Django settings, a couple of
+``django.utils`` helper functions and Django's internationalization hooks (but
 you're not required to be using internationalization features to use this
+:mod:`django.utils` helper functions and Django's internationalization hooks
+(but you're not required to be using internationalization features to use this
 library).
 Form objects

docs/topics/forms/media.txt

diff --git a/docs/topics/forms/media.txt b/docs/topics/forms/media.txt

-              a
     If you like the widgets that the Django Admin application uses,
     feel free to use them in your own application! They're all stored
     in ``django.contrib.admin.widgets``.
+    in :mod:`django.contrib.admin.widgets`.
 .. admonition:: Which JavaScript toolkit?
 …
 Paths used to specify media can be either relative or absolute. If a path
 starts with '/', 'http://' or 'https://', it will be interpreted as an absolute
 path, and left as-is. All other paths will be prepended with the value of
 ``settings.MEDIA_URL``. For example, if the MEDIA_URL for your site was
+:setting:`settings.MEDIA_URL<MEDIA_URL>`. For example, if the MEDIA_URL for your site was
 ``http://media.example.com/``::
     class CalendarWidget(forms.TextInput):

docs/topics/forms/modelforms.txt

diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt

-              a
                                      below)
     ``NullBooleanField``             ``CharField``
     ``PhoneNumberField``             ``USPhoneNumberField``
                                      (from ``django.contrib.localflavor.us``)
+                                     (from :mod:`django.contrib.localflavor.us`)
     ``PositiveIntegerField``         ``IntegerField``
     ``PositiveSmallIntegerField``    ``IntegerField``
     ``SlugField``                    ``SlugField``

docs/topics/http/file-uploads.txt

diff --git a/docs/topics/http/file-uploads.txt b/docs/topics/http/file-uploads.txt

-              a
         Defaults to your system's standard temporary directory (i.e. ``/tmp`` on
         most Unix-like systems).
     :setting:`FILE_UPLOAD_PERMISSIONS`
         The numeric mode (i.e. ``0644``) to set newly uploaded files to. For
         more information about what these modes mean, see the `documentation for
         os.chmod`_
         If this isn't given or is ``None``, you'll get operating-system
         dependent behavior. On most platforms, temporary files will have a mode
         of ``0600``, and files saved from memory will be saved using the
         system's standard umask.
         .. warning::
             If you're not familiar with file modes, please note that the leading
             ``0`` is very important: it indicates an octal number, which is the
             way that modes must be specified. If you try to use ``644``, you'll
 …
         Which means "try to upload to memory first, then fall back to temporary
         files."
 .. _documentation for os.chmod: http://docs.python.org/lib/os-file-dir.html
+.. _documentation for os.chmod: http://docs.python.org/lib/os-file-dir.html
 ``UploadedFile`` objects
 ========================
 …
     ``UploadedFile.temporary_file_path()``
         Only files uploaded onto disk will have this method; it returns the full
         path to the temporary uploaded file.
 .. note::
     Like regular Python files, you can read the file line-by-line simply by
     iterating over the uploaded file:
     .. code-block:: python
         for line in uploadedfile:
             do_something_with(line)
     However, *unlike* standard Python files, :class:`UploadedFile` only
     understands ``\n`` (also known as "Unix-style") line endings. If you know
     that you need to handle uploaded files with different line endings, you'll
 …
 When a user uploads a file, Django passes off the file data to an *upload
 handler* -- a small class that handles file data as it gets uploaded. Upload
 handlers are initially defined in the ``FILE_UPLOAD_HANDLERS`` setting, which
 defaults to::
+handlers are initially defined in the :setting:`FILE_UPLOAD_HANDLERS` setting,
+which defaults to::
     ("django.core.files.uploadhandler.MemoryFileUploadHandler",
      "django.core.files.uploadhandler.TemporaryFileUploadHandler",)
 …
 Sometimes particular views require different upload behavior. In these cases,
 you can override upload handlers on a per-request basis by modifying
 ``request.upload_handlers``. By default, this list will contain the upload
 handlers given by ``FILE_UPLOAD_HANDLERS``, but you can modify the list as you
 would any other list.
+handlers given by :setting:`FILE_UPLOAD_HANDLERS`, but you can modify the list
+as you would any other list.
 For instance, suppose you've written a ``ProgressBarUploadHandler`` that
 provides feedback on upload progress to some sort of AJAX widget. You'd add this

docs/topics/http/sessions.txt

diff --git a/docs/topics/http/sessions.txt b/docs/topics/http/sessions.txt

-              a
 To enable session functionality, do the following:
+    * Edit the ``MIDDLEWARE_CLASSES`` setting and make sure
+      ``MIDDLEWARE_CLASSES`` contains ``'django.contrib.sessions.middleware.SessionMiddleware'``.
+      The default ``settings.py`` created by ``django-admin.py startproject`` has
+    * Edit the :setting:`MIDDLEWARE_CLASSES` setting and make sure
+      :setting:`MIDDLEWARE_CLASSES` contains
+      ``'django.contrib.sessions.middleware.SessionMiddleware'``.  The default
+      ``settings.py`` created by ``django-admin.py startproject`` has
       ``SessionMiddleware`` activated.
     * Add ``'django.contrib.sessions'`` to your ``INSTALLED_APPS`` setting,
       and run ``manage.py syncdb`` to install the single database table
+    * Add ``'django.contrib.sessions'`` to your :setting:`INSTALLED_APPS`
+      setting, and run ``manage.py syncdb`` to install the single database table
       that stores session data.
 .. versionchanged:: 1.0
    This step is optional if you're not using the database session backend;
    see `configuring the session engine`_.
 If you don't want to use sessions, you might as well remove the
+``SessionMiddleware`` line from ``MIDDLEWARE_CLASSES`` and ``'django.contrib.sessions'``
+from your ``INSTALLED_APPS``. It'll save you a small bit of overhead.
+``SessionMiddleware`` line from :setting:`MIDDLEWARE_CLASSES` and
+``'django.contrib.sessions'`` from your :setting:`INSTALLED_APPS`. It'll save
+you a small bit of overhead.
 Configuring the session engine
 ==============================
 …
 For better performance, you may want to use a cache-based session backend.
 .. versionchanged:: 1.1
    Django 1.0 did not include the ``cached_db`` session backend.
 To store session data using Django's cache system, you'll first need to make
 …
 Using file-based sessions
 -------------------------
 To use file-based sessions, set the ``SESSION_ENGINE`` setting to
+To use file-based sessions, set the :setting:`SESSION_ENGINE` setting to
 ``"django.contrib.sessions.backends.file"``.
 You might also want to set the ``SESSION_FILE_PATH`` setting (which defaults
+to output from ``tempfile.gettempdir()``, most likely ``/tmp``) to control
+where Django stores session files. Be sure to check that your Web server has
 permissions to read and write to this location.
+You might also want to set the :setting:`SESSION_FILE_PATH` setting (which
+defaults to output from ``tempfile.gettempdir()``, most likely ``/tmp``) to
+control where Django stores session files. Be sure to check that your Web server
+has permissions to read and write to this location.
 Using sessions in views
 =======================
 …
     * ``clear()``
 .. versionadded:: 1.0
    ``setdefault()`` and ``clear()`` are new in this version.
 It also has these methods:
 …
       Returns the number of seconds until this session expires. For sessions
       with no custom expiration (or those set to expire at browser close), this
       will equal ``settings.SESSION_COOKIE_AGE``.
+      will equal :setting:`setting.SESSION_COOKIE_AGE<SESSION_COOKIE_AGE>`.
     * ``get_expiry_date()``
 …
       Returns the date this session will expire. For sessions with no custom
       expiration (or those set to expire at browser close), this will equal the
+      date ``settings.SESSION_COOKIE_AGE`` seconds from now.
+      date :setting:`settings.SESSION_COOKIE_AGE<SESSION_COOKIE_AGE>` seconds
+      from now.
     * ``get_expire_at_browser_close()``
 …
     datetime.datetime(2005, 8, 20, 13, 35, 0)
     >>> s.save()
 If you're using the ``django.contrib.sessions.backends.db`` backend, each
+If you're using the :mod:`django.contrib.sessions.backends.db` backend, each
 session is just a normal Django model. The ``Session`` model is defined in
 ``django/contrib/sessions/models.py``. Because it's a normal model, you can
 access sessions using the normal Django database API::
 …
     request.session.modified = True
 To change this default behavior, set the ``SESSION_SAVE_EVERY_REQUEST`` setting
+to ``True``. If ``SESSION_SAVE_EVERY_REQUEST`` is ``True``, Django will save
 the session to the database on every single request.
+To change this default behavior, set the :setting:`SESSION_SAVE_EVERY_REQUEST`
+setting to ``True``. If ``SESSION_SAVE_EVERY_REQUEST`` is ``True``, Django will
+save the session to the database on every single request.
 Note that the session cookie is only sent when a session has been created or
 modified. If ``SESSION_SAVE_EVERY_REQUEST`` is ``True``, the session cookie
 …
 ===============================================
 You can control whether the session framework uses browser-length sessions vs.
 persistent sessions with the ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` setting.
+persistent sessions with the :setting:`SESSION_EXPIRE_AT_BROWSER_CLOSE` setting.
 By default, ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` is set to ``False``, which
 means session cookies will be stored in users' browsers for as long as
 ``SESSION_COOKIE_AGE``. Use this if you don't want people to have to log in
+:setting:`SESSION_COOKIE_AGE`. Use this if you don't want people to have to log in
 every time they open a browser.
 If ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` is set to ``True``, Django will use
 …
 Settings
 ========
+A few :ref:`Django settings <ref-settings>` give you control over session behavior:
+A few :ref:`Django settings <ref-settings>` give you control over session
+behavior:
 SESSION_ENGINE
 --------------
 .. versionadded:: 1.0
 Default: ``django.contrib.sessions.backends.db``
+Default: :mod:`django.contrib.sessions.backends.db`
 Controls where Django stores session data. Valid values are:

docs/topics/http/shortcuts.txt

diff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt

-              a
 Django shortcut functions
 =========================
 The package ``django.shortcuts`` collects helper functions and classes that
+The package :mod:`django.shortcuts` collects helper functions and classes that
 "span" multiple levels of MVC. In other words, these functions/classes
 introduce controlled coupling for convenience's sake.

docs/topics/http/urls.txt

diff --git a/docs/topics/http/urls.txt b/docs/topics/http/urls.txt

-              a
 When a user requests a page from your Django-powered site, this is the
 algorithm the system follows to determine which Python code to execute:
 . Django determines the root URLconf module to use. Ordinarily,
        this is the value of the ``ROOT_URLCONF`` setting, but if the incoming
+. Django determines the root URLconf module to use. Ordinarily, this is the
+       value of the :setting:`ROOT_URLCONF` setting, but if the incoming
        ``HttpRequest`` object has an attribute called ``urlconf``, its value
        will be used in place of the ``ROOT_URLCONF`` setting.
 . Django loads that Python module and looks for the variable
        ``urlpatterns``. This should be a Python list, in the format returned by
        the function ``django.conf.urls.defaults.patterns()``.
 . Django runs through each URL pattern, in order, and stops at the first
        one that matches the requested URL.
 . Once one of the regexes matches, Django imports and calls the given
        view, which is a simple Python function. The view gets passed an
        :class:`~django.http.HttpRequest` as its first argument and any values
 …
 If you need to use something similar to the :ttag:`url` template tag in
 your code, Django provides the following method (in the
 ``django.core.urlresolvers`` module):
+:mod:`django.core.urlresolvers` module):
 .. currentmodule:: django.core.urlresolvers
 .. function:: reverse(viewname, urlconf=None, args=None, kwargs=None)

docs/topics/http/views.txt

diff --git a/docs/topics/http/views.txt b/docs/topics/http/views.txt

-              a
 Let's step through this code one line at a time:
     * First, we import the class ``HttpResponse``, which lives in the
       ``django.http`` module, along with Python's ``datetime`` library.
+      :mod:`django.http` module, along with Python's ``datetime`` library.
     * Next, we define a function called ``current_datetime``. This is the view
       function. Each view function takes an ``HttpRequest`` object as its first
 …
       later.)
 .. admonition:: Django's Time Zone
     Django includes a ``TIME_ZONE`` setting that defaults to
+    Django includes a :setting:`TIME_ZONE` setting that defaults to
     ``America/Chicago``. This probably isn't where you live, so you might want
     to change it in your settings file.
 …
       in the 404.
     * The 404 view is passed a ``RequestContext`` and will have access to
       variables supplied by your ``TEMPLATE_CONTEXT_PROCESSORS`` setting (e.g.,
       ``MEDIA_URL``).
+      variables supplied by your :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting
+      (e.g., :setting:`MEDIA_URL`).
+    * If ``DEBUG`` is set to ``True`` (in your settings module), then your 404
+      view will never be used, and the traceback will be displayed instead.
+    * If :setting:`DEBUG` is set to ``True`` (in your settings module), then
+      your 404 view will never be used, and the traceback will be displayed
+      instead.
 The 500 (server error) view
 ----------------------------
 …
     handler500 = 'mysite.views.my_custom_error_view'
 Behind the scenes, Django determines the error view by looking for ``handler500``.
 By default, URLconfs contain the following line::
+Behind the scenes, Django determines the error view by looking for
+``handler500``.  By default, URLconfs contain the following line::
     from django.conf.urls.defaults import *

docs/topics/i18n.txt

diff --git a/docs/topics/i18n.txt b/docs/topics/i18n.txt

-              a
 optimizations so as not to load the internationalization machinery.
 You'll probably also want to remove ``'django.core.context_processors.i18n'``
 from your ``TEMPLATE_CONTEXT_PROCESSORS`` setting.
+from your :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.
 If you do need internationalization: three steps
 ================================================
 …
 Each ``RequestContext`` has access to three translation-specific variables:
     * ``LANGUAGES`` is a list of tuples in which the first element is the
+    * :setting:`LANGUAGES` is a list of tuples in which the first element is the
       language code and the second is the language name (translated into the
       currently active locale).
 …
 The allow_lazy() decorator
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 Django offers many utility functions (particularly in ``django.utils``) that
+Django offers many utility functions (particularly in :mod:`django.utils`) that
 take a string as their first argument and do something to that string. These
 functions are used by template filters as well as directly in other code.
 …
 selection based on data from the request. It customizes content for each user.
 To use ``LocaleMiddleware``, add ``'django.middleware.locale.LocaleMiddleware'``
 to your ``MIDDLEWARE_CLASSES`` setting. Because middleware order matters, you
 should follow these guidelines:
+to your :setting:`MIDDLEWARE_CLASSES` setting. Because middleware order matters,
+you should follow these guidelines:
     * Make sure it's one of the first middlewares installed.
     * It should come after ``SessionMiddleware``, because ``LocaleMiddleware``
       makes use of session data.
     * If you use ``CacheMiddleware``, put ``LocaleMiddleware`` after it.
 For example, your ``MIDDLEWARE_CLASSES`` might look like this::
+For example, your :setting:`MIDDLEWARE_CLASSES` might look like this::
     MIDDLEWARE_CLASSES = (
        'django.contrib.sessions.middleware.SessionMiddleware',
 …
       In Django version 0.96 and before, the cookie's name is hard-coded to
       ``django_language``. In Django 1,0, The cookie name is set by the
       ``LANGUAGE_COOKIE_NAME`` setting. (The default name is
+      :setting:`LANGUAGE_COOKIE_NAME` setting. (The default name is
       ``django_language``.)
     * Failing that, it looks at the ``Accept-Language`` HTTP header. This
 …
       prefer, in order by priority. Django tries each language in the header
       until it finds one with available translations.
     * Failing that, it uses the global ``LANGUAGE_CODE`` setting.
+    * Failing that, it uses the global :setting:`LANGUAGE_CODE` setting.
 .. _locale-middleware-notes:
 …
     * Only languages listed in the :setting:`LANGUAGES` setting can be selected.
       If you want to restrict the language selection to a subset of provided
       languages (because your application doesn't provide all those languages),
       set ``LANGUAGES`` to a list of languages. For example::
+      set :setting:`LANGUAGES` to a list of languages. For example::
           LANGUAGES = (
             ('de', _('German')),
 …
       .. _LANGUAGES setting: ../settings/#languages
     * If you define a custom ``LANGUAGES`` setting, as explained in the
       previous bullet, it's OK to mark the languages as translation strings
       -- but use a "dummy" ``ugettext()`` function, not the one in
       ``django.utils.translation``. You should *never* import
       ``django.utils.translation`` from within your settings file, because that
       module in itself depends on the settings, and that would cause a circular
       import.
+    * If you define a custom :setting:`LANGUAGES` setting, as explained in the
+      previous bullet, it's OK to mark the languages as translation strings --
+      but use a "dummy" ``ugettext()`` function, not the one in
+      :mod:`django.utils.translation`. You should *never* import
+      :mod:`django.utils.translation` from within your settings file, because
+      that module in itself depends on the settings, and that would cause a
+      circular import.
       The solution is to use a "dummy" ``ugettext()`` function. Here's a sample
       settings file::
 …
       With this arrangement, ``django-admin.py makemessages`` will still find
       and mark these strings for translation, but the translation won't happen
       at runtime -- so you'll have to remember to wrap the languages in the
+      *real* ``ugettext()`` in any code that uses ``LANGUAGES`` at runtime.
+      *real* ``ugettext()`` in any code that uses :setting:`LANGUAGES` at
+      runtime.
     * The ``LocaleMiddleware`` can only select languages for which there is a
       Django-provided base translation. If you want to provide translations
 …
       Technical message IDs are easily recognized; they're all upper case. You
       don't translate the message ID as with other messages, you provide the
       correct local variant on the provided English value. For example, with
+      ``DATETIME_FORMAT`` (or ``DATE_FORMAT`` or ``TIME_FORMAT``), this would
+      be the format string that you want to use in your language. The format
+      is identical to the format strings used by the ``now`` template tag.
+      :setting:`DATETIME_FORMAT` (or :setting:`DATE_FORMAT` or
+      :setting:`TIME_FORMAT`), this would be the format string that you want to
+      use in your language. The format is identical to the format strings used
+      by the ``now`` template tag.
 Once ``LocaleMiddleware`` determines the user's preference, it makes this
 preference available as ``request.LANGUAGE_CODE`` for each
 …
             return HttpResponse("You prefer to read another language.")
 Note that, with static (middleware-less) translation, the language is in
+``settings.LANGUAGE_CODE``, while with dynamic (middleware) translation, it's
 in ``request.LANGUAGE_CODE``.
+:setting:`settings.LANGUAGE_CODE<LANGUAGE_CODE>`, while with dynamic
+(middleware) translation, it's in ``request.LANGUAGE_CODE``.
 .. _settings file: ../settings/
 .. _middleware documentation: ../middleware/
 …
     * ``$APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)``
     * ``$PROJECTPATH/locale/<language>/LC_MESSAGES/django.(po|mo)``
     * All paths listed in ``LOCALE_PATHS`` in your settings file are
+    * All paths listed in :setting:`LOCALE_PATHS` in your settings file are
       searched in that order for ``<language>/LC_MESSAGES/django.(po|mo)``
     * ``$PYTHONPATH/django/conf/locale/<language>/LC_MESSAGES/django.(po|mo)``
 …
 to produce the binary ``django.mo`` files that are used by ``gettext``.
 You can also run ``django-admin.py compilemessages --settings=path.to.settings``
 to make the compiler process all the directories in your ``LOCALE_PATHS``
+to make the compiler process all the directories in your :setting:`LOCALE_PATHS`
 setting.
 Application message files are a bit complicated to discover -- they need the
 …
 parameter set in request. If session support is enabled, the view
 saves the language choice in the user's session. Otherwise, it saves the
 language choice in a cookie that is by default named ``django_language``.
 (The name can be changed through the ``LANGUAGE_COOKIE_NAME`` setting.)
+(The name can be changed through the :setting:`LANGUAGE_COOKIE_NAME` setting.)
 After setting the language choice, Django redirects the user, following this
 algorithm:
 …
         (r'^jsi18n/$', 'django.views.i18n.javascript_catalog', js_info_dict),
+    )
 Each string in ``packages`` should be in Python dotted-package syntax (the
+same format as the strings in ``INSTALLED_APPS``) and should refer to a package
+that contains a ``locale`` directory. If you specify multiple packages, all
 those catalogs are merged into one catalog. This is useful if you have
+Each string in ``packages`` should be in Python dotted-package syntax (the same
+format as the strings in :setting:`INSTALLED_APPS`) and should refer to a
+package that contains a ``locale`` directory. If you specify multiple packages,
+all those catalogs are merged into one catalog. This is useful if you have
 JavaScript that uses strings from different applications.
 You can make the view dynamic by putting the packages into the URL pattern::
 …
 signs in the URL. This is especially useful if your pages use code from
 different apps and this changes often and you don't want to pull in one big
 catalog file. As a security measure, these values can only be either
 ``django.conf`` or any package from the ``INSTALLED_APPS`` setting.
+``django.conf`` or any package from the :setting:`INSTALLED_APPS` setting.
 Using the JavaScript translation catalog
 ----------------------------------------
 …
       * Add ``;C:\Program Files\gettext-utils\bin`` at the end of the
         ``Variable value`` field
 You may also use ``gettext`` binaries you have obtained elsewhere, so long as
+You may also use ``gettext`` binaries you have obtained elsewhere, so long as
 the ``xgettext --version`` command works properly. Some version 0.14.4 binaries
 have been found to not support this command. Do not attempt to use Django
+have been found to not support this command. Do not attempt to use Django
 translation utilities with a ``gettext`` package if the command ``xgettext
 --version`` entered at a Windows command prompt causes a popup window saying
 "xgettext.exe has generated errors and will be closed by Windows".

docs/topics/templates.txt

diff --git a/docs/topics/templates.txt b/docs/topics/templates.txt

-              a
 In the above example, ``{{ section.title }}`` will be replaced with the
 ``title`` attribute of the ``section`` object.
 If you use a variable that doesn't exist, the template system will insert
+the value of the ``TEMPLATE_STRING_IF_INVALID`` setting, which is set to ``''``
 (the empty string) by default.
+If you use a variable that doesn't exist, the template system will insert the
+value of the :setting:`TEMPLATE_STRING_IF_INVALID` setting, which is set to
+``''`` (the empty string) by default.
 See `Using the built-in reference`_, below, for help on finding what variables
 are available in a given template.
 …
         If ``value`` isn't provided or is empty, the above will display
         "``nothing``".
     :tfilter:`length`
         Returns the length of the value. This works for both strings and lists;
         for example::
 …
             {{ value|length }}
         If ``value`` is ``['a', 'b', 'c', 'd']``, the output will be ``4``.
     :tfilter:`striptags`
         Strips all [X]HTML tags. For example::
 …
                 <li>{{ athlete.name }}</li>
             {% endfor %}
             </ul>
     :ttag:`if` and :ttag:`else`
         Evaluates a variable, and if that variable is "true" the contents of the
         block are displayed::
 …
         In the above, if ``athlete_list`` is not empty, the number of athletes
         will be displayed by the ``{{ athlete_list|length }}`` variable.
     :ttag:`ifequal` and :ttag:`ifnotequal`
         Display some contents if two arguments are or are not equal. For example::
 …
             {% ifnotequal athlete.name "Joe" %}
                 ...
             {% endifnotequal %}
     :ttag:`block` and :ttag:`extends`
         Set up `template inheritance`_ (see below), a powerful way
         of cutting down on "boilerplate" in templates.
 …
 Example::
     {% load comments i18n %}
 See :ref:`howto-custom-template-tags` for information on writing your own custom
 template libraries.

docs/topics/testing.txt

diff --git a/docs/topics/testing.txt b/docs/topics/testing.txt

-              a
 Note that we used ``animals``, not ``myproject.animals``.
 .. versionadded:: 1.0
    You can now choose which test to run.
 If you use unit tests, as opposed to
 …
 Overview and a quick example
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 To use the test client, instantiate ``django.test.client.Client`` and retrieve
 Web pages::
+To use the test client, instantiate :class:`django.test.client.Client` and
+retrieve Web pages::
     >>> from django.test.client import Client
     >>> c = Client()
 …
 Making requests
 ~~~~~~~~~~~~~~~
 Use the ``django.test.client.Client`` class to make requests. It requires no
 arguments at time of construction:
+Use the :class:`django.test.client.Client` class to make requests. It requires
+no arguments at time of construction:
 .. class:: Client()
 …
 This class provides some additional capabilities that can be useful for testing
 Web sites.
 Converting a normal ``unittest.TestCase`` to a Django ``TestCase`` is easy:
 just change the base class of your test from ``unittest.TestCase`` to
+``django.test.TestCase``. All of the standard Python unit test functionality
+will continue to be available, but it will be augmented with some useful
 additions.
+Converting a normal ``unittest.TestCase`` to a Django ``TestCase`` is easy: just
+change the base class of your test from ``unittest.TestCase`` to
+:class:`django.test.TestCase`. All of the standard Python unit test
+functionality will continue to be available, but it will be augmented with some
+useful additions.
 .. versionadded:: 1.1
 .. class:: TransactionTestCase()
 Django ``TestCase`` classes make use of database transaction facilities, if
 available, to speed up the process of resetting the database to a known state
 at the beginning of each test. A consequence of this, however, is that the
 effects of transaction commit and rollback cannot be tested by a Django
 ``TestCase`` class. If your test requires testing of such transactional
+Django ``TestCase`` classes make use of database transaction facilities, if
+available, to speed up the process of resetting the database to a known state
+at the beginning of each test. A consequence of this, however, is that the
+effects of transaction commit and rollback cannot be tested by a Django
+``TestCase`` class. If your test requires testing of such transactional
 behavior, you should use a Django ``TransactionTestCase``.
 ``TransactionTestCase`` and ``TestCase`` are identical except for the manner
 in which the database is reset to a known state and the ability for test code
 to test the effects of commit and rollback. A ``TranscationTestCase`` resets
 the database before the test runs by truncating all tables and reloading
 initial data. A ``TransactionTestCase`` may call commit and rollback and
 observe the effects of these calls on the database.
+``TransactionTestCase`` and ``TestCase`` are identical except for the manner
+in which the database is reset to a known state and the ability for test code
+to test the effects of commit and rollback. A ``TranscationTestCase`` resets
+the database before the test runs by truncating all tables and reloading
+initial data. A ``TransactionTestCase`` may call commit and rollback and
+observe the effects of these calls on the database.
 A ``TestCase``, on the other hand, does not truncate tables and reload initial
 data at the beginning of a test. Instead, it encloses the test code in a
 database transaction that is rolled back at the end of the test.  It also
 prevents the code under test from issuing any commit or rollback operations
 on the database, to ensure that the rollback at the end of the test restores
 the database to its initial state. In order to guarantee that all ``TestCase``
 code starts with a clean database, the Django test runner runs all ``TestCase``
 tests first, before any other tests (e.g. doctests) that may alter the
+A ``TestCase``, on the other hand, does not truncate tables and reload initial
+data at the beginning of a test. Instead, it encloses the test code in a
+database transaction that is rolled back at the end of the test.  It also
+prevents the code under test from issuing any commit or rollback operations
+on the database, to ensure that the rollback at the end of the test restores
+the database to its initial state. In order to guarantee that all ``TestCase``
+code starts with a clean database, the Django test runner runs all ``TestCase``
+tests first, before any other tests (e.g. doctests) that may alter the
 database without restoring it to its original state.
 When running on a database that does not support rollback (e.g. MySQL with the
 MyISAM storage engine), ``TestCase`` falls back to initializing the database
+When running on a database that does not support rollback (e.g. MySQL with the
+MyISAM storage engine), ``TestCase`` falls back to initializing the database
 by truncating tables and reloading initial data.
 .. note::
     The ``TestCase`` use of rollback to un-do the effects of the test code
     may reveal previously-undetected errors in test code.  For example,
     test code that assumes primary keys values will be assigned starting at
     one may find that assumption no longer holds true when rollbacks instead
     of table truncation are being used to reset the database.  Similarly,
     the reordering of tests so that all ``TestCase`` classes run first may
     reveal unexpected dependencies on test case ordering.  In such cases a
+    The ``TestCase`` use of rollback to un-do the effects of the test code
+    may reveal previously-undetected errors in test code.  For example,
+    test code that assumes primary keys values will be assigned starting at
+    one may find that assumption no longer holds true when rollbacks instead
+    of table truncation are being used to reset the database.  Similarly,
+    the reordering of tests so that all ``TestCase`` classes run first may
+    reveal unexpected dependencies on test case ordering.  In such cases a
     quick fix is to switch the ``TestCase`` to a ``TransactionTestCase``.
     A better long-term fix, that allows the test to take advantage of the
     speed benefit of ``TestCase``, is to fix the underlying test problem.
 Default test client
 ~~~~~~~~~~~~~~~~~~~
 …
 .. attribute:: TestCase.client
 Every test case in a ``django.test.TestCase`` instance has access to an
+Every test case in a :class:`django.test.TestCase` instance has access to an
 instance of a Django test client. This client can be accessed as
 ``self.client``. This client is recreated for each test, so you don't have to
 worry about state (such as cookies) carrying over from one test to another.
 …
 Once you've created a fixture and placed it somewhere in your Django project,
 you can use it in your unit tests by specifying a ``fixtures`` class attribute
 on your ``django.test.TestCase`` subclass::
+on your :class:`django.test.TestCase` subclass::
     from django.test import TestCase
     from myapp.models import Animal
 …
 particular URL.
 In order to provide a reliable URL space for your test,
 ``django.test.TestCase`` provides the ability to customize the URLconf
+:class:`django.test.TestCase` provides the ability to customize the URLconf
 configuration for the duration of the execution of a test suite. If your
 ``TestCase`` instance defines an ``urls`` attribute, the ``TestCase`` will use
 the value of that attribute as the ``ROOT_URLCONF`` for the duration of that
 test.
+the value of that attribute as the :setting:`ROOT_URLCONF` for the duration of
+that test.
 For example::
 …
    :synopsis: Helpers to write custom test runners.
 To assist in the creation of your own test runner, Django provides a number of
 utility methods in the ``django.test.utils`` module.
+utility methods in the :mod:`django.test.utils` module.
 .. function:: setup_test_environment()
 …
     Returns the name of the test database that it created.
     ``create_test_db()`` has the side effect of modifying
+    ``settings.DATABASE_NAME`` to match the name of the test database.
+    :setting:`settings.DATABASE_NAME<DATABASE_NAME>` to match the name of the
+    test database.
     .. versionchanged:: 1.0
        ``create_test_db()`` now returns the name of the test database.
 .. function:: destroy_test_db(old_database_name, verbosity=1)

Download in other formats:

Original Format

Issues

Context Navigation

Ticket #9502: 9502-r9891.diff

Download in other formats: