Ticket #9502: 9502-trunk-r9885.diff

File 9502-trunk-r9885.diff, 161.0 KB (added by Ramiro Morales, 16 years ago)

Patch for trunk, updated to r9885.

  • docs/faq/admin.txt

    diff --git a/docs/faq/admin.txt b/docs/faq/admin.txt
    a b  
    1010sent out by Django doesn't match the domain in your browser. Try these two
    1111things:
    1212
    13     * Set the ``SESSION_COOKIE_DOMAIN`` setting in your admin config file
     13    * Set the :setting:`SESSION_COOKIE_DOMAIN` setting in your admin config file
    1414      to match your domain. For example, if you're going to
    1515      "http://www.example.com/admin/" in your browser, in
    1616      "myproject.settings" you should set ``SESSION_COOKIE_DOMAIN = 'www.example.com'``.
     
    1919      don't have dots in them. If you're running the admin site on "localhost"
    2020      or another domain that doesn't have a dot in it, try going to
    2121      "localhost.localdomain" or "127.0.0.1". And set
    22       ``SESSION_COOKIE_DOMAIN`` accordingly.
     22      :setting:`SESSION_COOKIE_DOMAIN` accordingly.
    2323
    2424I 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.
    2525-----------------------------------------------------------------------------------------------------------------------------------------------------------
     
    6161My "list_filter" contains a ManyToManyField, but the filter doesn't display.
    6262----------------------------------------------------------------------------
    6363
    64 Django won't bother displaying the filter for a ``ManyToManyField`` if there
    65 are fewer than two related objects.
     64Django won't bother displaying the filter for a :class:`ManyToManyField` if
     65there are fewer than two related objects.
    6666
    6767For example, if your ``list_filter`` includes ``sites``, and there's only one
    6868site 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 b  
    66How can I see the raw SQL queries Django is running?
    77----------------------------------------------------
    88
    9 Make sure your Django ``DEBUG`` setting is set to ``True``. Then, just do
     9Make sure your Django :setting:`DEBUG` setting is set to ``True``. Then, just do
    1010this::
    1111
    1212    >>> from django.db import connection
     
    1414    [{'sql': 'SELECT polls_polls.id,polls_polls.question,polls_polls.pub_date FROM polls_polls',
    1515    'time': '0.002'}]
    1616
    17 ``connection.queries`` is only available if ``DEBUG`` is ``True``. It's a list
    18 of dictionaries in order of query execution. Each dictionary has the following::
     17:data:`connection.queries` is only available if :setting:`DEBUG` is ``True``.
     18It's a list of dictionaries in order of query execution. Each dictionary has
     19the following::
    1920
    2021    ``sql`` -- The raw SQL statement
    2122    ``time`` -- How long the statement took to execute, in seconds.
    2223
    23 ``connection.queries`` includes all SQL statements -- INSERTs, UPDATES,
     24:data:`connection.queries` includes all SQL statements -- INSERTs, UPDATES,
    2425SELECTs, etc. Each time your app hits the database, the query will be recorded.
    2526
    2627Can I use Django with a pre-existing database?
     
    7980
    8081Django isn't known to leak memory. If you find your Django processes are
    8182allocating more and more memory, with no sign of releasing it, check to make
    82 sure your ``DEBUG`` setting is set to ``False``. If ``DEBUG`` is ``True``, then
    83 Django saves a copy of every SQL statement it has executed.
     83sure your :setting:`DEBUG` setting is set to ``False``. If ``DEBUG`` is
     84``True``, then Django saves a copy of every SQL statement it has executed.
    8485
    85 (The queries are saved in ``django.db.connection.queries``. See
     86(The queries are saved in :data:`django.db.connection.queries`. See
    8687`How can I see the raw SQL queries Django is running?`_.)
    8788
    88 To fix the problem, set ``DEBUG`` to ``False``.
     89To fix the problem, set :setting:`DEBUG` to ``False``.
    8990
    9091If you need to clear the query list manually at any point in your functions,
    91 just call ``reset_queries()``, like this::
     92just call :func:`reset_queries`, like this::
    9293
    9394    from django import db
    9495    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 b  
    5353
    5454**Required**.
    5555
    56 Called by ``Storage.open()``, this is the actual mechanism the storage class
     56Called by :meth:`Storage.open`, this is the actual mechanism the storage class
    5757uses to open the file. This must return a ``File`` object, though in most cases,
    5858you'll want to return some subclass here that implements logic specific to the
    5959backend storage system.
     
    6161``_save(name, content)``
    6262~~~~~~~~~~~~~~~~~~~~~~~~
    6363
    64 Called by ``Storage.save()``. The ``name`` will already have gone through
    65 ``get_valid_name()`` and ``get_available_name()``, and the ``content`` will be a
    66 ``File`` object itself. No return value is expected.
     64Called by :meth:`Storage.save`. The ``name`` will already have gone through
     65:meth:`get_valid_name` and :meth:`get_available_name`, and the ``content`` will
     66be a :class:`File` object itself. No return value is expected.
    6767
    6868``get_valid_name(name)``
    6969------------------------
     
    7373server, after having any path information removed. Override this to customize
    7474how non-standard characters are converted to safe filenames.
    7575
    76 The code provided on ``Storage`` retains only alpha-numeric characters, periods
    77 and underscores from the original filename, removing everything else.
     76The code provided on :class:`Storage` retains only alpha-numeric characters,
     77periods and underscores from the original filename, removing everything else.n
    7878
    7979``get_available_name(name)``
    8080----------------------------
     
    8282Returns a filename that is available in the storage mechanism, possibly taking
    8383the provided filename into account. The ``name`` argument passed to this method
    8484will have already cleaned to a filename valid for the storage system, according
    85 to the ``get_valid_name()`` method described above.
     85to the :meth:`get_valid_name` method described above.
    8686
    87 The code provided on ``Storage`` simply appends underscores to the filename
     87The code provided on :class:`Storage` simply appends underscores to the filename
    8888until 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 b  
    2424        views.py
    2525
    2626In this example, the ``explode`` command will be made available to any project
    27 that includes the ``blog`` application in ``settings.INSTALLED_APPS``.
     27that includes the ``blog`` application in
     28:setting:`settings.INSTALLED_APPS<INSTALLED_APPS>`.
    2829
    2930The ``explode.py`` module has only one requirement -- it must define a class
    3031called ``Command`` that extends ``django.core.management.base.BaseCommand``.
    3132
    3233For more details on how to define your own commands, look at the code for the
    33 existing ``django-admin.py`` commands, in ``/django/core/management/commands``.
    34  No newline at end of file
     34existing ``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 b  
    2525
    2626Alternatively, you may have a complex Python object that can somehow be
    2727serialized to fit into a standard database column type. This is another case
    28 where a ``Field`` subclass will help you use your object with your models.
     28where a :class:`Field` subclass will help you use your object with your models.
    2929
    3030Our example object
    3131------------------
     
    4545            self.east = east
    4646            self.south = south
    4747            self.west = west
    48        
     48
    4949        # ... (other possibly useful methods omitted) ...
    5050
    5151.. _Bridge: http://en.wikipedia.org/wiki/Contract_bridge
     
    203203      :class:`ForeignKey`). For advanced use only.
    204204    * :attr:`~django.db.models.Field.default`
    205205    * :attr:`~django.db.models.Field.editable`
    206     * :attr:`~django.db.models.Field.serialize`: If ``False``, the field will 
     206    * :attr:`~django.db.models.Field.serialize`: If ``False``, the field will
    207207      not be serialized when the model is passed to Django's :ref:`serializers
    208208      <topics-serialization>`. Defaults to ``True``.
    209209    * :attr:`~django.db.models.Field.prepopulate_from`
     
    288288If you aim to build a database-agnostic application, you should account for
    289289differences in database column types. For example, the date/time column type
    290290in PostgreSQL is called ``timestamp``, while the same column in MySQL is called
    291 ``datetime``. The simplest way to handle this in a ``db_type()`` method is to
    292 import the Django settings module and check the :setting:`DATABASE_ENGINE` setting.
    293 For example::
     291``datetime``. The simplest way to handle this in a :meth:`db_type` method is to
     292import the Django settings module and check the :setting:`DATABASE_ENGINE`
     293setting. For example::
    294294
    295295    class MyDateField(models.Field):
    296296        def db_type(self):
     
    418418.. method:: get_db_prep_save(self, value)
    419419
    420420Same as the above, but called when the Field value must be *saved* to the
    421 database. As the default implementation just calls ``get_db_prep_value``, you
    422 shouldn't need to implement this method unless your custom field need a special
    423 conversion when being saved that is not the same as the used for normal query
    424 parameters (which is implemented by ``get_db_prep_value``).
     421database. As the default implementation just calls :meth:`get_db_prep_value`,
     422you shouldn't need to implement this method unless your custom field need a
     423special conversion when being saved that is not the same as the used for normal
     424query parameters (which is implemented by :meth:`get_db_prep_value`).
    425425
    426426Preprocessing values before saving
    427427~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     
    453453
    454454Prepares the ``value`` for passing to the database when used in a lookup (a
    455455``WHERE`` constraint in SQL). The ``lookup_type`` will be one of the valid
    456 Django filter lookups: ``exact``, ``iexact``, ``contains``, ``icontains``,
    457 ``gt``, ``gte``, ``lt``, ``lte``, ``in``, ``startswith``, ``istartswith``,
    458 ``endswith``, ``iendswith``, ``range``, ``year``, ``month``, ``day``,
    459 ``isnull``, ``search``, ``regex``, and ``iregex``.
     456Django filter lookups: :lookup:`exact`, :lookup:`iexact`, :lookup:`contains`,
     457:lookup:`icontains`, :lookup:`gt`, :lookup:`gte`, :lookup:`lt`, :lookup:`lte`,
     458:lookup:`in`, :lookup:`startswith`, :lookup:`istartswith`, :lookup:`endswith`,
     459:lookup:`iendswith`, :lookup:`range`, :lookup:`year`, :lookup:`month`,
     460:lookup:`day`, :lookup:`isnull`, :lookup:`search`, :lookup:`regex`, and
     461:lookup:`iregex`.
    460462
    461463Your method must be prepared to handle all of these ``lookup_type`` values and
    462 should raise either a ``ValueError`` if the ``value`` is of the wrong sort (a
    463 list when you were expecting an object, for example) or a ``TypeError`` if
     464should raise either a :exc:`ValueError` if the ``value`` is of the wrong sort
     465(a list when you were expecting an object, for example) or a ``TypeError`` if
    464466your field does not support that type of lookup. For many fields, you can get
    465467by with handling the lookup types that need special handling for your field
    466468and pass the rest of the :meth:`get_db_prep_lookup` method of the parent class.
    467469
    468 If you needed to implement ``get_db_prep_save()``, you will usually need to
    469 implement ``get_db_prep_lookup()``. If you don't, ``get_db_prep_value`` will be
    470 called by the default implementation, to manage ``exact``, ``gt``, ``gte``,
    471 ``lt``, ``lte``, ``in`` and ``range`` lookups.
     470If you needed to implement :meth:`get_db_prep_save`, you will usually need to
     471implement :meth:`get_db_prep_lookup`. If you don't, :meth:`get_db_prep_value`
     472will be called by the default implementation, to manage :lookup:`exact`,
     473:lookup:`gt`, :lookup:`gte`, :lookup:`lt`, :lookup:`lte`, :lookup:`in` and
     474:lookup:`range` lookups.
    472475
    473476You may also want to implement this method to limit the lookup types that could
    474477be used with your custom field type.
    475478
    476 Note that, for ``range`` and ``in`` lookups, ``get_db_prep_lookup`` will receive
    477 a list of objects (presumably of the right type) and will need to convert them
    478 to a list of things of the right type for passing to the database. Most of the
    479 time, you can reuse ``get_db_prep_value()``, or at least factor out some common
    480 pieces.
     479Note that, for :lookup:`range` and :lookup:`in` lookups,
     480:meth:`get_db_prep_lookup` will receive a list of objects (presumably of the
     481right type) and will need to convert them to a list of things of the right type
     482for passing to the database. Most of the time, you can reuse
     483:meth:`get_db_prep_value`, or at least factor out some common pieces.
    481484
    482 For example, the following code implements ``get_db_prep_lookup`` to limit the
    483 accepted lookup types to ``exact`` and ``in``::
     485For example, the following code implements :meth:`get_db_prep_lookup` to limit
     486the accepted lookup types to :lookup:`exact` and ``in``::
    484487
    485488    class HandField(models.Field):
    486489        # ...
     
    608611
    609612In addition to the above methods, fields that deal with files have a few other
    610613special requirements which must be taken into account. The majority of the
    611 mechanics provided by ``FileField``, such as controlling database storage and
    612 retrieval, can remain unchanged, leaving subclasses to deal with the challenge
    613 of supporting a particular type of file.
     614mechanics provided by :class:`FileField`, such as controlling database storage
     615and retrieval, can remain unchanged, leaving subclasses to deal with the
     616challenge of supporting a particular type of file.
    614617
    615 Django provides a ``File`` class, which is used as a proxy to the file's
     618Django provides a :class:`File` class, which is used as a proxy to the file's
    616619contents and operations. This can be subclassed to customize how the file is
    617620accessed, and what methods are available. It lives at
    618 ``django.db.models.fields.files``, and its default behavior is explained in the
    619 :ref:`file documentation <ref-files-file>`.
     621:mod:`django.db.models.fields.files`, and its default behavior is explained in
     622the :ref:`file documentation <ref-files-file>`.
    620623
    621 Once a subclass of ``File`` is created, the new ``FileField`` subclass must be
    622 told to use it. To do so, simply assign the new ``File`` subclass to the special
    623 ``attr_class`` attribute of the ``FileField`` subclass.
     624Once a subclass of :class:`File` is created, the new :class:`FileField`
     625subclass must be told to use it. To do so, simply assign the new :class:`File`
     626subclass to the special :attr:`attr_class` attribute of the ``FileField``
     627subclass.
    624628
    625629A few suggestions
    626630------------------
     
    628632In addition to the above details, there are a few guidelines which can greatly
    629633improve the efficiency and readability of the field's code.
    630634
    631     1. The source for Django's own ``ImageField`` (in
     635    1. The source for Django's own :class:`ImageField` (in
    632636       ``django/db/models/fields/files.py``) is a great example of how to
    633637       subclass ``FileField`` to support a particular type of file, as it
    634638       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 b  
    5757the given Python module name, not the name of the app.
    5858
    5959To be a valid tag library, the module must contain a module-level variable
    60 named ``register`` that is a ``template.Library`` instance, in which all the
    61 tags and filters are registered. So, near the top of your module, put the
     60named ``register`` that is a :class:`template.Library` instance, in which all
     61the tags and filters are registered. So, near the top of your module, put the
    6262following::
    6363
    6464    from django import template
     
    120120        return value.lower()
    121121
    122122This way, you'll be able to pass, say, an integer to this filter, and it
    123 won't cause an ``AttributeError`` (because integers don't have ``lower()``
     123won't cause an :exc:`AttributeError` (because integers don't have ``lower()``
    124124methods).
    125125
    126126Registering custom filters
    127127~~~~~~~~~~~~~~~~~~~~~~~~~~
    128128
    129129Once you've written your filter definition, you need to register it with
    130 your ``Library`` instance, to make it available to Django's template language::
     130your :class:`Library` instance, to make it available to Django's templatei
     131language::
    131132
    132133    register.filter('cut', cut)
    133134    register.filter('lower', lower)
    134135
    135 The ``Library.filter()`` method takes two arguments:
     136The :meth:`Library.filter` method takes two arguments:
    136137
    137138    1. The name of the filter -- a string.
    138139    2. The compilation function -- a Python function (not the name of the
    139140       function as a string).
    140141
    141 If you're using Python 2.4 or above, you can use ``register.filter()`` as a
     142If you're using Python 2.4 or above, you can use :func:`register.filter` as a
    142143decorator instead::
    143144
    144145    @register.filter(name='cut')
     
    172173      They're commonly used for output that contains raw HTML that is intended
    173174      to be interpreted as-is on the client side.
    174175
    175       Internally, these strings are of type ``SafeString`` or ``SafeUnicode``.
    176       They share a common base class of ``SafeData``, so you can test
    177       for them using code like::
     176      Internally, these strings are of type :class:`SafeString` ori
     177      :class:`SafeUnicode`. They share a common base class of
     178      :class:`SafeData`, so you can test for them using code like::
    178179
    179180          if isinstance(value, SafeData):
    180181              # Do something with the "safe" string.
     
    184185      These strings are only escaped once, however, even if auto-escaping
    185186      applies.
    186187
    187       Internally, these strings are of type ``EscapeString`` or
    188       ``EscapeUnicode``. Generally you don't have to worry about these; they
    189       exist for the implementation of the ``escape`` filter.
     188      Internally, these strings are of type :class:`EscapeString` or
     189      :class:`EscapeUnicode`. Generally you don't have to worry about these;
     190      they exist for the implementation of the ``escape`` filter.
    190191
    191192Template filter code falls into one of two situations:
    192193
     
    209210       introduce any possibility of unsafe HTML."
    210211
    211212       The reason ``is_safe`` is necessary is because there are plenty of
    212        normal string operations that will turn a ``SafeData`` object back into
    213        a normal ``str`` or ``unicode`` object and, rather than try to catch
    214        them all, which would be very difficult, Django repairs the damage after
    215        the filter has completed.
     213       normal string operations that will turn a :class:`SafeData` object back
     214       into a normal ``str`` or ``unicode`` object and, rather than try to
     215       catch tem all, which would be very difficult, Django repairs the damage
     216       after the filter has completed.
    216217
    217218       For example, suppose you have a filter that adds the string ``xx`` to the
    218219       end of any input. Since this introduces no dangerous HTML characters to
     
    289290       ``autoescape`` keyword argument mean that our function will know whether
    290291       automatic escaping is in effect when the filter is called. We use
    291292       ``autoescape`` to decide whether the input data needs to be passed
    292        through ``django.utils.html.conditional_escape`` or not. (In the latter
    293        case, we just use the identity function as the "escape" function.) The
    294        ``conditional_escape()`` function is like ``escape()`` except it only
    295        escapes input that is **not** a ``SafeData`` instance. If a ``SafeData``
    296        instance is passed to ``conditional_escape()``, the data is returned
    297        unchanged.
     293       through :func:`django.utils.html.conditional_escape` or not. (In the
     294       latter case, we just use the identity function as the "escape"
     295       function.) The :func:`conditional_escape` function is like
     296       :func:`escape` except it only escapes input that is **not** a
     297       :class:`SafeData` instance. If a ``SafeData`` instance is passed to
     298       ``conditional_escape()``, the data is returned unchanged.
    298299
    299300       Finally, in the above example, we remember to mark the result as safe
    300301       so that our HTML is inserted directly into the template without further
     
    318319how the compilation works and how the rendering works.
    319320
    320321When Django compiles a template, it splits the raw template text into
    321 ''nodes''. Each node is an instance of ``django.template.Node`` and has
    322 a ``render()`` method. A compiled template is, simply, a list of ``Node``
     322''nodes''. Each node is an instance of :class:`django.template.Node` and has
     323a ``render()`` method. A compiled template is, simply, a list of :class:`Node`
    323324objects. When you call ``render()`` on a compiled template object, the template
    324325calls ``render()`` on each ``Node`` in its node list, with the given context.
    325326The results are all concatenated together to form the output of the template.
     
    346347
    347348.. _`strftime syntax`: http://docs.python.org/library/time.html#time.strftime
    348349
    349 The parser for this function should grab the parameter and create a ``Node``
    350 object::
     350The parser for this function should grab the parameter and create a
     351:class:`Node` object::
    351352
    352353    from django import template
    353354    def do_current_time(parser, token):
     
    368369    * ``token.contents`` is a string of the raw contents of the tag. In our
    369370      example, it's ``'current_time "%Y-%m-%d %I:%M %p"'``.
    370371
    371     * The ``token.split_contents()`` method separates the arguments on spaces
     372    * The :meth:`token.split_contents` method separates the arguments on spaces
    372373      while keeping quoted strings together. The more straightforward
    373       ``token.contents.split()`` wouldn't be as robust, as it would naively
     374      :func:`token.contents.split` wouldn't be as robust, as it would naively
    374375      split on *all* spaces, including those within quoted strings. It's a good
    375       idea to always use ``token.split_contents()``.
     376      idea to always use :meth:`token.split_contents`.
    376377
    377378    * This function is responsible for raising
    378       ``django.template.TemplateSyntaxError``, with helpful messages, for
     379      :exc:`django.template.TemplateSyntaxError`, with helpful messages, for
    379380      any syntax error.
    380381
    381     * The ``TemplateSyntaxError`` exceptions use the ``tag_name`` variable.
     382    * The :exc:`TemplateSyntaxError` exceptions use the ``tag_name`` variable.
    382383      Don't hard-code the tag's name in your error messages, because that
    383384      couples the tag's name to your function. ``token.contents.split()[0]``
    384385      will ''always'' be the name of your tag -- even when the tag has no
     
    397398Writing the renderer
    398399~~~~~~~~~~~~~~~~~~~~
    399400
    400 The second step in writing custom tags is to define a ``Node`` subclass that
    401 has a ``render()`` method.
     401The second step in writing custom tags is to define a :class:`Node` subclass
     402that has a :meth:`render` method.
    402403
    403404Continuing the above example, we need to define ``CurrentTimeNode``::
    404405
     
    443444
    444445Also, if your template tag creates a new context for performing some
    445446sub-rendering, set the auto-escape attribute to the current context's value.
    446 The ``__init__`` method for the ``Context`` class takes a parameter called
     447The ``__init__`` method for the :class:`Context` class takes a parameter called
    447448``autoescape`` that you can use for this purpose. For example::
    448449
    449450    def render(self, context):
     
    466467Registering the tag
    467468~~~~~~~~~~~~~~~~~~~
    468469
    469 Finally, register the tag with your module's ``Library`` instance, as explained
    470 in "Writing custom template filters" above. Example::
     470Finally, register the tag with your module's :class:`Library` instance, as
     471explained in "Writing custom template filters" above. Example::
    471472
    472473    register.tag('current_time', do_current_time)
    473474
     
    496497~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    497498
    498499Although you can pass any number of arguments to a template tag using
    499 ``token.split_contents()``, the arguments are all unpacked as
     500:meth:`token.split_contents`, the arguments are all unpacked as
    500501string literals. A little more work is required in order to pass dynamic
    501502content (a template variable) to a template tag as an argument.
    502503
    503504While the previous examples have formatted the current time into a string and
    504 returned the string, suppose you wanted to pass in a ``DateTimeField`` from an
    505 object and have the template tag format that date-time:
     505returned the string, suppose you wanted to pass in a :class:`DateTimeField`
     506from an object and have the template tag format that date-time:
    506507
    507508.. code-block:: html+django
    508509
    509510    <p>This post was last updated at {% format_time blog_entry.date_updated "%Y-%m-%d %I:%M %p" %}.</p>
    510511
    511 Initially, ``token.split_contents()`` will return three values:
     512Initially, :meth:`token.split_contents` will return three values:
    512513
    513514    1. The tag name ``format_time``.
    514515    2. The string "blog_entry.date_updated" (without the surrounding quotes).
     
    531532
    532533.. versionchanged:: 1.0
    533534    Variable resolution has changed in the 1.0 release of Django. ``template.resolve_variable()``
    534     has been deprecated in favor of a new ``template.Variable`` class.
     535    has been deprecated in favor of a new :class:`template.Variable` class.
    535536
    536537You also have to change the renderer to retrieve the actual contents of the
    537538``date_updated`` property of the ``blog_entry`` object.  This can be
    538 accomplished by using the ``Variable()`` class in ``django.template``.
     539accomplished by using the :class:`Variable` class in :mod:`django.template`.
    539540
    540 To use the ``Variable`` class, simply instantiate it with the name of the
     541To use the :class:`Variable` class, simply instantiate it with the name of the
    541542variable to be resolved, and then call ``variable.resolve(context)``. So,
    542543for example::
    543544
     
    553554            except template.VariableDoesNotExist:
    554555                return ''
    555556
    556 Variable resolution will throw a ``VariableDoesNotExist`` exception if it cannot
    557 resolve the string passed to it in the current context of the page.
     557Variable resolution will throw a :exc:`VariableDoesNotExist` exception if it
     558cannot resolve the string passed to it in the current context of the page.
    558559
    559560Shortcut for simple tags
    560561~~~~~~~~~~~~~~~~~~~~~~~~
    561562
    562 Many template tags take a number of arguments -- strings or a template variables
    563 -- and return a string after doing some processing based solely on
     563Many template tags take a number of arguments -- strings or a template
     564variables -- and return a string after doing some processing based solely on
    564565the input argument and some external information. For example, the
    565566``current_time`` tag we wrote above is of this variety: we give it a format
    566567string, it returns the time as a string.
    567568
    568569To ease the creation of the types of tags, Django provides a helper function,
    569570``simple_tag``. This function, which is a method of
    570 ``django.template.Library``, takes a function that accepts any number of
     571:class:`django.template.Library`, takes a function that accepts any number of
    571572arguments, wraps it in a ``render`` function and the other necessary bits
    572573mentioned above and registers it with the template system.
    573574
     
    605606Another common type of template tag is the type that displays some data by
    606607rendering *another* template. For example, Django's admin interface uses custom
    607608template tags to display the buttons along the bottom of the "add/change" form
    608 pages. Those buttons always look the same, but the link targets change depending
    609 on the object being edited -- so they're a perfect case for using a small
    610 template that is filled with details from the current object. (In the admin's
    611 case, this is the ``submit_row`` tag.)
     609pages. Those buttons always look the same, but the link targets change
     610depending on the object being edited -- so they're a perfect case for using a
     611small template that is filled with details from the current object. (In the
     612admin's case, this is the ``submit_row`` tag.)
    612613
    613614These sorts of tags are called "inclusion tags".
    614615
     
    652653    </ul>
    653654
    654655Now, create and register the inclusion tag by calling the ``inclusion_tag()``
    655 method on a ``Library`` object. Following our example, if the above template is
    656 in a file called ``results.html`` in a directory that's searched by the template
    657 loader, we'd register the tag like this::
     656method on a :class:`Library` object. Following our example, if the above
     657template is in a file called ``results.html`` in a directory that's searched by
     658the template loader, we'd register the tag like this::
    658659
    659660    # Here, register is a django.template.Library instance, as before
    660661    register.inclusion_tag('results.html')(show_results)
     
    690691
    691692(Note that the first parameter to the function *must* be called ``context``.)
    692693
    693 In that ``register.inclusion_tag()`` line, we specified ``takes_context=True``
    694 and the name of the template. Here's what the template ``link.html`` might look
    695 like:
     694In that :func:`register.inclusion_tag` line, we specified
     695``takes_context=True`` and the name of the template. Here's what the template
     696``link.html`` might look like:
    696697
    697698.. code-block:: html+django
    698699
     
    802803            return ''
    803804
    804805``parser.parse()`` takes a tuple of names of block tags ''to parse until''. It
    805 returns an instance of ``django.template.NodeList``, which is a list of
    806 all ``Node`` objects that the parser encountered ''before'' it encountered
     806returns an instance of :class:`django.template.NodeList`, which is a list of
     807all :class:`Node` objects that the parser encountered ''before'' it encountered
    807808any of the tags named in the tuple.
    808809
    809810In ``"nodelist = parser.parse(('endcomment',))"`` in the above example,
     
    813814
    814815After ``parser.parse()`` is called, the parser hasn't yet "consumed" the
    815816``{% endcomment %}`` tag, so the code needs to explicitly call
    816 ``parser.delete_first_token()``.
     817:func:`parser.delete_first_token`.
    817818
    818819``CommentNode.render()`` simply returns an empty string. Anything between
    819820``{% 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 b  
    371371
    372372In the cases where Django cannot work out the prefix correctly and where you
    373373want the original value to be used in URLs, you can set the
    374 ``FORCE_SCRIPT_NAME`` setting in your main ``settings`` file. This sets the
     374:setting:`FORCE_SCRIPT_NAME` setting in your main ``settings`` file. This sets the
    375375script name uniformly for every URL served via that settings file. Thus you'll
    376376need to use different settings files if you want different sets of URLs to
    377377have 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 b  
    148148
    149149This code is straightforward. It imports the settings and checks the value of
    150150the :setting:`DEBUG` setting. If it evaluates to ``True``, then ``site_media``
    151 will be associated with the ``django.views.static.serve`` view. If not, then the
     151will be associated with the :func:`django.views.static.serve` view. If not, then the
    152152view won't be made available.
    153153
    154154Of 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 b  
    752752    ./runtests.py --settings=path.to.django.settings
    753753
    754754Yes, the unit tests need a settings module, but only for database connection
    755 info, with the ``DATABASE_ENGINE`` setting.
     755info, with the :setting:`DATABASE_ENGINE` setting.
    756756
    757757If you're using the ``sqlite3`` database backend, no further settings are
    758758needed. A temporary database will be created in memory when running the tests.
     
    771771
    772772You will also need to ensure that your database uses UTF-8 as the default
    773773character set. If your database server doesn't use UTF-8 as a default charset,
    774 you will need to include a value for ``TEST_DATABASE_CHARSET`` in your settings
     774you will need to include a value for :setting:`TEST_DATABASE_CHARSET` in your settings
    775775file.
    776776
    777777If 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 b  
    4242create a ``mysite`` directory in your current directory.
    4343
    4444.. admonition:: Mac OS X permissions
    45    
     45
    4646   If you're using Mac OS X, you may see the message "permission denied" when
    4747   you try to run ``django-admin.py startproject``. This is because, on
    4848   Unix-based systems like OS X, a file must be marked as "executable" before it
    4949   can be run as a program. To do this, open Terminal.app and navigate (using
    5050   the ``cd`` command) to the directory where :ref:`django-admin.py
    51    <ref-django-admin>` is installed, then run the command 
     51   <ref-django-admin>` is installed, then run the command
    5252   ``chmod +x django-admin.py``.
    5353
    5454.. note::
     
    9090    * :file:`__init__.py`: An empty file that tells Python that this directory
    9191      should be considered a Python package. (Read `more about packages`_ in the
    9292      official Python docs if you're a Python beginner.)
    93      
     93
    9494    * :file:`manage.py`: A command-line utility that lets you interact with this
    9595      Django project in various ways. You can read all the details about
    9696      :file:`manage.py` in :ref:`ref-django-admin`.
    97      
     97
    9898    * :file:`settings.py`: Settings/configuration for this Django project.
    9999      :ref:`topics-settings` will tell you all about how settings work.
    100    
     100
    101101    * :file:`urls.py`: The URL declarations for this Django project; a "table of
    102102      contents" of your Django-powered site. You can read more about URLs in
    103103      :ref:`topics-http-urls`.
     
    137137    on port 8000. If you want to change the server's port, pass it as a
    138138    command-line argument. For instance, this command starts the server on port
    139139    8080:
    140    
     140
    141141    .. code-block:: bash
    142142
    143143        python manage.py runserver 8080
     
    155155
    156156    * :setting:`DATABASE_ENGINE` -- Either 'postgresql_psycopg2', 'mysql' or
    157157      'sqlite3'. Other backends are :setting:`also available <DATABASE_ENGINE>`.
    158      
     158
    159159    * :setting:`DATABASE_NAME` -- The name of your database. If you're using
    160160      SQLite, the database will be a file on your computer; in that case,
    161       ``DATABASE_NAME`` should be the full absolute path, including filename, of
    162       that file. If the file doesn't exist, it will automatically be created
    163       when you synchronize the database for the first time (see below).
    164      
    165       When specifying the path, always use forward slashes, even on Windows
     161      :setting:`DATABASE_NAME` should be the full absolute path, including
     162      filename, of that file. If the file doesn't exist, it will automatically
     163      be created when you synchronize the database for the first time (see
     164      below).
     165
     166      When specifying the path, always use forward slashes, even on Windows
    166167      (e.g. ``C:/homes/user/mysite/sqlite3.db``).
    167      
     168
    168169    * :setting:`DATABASE_USER` -- Your database username (not used for SQLite).
    169    
     170
    170171    * :setting:`DATABASE_PASSWORD` -- Your database password (not used for
    171172      SQLite).
    172    
     173
    173174    * :setting:`DATABASE_HOST` -- The host your database is on. Leave this as an
    174175      empty string if your database server is on the same physical machine (not
    175176      used for SQLite).
     
    585586prompt, but also because objects' representations are used throughout Django's
    586587automatically-generated admin.
    587588
    588 .. admonition:: Why :meth:`~django.db.models.Model.__unicode__` and not 
     589.. admonition:: Why :meth:`~django.db.models.Model.__unicode__` and not
    589590                :meth:`django.db.models.Model.__str__`?
    590591
    591592    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 b  
    1717   - All the public APIs -- everything documented in the linked documents below,
    1818     and all methods that don't begin with an underscore -- will not be moved or
    1919     renamed without providing backwards-compatible aliases.
    20      
     20
    2121   - If new features are added to these APIs -- which is quite possible --
    2222     they will not break or change the meaning of existing methods. In other
    2323     words, "stable" does not (necessarily) mean "complete."
    24          
     24
    2525   - If, for some reason, an API declared stable must be removed or replaced, it
    2626     will be declared deprecated but will remain in the API for at least two
    2727     minor version releases. Warnings will be issued when the deprecated method
    2828     is called.
    29      
     29
    3030     See :ref:`official-releases` for more details on how Django's version
    3131     numbering scheme works, and how features will be deprecated.
    32      
     32
    3333   - We'll only break backwards compatibility of these APIs if a bug or
    3434     security hole makes it completely unavoidable.
    3535
     
    4343    - :ref:`Authorization <topics-auth>`
    4444
    4545    - :ref:`Caching <topics-cache>`.
    46    
     46
    4747    - :ref:`Model definition, managers, querying and transactions
    4848      <topics-db-index>`
    49    
     49
    5050    - :ref:`Sending e-mail <topics-email>`.
    51    
     51
    5252    - :ref:`File handling and storage <topics-files>`
    53    
     53
    5454    - :ref:`Forms <topics-forms-index>`
    55    
     55
    5656    - :ref:`HTTP request/response handling <topics-http-index>`, including file
    5757      uploads, middleware, sessions, URL resolution, view, and shortcut APIs.
    58    
     58
    5959    - :ref:`Generic views <topics-http-generic-views>`.
    6060
    6161    - :ref:`Internationalization <topics-i18n>`.
    62    
     62
    6363    - :ref:`Pagination <topics-pagination>`
    64    
     64
    6565    - :ref:`Serialization <topics-serialization>`
    66    
     66
    6767    - :ref:`Signals <topics-signals>`
    68    
     68
    6969    - :ref:`Templates <topics-templates>`, including the language, Python-level
    7070      :ref:`template APIs <ref-templates-index>`, and :ref:`custom template tags
    7171      and libraries <howto-custom-template-tags>`. We may add new template
    7272      tags in the future and the names may inadvertently clash with
    7373      external template tags. Before adding any such tags, we'll ensure that
    7474      Django raises an error if it tries to load tags with duplicate names.
    75      
     75
    7676    - :ref:`Testing <topics-testing>`
    7777
    7878    - :ref:`django-admin utility <ref-django-admin>`.
    79    
     79
    8080    - :ref:`Built-in middleware <ref-middleware>`
    81    
     81
    8282    - :ref:`Request/response objects <ref-request-response>`.
    83    
     83
    8484    - :ref:`Settings <ref-settings>`. Note, though that while the :ref:`list of
    8585      built-in settings <ref-settings>` can be considered complete we may -- and
    8686      probably will -- add new settings in future versions. This is one of those
    8787      places where "'stable' does not mean 'complete.'"
    88      
     88
    8989    - :ref:`Built-in signals <ref-signals>`. Like settings, we'll probably add
    9090      new signals in the future, but the existing ones won't break.
    91      
     91
    9292    - :ref:`Unicode handling <ref-unicode>`.
    93        
     93
    9494    - Everything covered by the :ref:`HOWTO guides <howto-index>`.
    95    
     95
    9696``django.utils``
    9797----------------
    9898
    99 Most of the modules in ``django.utils`` are designed for internal use. Only the following parts of ``django.utils`` can be considered stable:
     99Most of the modules in :mod:`django.utils` are designed for internal use. Only
     100the following parts of :mod:`django.utils` can be considered stable:
    100101
    101     - ``django.utils.cache``
    102     - ``django.utils.datastructures.SortedDict`` -- only this single class; the
    103       rest of the module is for internal use.
    104     - ``django.utils.encoding``
    105     - ``django.utils.feedgenerator``
    106     - ``django.utils.http``
    107     - ``django.utils.safestring``
    108     - ``django.utils.translation``
    109     - ``django.utils.tzinfo``
    110    
     102    - :mod:`django.utils.cache`
     103    - :class:`django.utils.datastructures.SortedDict` -- only this single
     104      class; the rest of the module is for internal use.
     105    - :mod:`django.utils.encoding`
     106    - :mod:`django.utils.feedgenerator`
     107    - :mod:`django.utils.http`
     108    - :mod:`django.utils.safestring`
     109    - :mod:`django.utils.translation`
     110    - :mod:`django.utils.tzinfo`
     111
    111112Exceptions
    112113==========
    113114
     
    119120
    120121If we become aware of a security problem -- hopefully by someone following our
    121122:ref:`security reporting policy <reporting-security-issues>` -- we'll do
    122 everything necessary to fix it. This might mean breaking backwards compatibility; security trumps the compatibility guarantee.
     123everything necessary to fix it. This might mean breaking backwards
     124compatibility; security trumps the compatibility guarantee.
    123125
    124126Contributed applications (``django.contrib``)
    125127---------------------------------------------
     
    129131releases. As the web evolves, Django must evolve with it.
    130132
    131133However, any changes to contrib apps will come with an important guarantee:
    132 we'll make sure it's always possible to use an older version of a contrib app if
    133 we need to make changes. Thus, if Django 1.5 ships with a backwards-incompatible
    134 ``django.contrib.flatpages``, we'll make sure you can still use the Django 1.4
    135 version alongside Django 1.5. This will continue to allow for easy upgrades.
     134we'll make sure it's always possible to use an older version of a contrib app
     135if we need to make changes. Thus, if Django 1.5 ships with a
     136backwards-incompatible ``django.contrib.flatpages``, we'll make sure you can
     137still use the Django 1.4 version alongside Django 1.5. This will continue to
     138allow for easy upgrades.
    136139
    137 Historically, apps in ``django.contrib`` have been more stable than the core, so
    138 in practice we probably won't have to ever make this exception. However, it's
    139 worth noting if you're building apps that depend on ``django.contrib``.
     140Historically, apps in :mod:`django.contrib` have been more stable than the
     141core, so in practice we probably won't have to ever make this exception.
     142However, it's worth noting if you're building apps that depend on
     143:mod:`django.contrib`.
    140144
    141145APIs marked as internal
    142146-----------------------
     
    146150    - Some documentation refers to internals and mentions them as such. If the
    147151      documentation says that something is internal, we reserve the right to
    148152      change it.
    149      
     153
    150154    - Functions, methods, and other objects prefixed by a leading underscore
    151155      (``_``). This is the standard Python way of indicating that something is
    152156      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 b  
    6969    The `discussion of DRY on the Portland Pattern Repository`__
    7070
    7171    __ http://c2.com/cgi/wiki?DontRepeatYourself
    72    
     72
    7373.. _explicit-is-better-than-implicit:
    7474
    7575Explicit is better than implicit
     
    130130This is why developers need to call ``save()`` explicitly, rather than the
    131131framework saving things behind the scenes silently.
    132132
    133 This is also why the ``select_related()`` ``QuerySet`` method exists. It's an
    134 optional performance booster for the common case of selecting "every related
     133This is also why the ``select_related()`` :class:`QuerySet` method exists. It's
     134an optional performance booster for the common case of selecting "every related
    135135object."
    136136
    137137Terse, powerful syntax
  • docs/ref/contrib/admin.txt

    diff --git a/docs/ref/contrib/admin.txt b/docs/ref/contrib/admin.txt
    a b  
    2525
    2626There are five steps in activating the Django admin site:
    2727
    28     1. Add ``django.contrib.admin`` to your ``INSTALLED_APPS`` setting.
     28    1. Add ``django.contrib.admin`` to your :setting:`INSTALLED_APPS` setting.
    2929
    3030    2. Determine which of your application's models should be editable in the
    3131       admin interface.
     
    112112dictionary of information about the fieldset, including a list of fields to be
    113113displayed in it.
    114114
    115 A full example, taken from the ``django.contrib.flatpages.FlatPage`` model::
     115A full example, taken from the :class:`django.contrib.flatpages.FlatPage`
     116model::
    116117
    117118    class FlatPageAdmin(admin.ModelAdmin):
    118119        fieldsets = (
     
    184185Use this option as an alternative to ``fieldsets`` if the layout does not
    185186matter and if you want to only show a subset of the available fields in the
    186187form. For example, you could define a simpler version of the admin form for
    187 the ``django.contrib.flatpages.FlatPage`` model as follows::
     188the :class:`django.contrib.flatpages.FlatPage` model as follows::
    188189
    189190    class FlatPageAdmin(admin.ModelAdmin):
    190191        fields = ('url', 'title', 'content')
     
    411412field should be either a ``BooleanField``, ``CharField``, ``DateField``,
    412413``DateTimeField``, ``IntegerField`` or ``ForeignKey``.
    413414
    414 This example, taken from the ``django.contrib.auth.models.User`` model, shows
    415 how both ``list_display`` and ``list_filter`` work::
     415This example, taken from the :class:`django.contrib.auth.models.User` model,
     416shows how both ``list_display`` and ``list_filter`` work::
    416417
    417418    class UserAdmin(admin.ModelAdmin):
    418419        list_display = ('username', 'email', 'first_name', 'last_name', 'is_staff')
     
    495496        radio_fields = {"group": admin.VERTICAL}
    496497
    497498You have the choice of using ``HORIZONTAL`` or ``VERTICAL`` from the
    498 ``django.contrib.admin`` module.
     499:mod:`django.contrib.admin` module.
    499500
    500501Don't include a field in ``radio_fields`` unless it's a ``ForeignKey`` or has
    501502``choices`` set.
     
    747748            }
    748749            js = ("my_code.js",)
    749750
    750 Keep in mind that this will be prepended with ``MEDIA_URL``. The same rules
    751 apply as :ref:`regular media definitions on forms <topics-forms-media>`.
     751Keep in mind that this will be prepended with :setting:`MEDIA_URL`. The same
     752rules apply as :ref:`regular media definitions on forms <topics-forms-media>`.
    752753
    753754Adding custom validation to the admin
    754755-------------------------------------
     
    972973
    973974If you want to allow editing and creating ``Image`` instance on the ``Product``
    974975add/change views you can simply use ``GenericInlineModelAdmin`` provided by
    975 ``django.contrib.contenttypes.generic``. In your ``admin.py`` for this
     976:mod:`django.contrib.contenttypes.generic`. In your ``admin.py`` for this
    976977example app::
    977978
    978979    from django.contrib import admin
     
    990991
    991992    admin.site.register(Product, ProductAdmin)
    992993
    993 ``django.contrib.contenttypes.generic`` provides both a ``GenericTabularInline``
    994 and ``GenericStackedInline`` and behave just like any other inline. See the
     994:mod:`django.contrib.contenttypes.generic` provides both a
     995``GenericTabularInline`` and ``GenericStackedInline`` and behave just like any
     996other inline. See the
    995997:ref:`contenttypes documentation <ref-contrib-contenttypes>` for more specific
    996998information.
    997999
     
    9991001==========================
    10001002
    10011003It is relatively easy to override many of the templates which the admin module
    1002 uses to generate the various pages of an admin site. You can even override a few
    1003 of these templates for a specific app, or a specific model.
     1004uses to generate the various pages of an admin site. You can even override a
     1005few of these templates for a specific app, or a specific model.
    10041006
    10051007Set up your projects admin template directories
    10061008-----------------------------------------------
     
    10081010The admin template files are located in the ``contrib/admin/templates/admin``
    10091011directory.
    10101012
    1011 In order to override one or more of them, first create an ``admin`` directory in
    1012 your project's ``templates`` directory. This can be any of the directories you
    1013 specified in ``TEMPLATE_DIRS``.
     1013In order to override one or more of them, first create an ``admin`` directory
     1014in your project's ``templates`` directory. This can be any of the directories
     1015you specified in :setting:`TEMPLATE_DIRS`.
    10141016
    10151017Within this ``admin`` directory, create sub-directories named after your app.
    10161018Within these app subdirectories create sub-directories named after your models.
    10171019Note, that the admin app will lowercase the model name when looking for the
    1018 directory, so make sure you name the directory in all lowercase if you are going
    1019 to run your app on a case-sensitive filesystem.
     1020directory, so make sure you name the directory in all lowercase if you are
     1021going to run your app on a case-sensitive filesystem.
    10201022
    10211023To override an admin template for a specific app, copy and edit the template
    10221024from the ``django/contrib/admin/templates/admin`` directory, and save it to one
     
    10391041necessary nor advisable to replace an entire template. It is almost always
    10401042better to override only the section of the template which you need to change.
    10411043
    1042 To continue the example above, we want to add a new link next to the ``History``
    1043 tool for the ``Page`` model. After looking at ``change_form.html`` we determine
    1044 that we only need to override the ``object-tools`` block. Therefore here is our
    1045 new ``change_form.html`` :
     1044To continue the example above, we want to add a new link next to the
     1045``History`` tool for the ``Page`` model. After looking at ``change_form.html``
     1046we determine that we only need to override the ``object-tools`` block.
     1047Therefore here is our new ``change_form.html``:
    10461048
    10471049.. code-block:: html+django
    10481050
     
    10851087
    10861088    Some of the admin templates, such as ``change_list_request.html`` are used
    10871089    to render custom inclusion tags. These may be overridden, but in such cases
    1088     you are probably better off creating your own version of the tag in question
    1089     and giving it a different name. That way you can use it selectively.
     1090    you are probably better off creating your own version of the tag in
     1091    question and giving it a different name. That way you can use it
     1092    selectively.
    10901093
    10911094Root and login templates
    10921095------------------------
    10931096
    10941097If you wish to change the index or login templates, you are better off creating
    1095 your own ``AdminSite`` instance (see below), and changing the ``index_template``
    1096 or ``login_template`` properties.
     1098your own ``AdminSite`` instance (see below), and changing the
     1099``index_template`` or ``login_template`` properties.
    10971100
    10981101``AdminSite`` objects
    10991102=====================
    11001103
    11011104A Django administrative site is represented by an instance of
    1102 ``django.contrib.admin.sites.AdminSite``; by default, an instance of
     1105:class:`django.contrib.admin.sites.AdminSite`; by default, an instance of
    11031106this class is created as ``django.contrib.admin.site`` and you can
    11041107register your models and ``ModelAdmin`` instances with it.
    11051108
     
    11321135    )
    11331136
    11341137Above we used ``admin.autodiscover()`` to automatically load the
    1135 ``INSTALLED_APPS`` admin.py modules.
     1138:setting:`INSTALLED_APPS` admin.py modules.
    11361139
    11371140In this example, we register the ``AdminSite`` instance
    11381141``myproject.admin.admin_site`` at the URL ``/myadmin/`` ::
  • docs/ref/contrib/comments/settings.txt

    diff --git a/docs/ref/contrib/comments/settings.txt b/docs/ref/contrib/comments/settings.txt
    a b  
    2929COMMENTS_APP
    3030------------
    3131
    32 The app (i.e. entry in ``INSTALLED_APPS``) responsible for all "business logic."
    33 You can change this to provide custom comment models and forms, though this is
    34 currently undocumented.
     32The app (i.e. entry in :setting:`INSTALLED_APPS`) responsible for all "business
     33logic." You can change this to provide custom comment models and forms, though
     34this is currently undocumented.
  • docs/ref/contrib/index.txt

    diff --git a/docs/ref/contrib/index.txt b/docs/ref/contrib/index.txt
    a b  
    1616
    1717    For most of these add-ons -- specifically, the add-ons that include either
    1818    models or template tags -- you'll need to add the package name (e.g.,
    19     ``'django.contrib.admin'``) to your ``INSTALLED_APPS`` setting and re-run
    20     ``manage.py syncdb``.
     19    ``'django.contrib.admin'``) to your :setting:`INSTALLED_APPS` setting and
     20    re-run ``manage.py syncdb``.
    2121
    2222.. _"batteries included" philosophy: http://docs.python.org/tut/node12.html#batteries-included
    2323
     
    121121===========
    122122
    123123A collection of various Django snippets that are useful only for a particular
    124 country or culture. For example, ``django.contrib.localflavor.us.forms``
     124country or culture. For example, :mod:`django.contrib.localflavor.us.forms`
    125125contains a ``USZipCodeField`` that you can use to validate U.S. zip codes.
    126126
    127127See 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 b  
    6565    * `United Kingdom`_
    6666    * `United States of America`_
    6767
    68 The ``django.contrib.localflavor`` package also includes a ``generic`` subpackage,
    69 containing useful code that is not specific to one particular country or
    70 culture. Currently, it defines date and datetime input fields based on those
    71 from :ref:`forms <topics-forms-index>`, but with non-US default formats.
    72 Here's an example of how to use them::
     68The :mod:`django.contrib.localflavor` package also includes a ``generic``
     69subpackage, containing useful code that is not specific to one particular
     70country or culture. Currently, it defines date and datetime input fields based
     71on those from :ref:`forms <topics-forms-index>`, but with non-US default
     72formats. Here's an example of how to use them::
    7373
    7474    from django import forms
    7575    from django.contrib.localflavor import generic
     
    120120
    121121.. class:: ar.forms.ARPostalCodeField
    122122
    123     A form field that validates input as either a classic four-digit Argentinian
    124     postal code or a CPA_.
     123    A form field that validates input as either a classic four-digit
     124    Argentinian postal code or a CPA_.
    125125
    126126.. _CPA: http://www.correoargentino.com.ar/consulta_cpa/home.php
    127127
    128128.. class:: ar.forms.ARDNIField
    129129
    130     A form field that validates input as a Documento Nacional de Identidad (DNI)
    131     number.
     130    A form field that validates input as a Documento Nacional de Identidad
     131    (DNI) number.
    132132
    133133.. class:: ar.forms.ARCUITField
    134134
     
    149149
    150150.. class:: au.forms.AUPhoneNumberField
    151151
    152     A form field that validates input as an Australian phone number. Valid numbers
    153     have ten digits.
     152    A form field that validates input as an Australian phone number. Valid
     153    numbers have ten digits.
    154154
    155155.. class:: au.forms.AUStateSelect
    156156
    157     A ``Select`` widget that uses a list of Australian states/territories as its
    158     choices.
     157    A ``Select`` widget that uses a list of Australian states/territories as
     158    its choices.
    159159
    160160Austria (``at``)
    161161================
     
    166166
    167167.. class:: at.forms.ATStateSelect
    168168
    169     A ``Select`` widget that uses a list of Austrian states as its choices. 
     169    A ``Select`` widget that uses a list of Austrian states as its choices.
    170170
    171171.. class:: at.forms.ATSocialSecurityNumberField
    172172
    173     A form field that validates its input as an Austrian social security number.
     173    A form field that validates its input as an Austrian social security
     174    number.
    174175
    175176Brazil (``br``)
    176177===============
    177178
    178179.. class:: br.forms.BRPhoneNumberField
    179180
    180     A form field that validates input as a Brazilian phone number, with the format
    181     XX-XXXX-XXXX.
     181    A form field that validates input as a Brazilian phone number, with the
     182    format XX-XXXX-XXXX.
    182183
    183184.. class:: br.forms.BRZipCodeField
    184185
     
    195196
    196197.. class:: ca.forms.CAPhoneNumberField
    197198
    198     A form field that validates input as a Canadian phone number, with the format
    199     XXX-XXX-XXXX.
     199    A form field that validates input as a Canadian phone number, with the
     200    format XXX-XXX-XXXX.
    200201
    201202.. class:: ca.forms.CAPostalCodeField
    202203
    203     A form field that validates input as a Canadian postal code, with the format
    204     XXX XXX.
     204    A form field that validates input as a Canadian postal code, with the
     205    format XXX XXX.
    205206
    206207.. class:: ca.forms.CAProvinceField
    207208
    208     A form field that validates input as a Canadian province name or abbreviation.
     209    A form field that validates input as a Canadian province name or
     210    abbreviation.
    209211
    210212.. class:: ca.forms.CASocialInsuranceNumberField
    211213
    212     A form field that validates input as a Canadian Social Insurance Number (SIN).
    213     A valid number must have the format XXX-XXX-XXX and pass a `Luhn mod-10
    214     checksum`_.
     214    A form field that validates input as a Canadian Social Insurance Number
     215    (SIN). A valid number must have the format XXX-XXX-XXX and pass a
     216    `Luhn mod-10 checksum`_.
    215217
    216218.. _Luhn mod-10 checksum: http://en.wikipedia.org/wiki/Luhn_algorithm
    217219
    218220.. class:: ca.forms.CAProvinceSelect
    219221
    220     A ``Select`` widget that uses a list of Canadian provinces and territories as
    221     its choices.
     222    A ``Select`` widget that uses a list of Canadian provinces and territories
     223    as its choices.
    222224
    223225Chile (``cl``)
    224226==============
    225227
    226228.. class:: cl.forms.CLRutField
    227229
    228     A form field that validates input as a Chilean national identification number
    229     ('Rol Unico Tributario' or RUT). The valid format is XX.XXX.XXX-X.
     230    A form field that validates input as a Chilean national identification
     231    number ('Rol Unico Tributario' or RUT). The valid format is XX.XXX.XXX-X.
    230232
    231233.. class:: cl.forms.CLRegionSelect
    232234
     
    404406
    405407.. class:: jp.forms.JPPrefectureSelect
    406408
    407     A ``Select`` widget that uses a list of Japanese prefectures as its choices.
     409    A ``Select`` widget that uses a list of Japanese prefectures as its
     410    choices.
    408411
    409412Mexico (``mx``)
    410413===============
     
    430433
    431434.. class:: no.forms.NOMunicipalitySelect
    432435
    433     A ``Select`` widget that uses a list of Norwegian municipalities (fylker) as
    434     its choices.
     436    A ``Select`` widget that uses a list of Norwegian municipalities (fylker)
     437    as its choices.
    435438
    436439Peru (``pe``)
    437440=============
     
    448451
    449452.. class:: pt.forms.PEDepartmentSelect
    450453
    451     A ``Select`` widget that uses a list of Peruvian Departments as its choices.
     454    A ``Select`` widget that uses a list of Peruvian Departments as its
     455    choices.
    452456
    453457Poland (``pl``)
    454458===============
    455459
    456460.. class:: pl.forms.PLNationalIdentificationNumberField
    457461
    458     A form field that validates input as a Polish national identification number
    459     (PESEL_).
     462    A form field that validates input as a Polish national identification
     463    number (PESEL_).
    460464
    461465.. _PESEL: http://en.wikipedia.org/wiki/PESEL
    462466
     
    506510
    507511    A form field that validates its input as a Romanian county (judet) name or
    508512    abbreviation. It normalizes the input to the standard vehicle registration
    509     abbreviation for the given county. This field will only accept names written
    510     with diacritics; consider using ROCountySelect as an alternative.
     513    abbreviation for the given county. This field will only accept names
     514    written with diacritics; consider using ROCountySelect as an alternative.
    511515
    512516.. class:: ro.forms.ROCountySelect
    513517
     
    516520
    517521.. class:: ro.forms.ROIBANField
    518522
    519     A form field that validates its input as a Romanian International Bank 
     523    A form field that validates its input as a Romanian International Bank
    520524    Account Number (IBAN). The valid format is ROXX-XXXX-XXXX-XXXX-XXXX-XXXX,
    521525    with or without hyphens.
    522526
     
    675679
    676680.. class:: us.models.PhoneNumberField
    677681
    678     A :class:`CharField` that checks that the value is a valid U.S.A.-style phone
    679     number (in the format ``XXX-XXX-XXXX``).
     682    A :class:`CharField` that checks that the value is a valid U.S.A.-style
     683    phone number (in the format ``XXX-XXX-XXXX``).
    680684
    681685.. class:: us.models.USStateField
    682686
  • docs/ref/contrib/webdesign.txt

    diff --git a/docs/ref/contrib/webdesign.txt b/docs/ref/contrib/webdesign.txt
    a b  
    88   :synopsis: Helpers and utilities targeted primarily at Web *designers*
    99              rather than Web *developers*.
    1010
    11 The ``django.contrib.webdesign`` package, part of the
     11The :mod:`django.contrib.webdesign` package, part of the
    1212:ref:`"django.contrib" add-ons <ref-contrib-index>`, provides various Django
    1313helpers that are particularly useful to Web *designers* (as opposed to
    1414developers).
  • docs/ref/databases.txt

    diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt
    a b  
    140140non-unique) with the default collation.
    141141
    142142In many cases, this default will not be a problem. However, if you really want
    143 case-sensitive comparisons on a particular column or table, you would change
    144 the column or table to use the ``utf8_bin`` collation. The main thing to be
    145 aware of in this case is that if you are using MySQLdb 1.2.2, the database backend in Django will then return
    146 bytestrings (instead of unicode strings) for any character fields it returns
    147 receive from the database. This is a strong variation from Django's normal
    148 practice of *always* returning unicode strings. It is up to you, the
    149 developer, to handle the fact that you will receive bytestrings if you
    150 configure your table(s) to use ``utf8_bin`` collation. Django itself should work
    151 smoothly with such columns, but if your code must be prepared to call
    152 ``django.utils.encoding.smart_unicode()`` at times if it really wants to work
    153 with consistent data -- Django will not do this for you (the database backend
    154 layer and the model population layer are separated internally so the database
    155 layer doesn't know it needs to make this conversion in this one particular
    156 case).
     143case-sensitive comparisons on a particular column or table, you would change the
     144column or table to use the ``utf8_bin`` collation. The main thing to be aware of
     145in this case is that if you are using MySQLdb 1.2.2, the database backend in
     146Django will then return bytestrings (instead of unicode strings) for any
     147character fields it returns receive from the database. This is a strong
     148variation from Django's normal practice of *always* returning unicode strings.
     149It is up to you, the developer, to handle the fact that you will receive
     150bytestrings if you configure your table(s) to use ``utf8_bin`` collation. Django
     151itself should work smoothly with such columns, but if your code must be prepared
     152to call ``django.utils.encoding.smart_unicode()`` at times if it really wants to
     153work with consistent data -- Django will not do this for you (the database
     154backend layer and the model population layer are separated internally so the
     155database layer doesn't know it needs to make this conversion in this one
     156particular case).
    157157
    158158If you're using MySQLdb 1.2.1p2, Django's standard
    159159:class:`~django.db.models.CharField` class will return unicode strings even
     
    189189       :setting:`DATABASE_PORT`
    190190    3. MySQL option files.
    191191
    192 In other words, if you set the name of the database in ``DATABASE_OPTIONS``,
    193 this will take precedence over ``DATABASE_NAME``, which would override
    194 anything in a `MySQL option file`_.
     192In other words, if you set the name of the database in
     193:setting:`DATABASE_OPTIONS`, this will take precedence over
     194:setting:`DATABASE_NAME`, which would override anything in a `MySQL option
     195file`_.
    195196
    196197Here's a sample configuration which uses a MySQL option file::
    197198
     
    319320modules.
    320321
    321322However, in the case of Windows, the official binary distribution of the stable
    322 release of Python 2.5 (2.5.2, as of this writing) includes SQLite 3.3.4, so the bug can
    323 make itself evident in that platform. There are (as of Django 1.0) even three
    324 tests in the Django test suite that will fail when run under this setup.  As
    325 described above, this can be solved by downloading and installing a newer
     323release of Python 2.5 (2.5.2, as of this writing) includes SQLite 3.3.4, so the
     324bug can make itself evident in that platform. There are (as of Django 1.0) even
     325three tests in the Django test suite that will fail when run under this setup.
     326As described above, this can be solved by downloading and installing a newer
    326327version of ``pysqlite2`` (``pysqlite-2.x.x.win32-py2.5.exe``) that includes and
    327 uses a newer version of SQLite. Python 2.6 ships with a newer version of
    328 SQLite and is not affected by this issue.
     328uses a newer version of SQLite. Python 2.6 ships with a newer version of SQLite
     329and is not affected by this issue.
    329330
    330331If you are in such platform and find yourself in the need to update
    331332``pysqlite``/SQLite, you will also need to manually modify the
     
    412413    DATABASE_HOST = 'dbprod01ned.mycompany.com'
    413414    DATABASE_PORT = '1540'
    414415
    415 You should supply both :setting:`DATABASE_HOST` and :setting:`DATABASE_PORT`, or leave both
    416 as empty strings.
     416You should supply both :setting:`DATABASE_HOST` and :setting:`DATABASE_PORT`, or
     417leave both as empty strings.
    417418
    418419Tablespace options
    419420------------------
  • docs/ref/django-admin.txt

    diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
    a b  
    5959---------
    6060
    6161Many subcommands take a list of "app names." An "app name" is the basename of
    62 the package containing your models. For example, if your ``INSTALLED_APPS``
    63 contains the string ``'mysite.blog'``, the app name is ``blog``.
     62the package containing your models. For example, if your
     63:setting:`INSTALLED_APPS` contains the string ``'mysite.blog'``, the app name is
     64``blog``.
    6465
    6566Determining the version
    6667-----------------------
     
    148149it when running interactively.
    149150
    150151This command is only available if Django's :ref:`authentication system
    151 <topics-auth>` (``django.contrib.auth``) is installed.
     152<topics-auth>` (:mod:`django.contrib.auth`) is installed.
    152153
    153154dbshell
    154155-------
     
    156157.. django-admin:: dbshell
    157158
    158159Runs the command-line client for the database engine specified in your
    159 ``DATABASE_ENGINE`` setting, with the connection parameters specified in your
    160 ``DATABASE_USER``, ``DATABASE_PASSWORD``, etc., settings.
     160:setting:`DATABASE_ENGINE` setting, with the connection parameters specified in
     161your :setting:`DATABASE_USER`, :setting:`DATABASE_PASSWORD`, etc., settings.
    161162
    162163    * For PostgreSQL, this runs the ``psql`` command-line client.
    163164    * For MySQL, this runs the ``mysql`` command-line client.
     
    177178settings.
    178179
    179180Settings that don't appear in the defaults are followed by ``"###"``. For
    180 example, the default settings don't define ``ROOT_URLCONF``, so
     181example, the default settings don't define :setting:`ROOT_URLCONF`, so
    181182``ROOT_URLCONF`` is followed by ``"###"`` in the output of ``diffsettings``.
    182183
    183184Note that Django's default settings live in ``django/conf/global_settings.py``,
     
    248249---------
    249250
    250251Introspects the database tables in the database pointed-to by the
    251 ``DATABASE_NAME`` setting and outputs a Django model module (a ``models.py``
    252 file) to standard output.
     252:setting:`DATABASE_NAME` setting and outputs a Django model module (a
     253``models.py`` file) to standard output.
    253254
    254255Use this if you have a legacy database with which you'd like to use Django.
    255256The script will inspect the database and create a model for each table within
     
    300301Django will search in three locations for fixtures:
    301302
    302303   1. In the ``fixtures`` directory of every installed application
    303    2. In any directory named in the ``FIXTURE_DIRS`` setting
     304   2. In any directory named in the :setting:`FIXTURE_DIRS` setting
    304305   3. In the literal path named by the fixture
    305306
    306307Django will load any and all fixtures it finds in these locations that match
     
    331332
    332333would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed
    333334application,  ``<dirname>/foo/bar/mydata.json`` for each directory in
    334 ``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``.
     335:setting:`FIXTURE_DIRS`, and the literal path ``foo/bar/mydata.json``.
    335336
    336337Note that the order in which fixture files are processed is undefined. However,
    337338all fixture data is installed as a single transaction, so data in
     
    525526~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    526527
    527528By default, the development server doesn't serve any static files for your site
    528 (such as CSS files, images, things under ``MEDIA_URL`` and so forth). If
     529(such as CSS files, images, things under :setting:`MEDIA_URL` and so forth). If
    529530you want to configure Django to serve static media, read :ref:`howto-static-files`.
    530531
    531532Turning off auto-reload
     
    629630syncdb
    630631------
    631632
    632 Creates the database tables for all apps in ``INSTALLED_APPS`` whose tables
    633 have not already been created.
     633Creates the database tables for all apps in :setting:`INSTALLED_APPS` whose
     634tables have not already been created.
    634635
    635636Use this command when you've added new applications to your project and want to
    636637install them in the database. This includes any apps shipped with Django that
    637 might be in ``INSTALLED_APPS`` by default. When you start a new project, run
    638 this command to install the default apps.
     638might be in :setting:`INSTALLED_APPS` by default. When you start a new project,
     639run this command to install the default apps.
    639640
    640641.. admonition:: Syncdb will not alter existing tables
    641642
     
    650651   to match, use the ``sql`` command to display the new SQL structure and
    651652   compare that to your existing table schema to work out the changes.
    652653
    653 If you're installing the ``django.contrib.auth`` application, ``syncdb`` will
     654If you're installing the :mod:`django.contrib.auth` application, ``syncdb`` will
    654655give you the option of creating a superuser immediately.
    655656
    656657``syncdb`` will also search for and install any fixture named ``initial_data``
     
    719720--addrport [port number or ipaddr:port]
    720721~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    721722
    722 Use ``--addrport`` to specify a different port, or IP address and port, from
    723 the default of 127.0.0.1:8000. This value follows exactly the same format and
    724 serves exactly the same function as the argument to the ``runserver`` subcommand.
     723Use ``--addrport`` to specify a different port, or IP address and port, from the
     724default of 127.0.0.1:8000. This value follows exactly the same format and serves
     725exactly the same function as the argument to the ``runserver`` subcommand.
    725726
    726727Examples:
    727728
     
    741742validate
    742743--------
    743744
    744 Validates all installed models (according to the ``INSTALLED_APPS`` setting)
    745 and prints validation errors to standard output.
     745Validates all installed models (according to the :setting:`INSTALLED_APPS`
     746setting) and prints validation errors to standard output.
    746747
    747748Default options
    748749===============
  • docs/ref/forms/api.txt

    diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt
    a b  
    132132Accessing "clean" data
    133133----------------------
    134134
    135 Each ``Field`` in a ``Form`` class is responsible not only for validating data,
    136 but also for "cleaning" it -- normalizing it to a consistent format. This is a
    137 nice feature, because it allows data for a particular field to be input in
    138 a variety of ways, always resulting in consistent output.
     135Each :class:`Field` in a :class:`Form` class is responsible not only for
     136validating data, but also for "cleaning" it -- normalizing it to a consistent
     137format. This is a nice feature, because it allows data for a particular field to
     138be input in a variety of ways, always resulting in consistent output.
    139139
    140 For example, ``DateField`` normalizes input into a Python ``datetime.date``
     140For example, :class:`DateField` normalizes input into a Python ``datetime.date``
    141141object. Regardless of whether you pass it a string in the format
    142142``'1994-07-15'``, a ``datetime.date`` object or a number of other formats,
    143143``DateField`` will always normalize it to a ``datetime.date`` object as long as
    144144it's valid.
    145145
    146 Once you've created a ``Form`` instance with a set of data and validated it,
    147 you can access the clean data via the ``cleaned_data`` attribute of the ``Form``
    148 object::
     146Once you've created a :class:`Form` instance with a set of data and validated
     147it, you can access the clean data via the :attr:`cleaned_data` attribute of the
     148``Form`` object::
    149149
    150150    >>> data = {'subject': 'hello',
    151151    ...         'message': 'Hi there',
     
    158158    {'cc_myself': True, 'message': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'}
    159159
    160160.. versionchanged:: 1.0
    161     The ``cleaned_data`` attribute was called ``clean_data`` in earlier releases.
     161    The :attr:`cleaned_data` attribute was called ``clean_data`` in earlier releases.
    162162
    163 Note that any text-based field -- such as ``CharField`` or ``EmailField`` --
    164 always cleans the input into a Unicode string. We'll cover the encoding
    165 implications later in this document.
     163Note that any text-based field -- such as :class:`CharField` or
     164:class:`EmailField` -- always cleans the input into a Unicode string. We'll
     165cover the encoding implications later in this document.
    166166
    167 If your data does *not* validate, your ``Form`` instance will not have a
    168 ``cleaned_data`` attribute::
     167If your data does *not* validate, your :class:`Form` instance will not have a
     168:attr:`cleaned_data` attribute::
    169169
    170170    >>> data = {'subject': '',
    171171    ...         'message': 'Hi there',
     
    179179    ...
    180180    AttributeError: 'ContactForm' object has no attribute 'cleaned_data'
    181181
    182 ``cleaned_data`` will always *only* contain a key for fields defined in the
    183 ``Form``, even if you pass extra data when you define the ``Form``. In this
    184 example, we pass a bunch of extra fields to the ``ContactForm`` constructor,
    185 but ``cleaned_data`` contains only the form's fields::
     182:attr:`cleaned_data` will always *only* contain a key for fields defined in the
     183:class:`Form`, even if you pass extra data when you define the :class:`Form`. In
     184this example, we pass a bunch of extra fields to the ``ContactForm``
     185constructor, but :attr:`cleaned_data` contains only the form's fields::
    186186
    187187    >>> data = {'subject': 'hello',
    188188    ...         'message': 'Hi there',
     
    197197    >>> f.cleaned_data # Doesn't contain extra_field_1, etc.
    198198    {'cc_myself': True, 'message': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'}
    199199
    200 ``cleaned_data`` will include a key and value for *all* fields defined in the
    201 ``Form``, even if the data didn't include a value for fields that are not
    202 required. In this example, the data dictionary doesn't include a value for the
    203 ``nick_name`` field, but ``cleaned_data`` includes it, with an empty value::
     200:attr:`cleaned_data` will include a key and value for *all* fields defined in
     201the :class:`Form`, even if the data didn't include a value for fields that are
     202not required. In this example, the data dictionary doesn't include a value for
     203the ``nick_name`` field, but :attr:`cleaned_data` includes it, with an empty
     204value::
    204205
    205206    >>> class OptionalPersonForm(Form):
    206207    ...     first_name = CharField()
     
    213214    >>> f.cleaned_data
    214215    {'nick_name': u'', 'first_name': u'John', 'last_name': u'Lennon'}
    215216
    216 In this above example, the ``cleaned_data`` value for ``nick_name`` is set to an
    217 empty string, because ``nick_name`` is ``CharField``, and ``CharField``\s treat
    218 empty values as an empty string. Each field type knows what its "blank" value
    219 is -- e.g., for ``DateField``, it's ``None`` instead of the empty string. For
    220 full details on each field's behavior in this case, see the "Empty value" note
    221 for each field in the "Built-in ``Field`` classes" section below.
     217In this above example, the :attr:`cleaned_data` value for ``nick_name`` is set
     218to an empty string, because ``nick_name`` is :class:`CharField`, and
     219:class:`CharField`\s treat empty values as an empty string. Each field type
     220knows what its "blank" value is -- e.g., for :class:`DateField`, it's ``None``
     221instead of the empty string. For full details on each field's behavior in this
     222case, see the "Empty value" note for each field in the "Built-in :class:`Field`
     223classes" section below.
    222224
    223225You can write code to perform validation for particular form fields (based on
    224226their name) or for the form as a whole (considering combinations of various
     
    227229Outputting forms as HTML
    228230------------------------
    229231
    230 The second task of a ``Form`` object is to render itself as HTML. To do so,
     232The second task of a :class:`Form` object is to render itself as HTML. To do so,
    231233simply ``print`` it::
    232234
    233235    >>> f = ContactForm()
     
    261263      ``</table>`` tags, nor does it include the ``<form>`` and ``</form>``
    262264      tags or an ``<input type="submit">`` tag. It's your job to do that.
    263265
    264     * Each field type has a default HTML representation. ``CharField`` and
    265       ``EmailField`` are represented by an ``<input type="text">``.
    266       ``BooleanField`` is represented by an ``<input type="checkbox">``. Note
    267       these are merely sensible defaults; you can specify which HTML to use for
    268       a given field by using widgets, which we'll explain shortly.
     266    * Each field type has a default HTML representation. :class:`CharField` and
     267      :class:`EmailField` are represented by an ``<input type="text">``.
     268      :class:`BooleanField` is represented by an ``<input type="checkbox">``.
     269      Note these are merely sensible defaults; you can specify which HTML to use
     270      for a given field by using widgets, which we'll explain shortly.
    269271
    270272    * The HTML ``name`` for each tag is taken directly from its attribute name
    271273      in the ``ContactForm`` class.
     
    288290``as_p()``
    289291~~~~~~~~~~
    290292
    291 ``Form.as_p()`` renders the form as a series of ``<p>`` tags, with each ``<p>``
     293:meth:`Form.as_p` renders the form as a series of ``<p>`` tags, with each ``<p>``
    292294containing one field::
    293295
    294296    >>> f = ContactForm()
     
    303305``as_ul()``
    304306~~~~~~~~~~~
    305307
    306 ``Form.as_ul()`` renders the form as a series of ``<li>`` tags, with each
     308:meth:`Form.as_ul` renders the form as a series of ``<li>`` tags, with each
    307309``<li>`` containing one field. It does *not* include the ``<ul>`` or ``</ul>``,
    308310so that you can specify any HTML attributes on the ``<ul>`` for flexibility::
    309311
     
    319321``as_table()``
    320322~~~~~~~~~~~~~~
    321323
    322 Finally, ``Form.as_table()`` outputs the form as an HTML ``<table>``. This is
     324Finally, :meth:`Form.as_table` outputs the form as an HTML ``<table>``. This is
    323325exactly the same as ``print``. In fact, when you ``print`` a form object, it
    324 calls its ``as_table()`` method behind the scenes::
     326calls its :meth:`as_table` method behind the scenes::
    325327
    326328    >>> f = ContactForm()
    327329    >>> f.as_table()
     
    347349This behavior is configurable, though, if you want to change the ``id``
    348350convention or remove HTML ``id`` attributes and ``<label>`` tags entirely.
    349351
    350 Use the ``auto_id`` argument to the ``Form`` constructor to control the label
    351 and ``id`` behavior. This argument must be ``True``, ``False`` or a string.
     352Use the ``auto_id`` argument to the :class:`Form` constructor to control the
     353label and ``id`` behavior. This argument must be ``True``, ``False`` or a
     354string.
    352355
    353356If ``auto_id`` is ``False``, then the form output will not include ``<label>``
    354357tags nor ``id`` attributes::
     
    442445Notes on field ordering
    443446~~~~~~~~~~~~~~~~~~~~~~~
    444447
    445 In the ``as_p()``, ``as_ul()`` and ``as_table()`` shortcuts, the fields are
    446 displayed in the order in which you define them in your form class. For
     448In the :meth:`as_p`, :meth:`as_ul` and :meth:`as_table` shortcuts, the fields
     449are displayed in the order in which you define them in your form class. For
    447450example, in the ``ContactForm`` example, the fields are defined in the order
    448 ``subject``, ``message``, ``sender``, ``cc_myself``. To reorder the HTML
    449 output, just change the order in which those fields are listed in the class.
     451``subject``, ``message``, ``sender``, ``cc_myself``. To reorder the HTML output,
     452just change the order in which those fields are listed in the class.
    450453
    451454How errors are displayed
    452455~~~~~~~~~~~~~~~~~~~~~~~~
    453456
    454 If you render a bound ``Form`` object, the act of rendering will automatically
    455 run the form's validation if it hasn't already happened, and the HTML output
    456 will include the validation errors as a ``<ul class="errorlist">`` near the
    457 field. The particular positioning of the error messages depends on the output
    458 method you're using::
     457If you render a bound :class:`Form` object, the act of rendering will
     458automatically run the form's validation if it hasn't already happened, and the
     459HTML output will include the validation errors as a ``<ul class="errorlist">``
     460near the field. The particular positioning of the error messages depends on the
     461output method you're using::
    459462
    460463    >>> data = {'subject': '',
    461464    ...         'message': 'Hi there',
     
    483486Customizing the error list format
    484487~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    485488
    486 By default, forms use ``django.forms.util.ErrorList`` to format validation
     489By default, forms use :class:`django.forms.util.ErrorList` to format validation
    487490errors. If you'd like to use an alternate class for displaying errors, you can
    488491pass that in at construction time::
    489492
     
    506509More granular output
    507510~~~~~~~~~~~~~~~~~~~~
    508511
    509 The ``as_p()``, ``as_ul()`` and ``as_table()`` methods are simply shortcuts for
    510 lazy developers -- they're not the only way a form object can be displayed.
     512The :meth:`as_p`, :meth:`as_ul` and :meth:`as_table` methods are simply
     513shortcuts for lazy developers -- they're not the only way a form object can be
     514displayed.
    511515
    512516To display the HTML for a single field in your form, use dictionary lookup
    513517syntax using the field's name as the key, and print the resulting object::
     
    549553    >>> print f['message']
    550554    <input type="text" name="message" id="id_message" />
    551555
    552 For a field's list of errors, access the field's ``errors`` attribute. This
     556For a field's list of errors, access the field's :attr:`errors` attribute. This
    553557is a list-like object that is displayed as an HTML ``<ul class="errorlist">``
    554558when printed::
    555559
     
    575579
    576580.. versionadded:: 1.0
    577581
    578 Dealing with forms that have ``FileField`` and ``ImageField`` fields
     582Dealing with forms that have :class:`FileField` and :class:`ImageField` fields
    579583is a little more complicated than a normal form.
    580584
    581585Firstly, in order to upload files, you'll need to make sure that your
     
    586590
    587591Secondly, when you use the form, you need to bind the file data. File
    588592data is handled separately to normal form data, so when your form
    589 contains a ``FileField`` and ``ImageField``, you will need to specify
     593contains a :class:`FileField` and :class:`ImageField`, you will need to specify
    590594a second argument when you bind your form. So if we extend our
    591 ContactForm to include an ``ImageField`` called ``mugshot``, we
     595ContactForm to include an :class:`ImageField` called ``mugshot``, we
    592596need to bind the file data containing the mugshot image::
    593597
    594598    # Bound form with an image field
     
    600604    >>> file_data = {'mugshot': SimpleUploadedFile('face.jpg', <file data>)}
    601605    >>> f = ContactFormWithMugshot(data, file_data)
    602606
    603 In practice, you will usually specify ``request.FILES`` as the source
    604 of file data (just like you use ``request.POST`` as the source of
     607In practice, you will usually specify :attr:`request.FILES` as the source
     608of file data (just like you use :attr:`request.POST` as the source of
    605609form data)::
    606610
    607611    # Bound form with an image field, data from the request
     
    617621~~~~~~~~~~~~~~~~~~~~~~~~~~~
    618622
    619623If you're writing reusable views or templates, you may not know ahead of time
    620 whether your form is a multipart form or not. The ``is_multipart()`` method
     624whether your form is a multipart form or not. The :meth:`is_multipart` method
    621625tells you whether the form requires multipart encoding for submission::
    622626
    623627    >>> f = ContactFormWithMugshot()
     
    637641Subclassing forms
    638642-----------------
    639643
    640 If you have multiple ``Form`` classes that share fields, you can use
     644If you have multiple :class:`Form` classes that share fields, you can use
    641645subclassing to remove redundancy.
    642646
    643 When you subclass a custom ``Form`` class, the resulting subclass will
     647When you subclass a custom :class:`Form` class, the resulting subclass will
    644648include all fields of the parent class(es), followed by the fields you define
    645649in the subclass.
    646650
     
    685689.. attribute:: Form.prefix
    686690
    687691You can put several Django forms inside one ``<form>`` tag. To give each
    688 ``Form`` its own namespace, use the ``prefix`` keyword argument::
     692:class:`Form` its own namespace, use the ``prefix`` keyword argument::
    689693
    690694    >>> mother = PersonForm(prefix="mother")
    691695    >>> father = PersonForm(prefix="father")
  • docs/ref/forms/fields.txt

    diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
    a b  
    726726.. attribute:: URLField.validator_user_agent
    727727
    728728    String used as the user-agent used when checking for a URL's existence.
    729     Defaults to the value of the ``URL_VALIDATOR_USER_AGENT`` setting.
     729    Defaults to the value of the :setting:`URL_VALIDATOR_USER_AGENT` setting.
    730730
    731731Slightly complex built-in ``Field`` classes
    732732-------------------------------------------
  • docs/ref/generic-views.txt

    diff --git a/docs/ref/generic-views.txt b/docs/ref/generic-views.txt
    a b  
    7373"Simple" generic views
    7474======================
    7575
    76 The ``django.views.generic.simple`` module contains simple views to handle a
     76The :mod:`django.views.generic.simple` module contains simple views to handle a
    7777couple of common cases: rendering a template when no view logic is needed,
    7878and issuing a redirect.
    7979
     
    9797      just before rendering the template.
    9898
    9999    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    100       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     100      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    101101
    102102**Example:**
    103103
     
    204204      page. This lets you override the default template name (see below).
    205205
    206206    * ``template_loader``: The template loader to use when loading the
    207       template. By default, it's ``django.template.loader``.
     207      template. By default, it's :mod:`django.template.loader`.
    208208
    209209    * ``extra_context``: A dictionary of values to add to the template
    210210      context. By default, this is an empty dictionary. If a value in the
     
    220220      the view's template.
    221221
    222222    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    223       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     223      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    224224
    225225    * ``allow_future``: A boolean specifying whether to include "future"
    226226      objects on this page, where "future" means objects in which the field
     
    289289      page. This lets you override the default template name (see below).
    290290
    291291    * ``template_loader``: The template loader to use when loading the
    292       template. By default, it's ``django.template.loader``.
     292      template. By default, it's :mod:`django.template.loader`.
    293293
    294294    * ``extra_context``: A dictionary of values to add to the template
    295295      context. By default, this is an empty dictionary. If a value in the
     
    317317      this is ``False``.
    318318
    319319    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    320       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     320      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    321321
    322322    * ``allow_future``: A boolean specifying whether to include "future"
    323323      objects on this page, where "future" means objects in which the field
     
    383383      page. This lets you override the default template name (see below).
    384384
    385385    * ``template_loader``: The template loader to use when loading the
    386       template. By default, it's ``django.template.loader``.
     386      template. By default, it's :mod:`django.template.loader`.
    387387
    388388    * ``extra_context``: A dictionary of values to add to the template
    389389      context. By default, this is an empty dictionary. If a value in the
     
    404404      determining the variable's name.
    405405
    406406    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    407       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     407      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    408408
    409409    * ``allow_future``: A boolean specifying whether to include "future"
    410410      objects on this page, where "future" means objects in which the field
     
    464464      page. This lets you override the default template name (see below).
    465465
    466466    * ``template_loader``: The template loader to use when loading the
    467       template. By default, it's ``django.template.loader``.
     467      template. By default, it's :mod:`django.template.loader`.
    468468
    469469    * ``extra_context``: A dictionary of values to add to the template
    470470      context. By default, this is an empty dictionary. If a value in the
     
    485485      determining the variable's name.
    486486
    487487    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    488       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     488      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    489489
    490490    * ``allow_future``: A boolean specifying whether to include "future"
    491491      objects on this page, where "future" means objects in which the field
     
    549549      page. This lets you override the default template name (see below).
    550550
    551551    * ``template_loader``: The template loader to use when loading the
    552       template. By default, it's ``django.template.loader``.
     552      template. By default, it's :mod:`django.template.loader`.
    553553
    554554    * ``extra_context``: A dictionary of values to add to the template
    555555      context. By default, this is an empty dictionary. If a value in the
     
    570570      determining the variable's name.
    571571
    572572    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    573       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     573      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    574574
    575575    * ``allow_future``: A boolean specifying whether to include "future"
    576576      objects on this page, where "future" means objects in which the field
     
    666666      It's a bit of a brain-bender, but it's useful in some cases.
    667667
    668668    * ``template_loader``: The template loader to use when loading the
    669       template. By default, it's ``django.template.loader``.
     669      template. By default, it's :mod:`django.template.loader`.
    670670
    671671    * ``extra_context``: A dictionary of values to add to the template
    672672      context. By default, this is an empty dictionary. If a value in the
     
    680680      to use in the template context. By default, this is ``'object'``.
    681681
    682682    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    683       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     683      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    684684
    685685    * ``allow_future``: A boolean specifying whether to include "future"
    686686      objects on this page, where "future" means objects in which the field
     
    735735      page. This lets you override the default template name (see below).
    736736
    737737    * ``template_loader``: The template loader to use when loading the
    738       template. By default, it's ``django.template.loader``.
     738      template. By default, it's :mod:`django.template.loader`.
    739739
    740740    * ``extra_context``: A dictionary of values to add to the template
    741741      context. By default, this is an empty dictionary. If a value in the
     
    756756      determining the variable's name.
    757757
    758758    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    759       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     759      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    760760
    761761**Template name:**
    762762
     
    861861      It's a bit of a brain-bender, but it's useful in some cases.
    862862
    863863    * ``template_loader``: The template loader to use when loading the
    864       template. By default, it's ``django.template.loader``.
     864      template. By default, it's :mod:`django.template.loader`.
    865865
    866866    * ``extra_context``: A dictionary of values to add to the template
    867867      context. By default, this is an empty dictionary. If a value in the
     
    875875      to use in the template context. By default, this is ``'object'``.
    876876
    877877    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    878       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     878      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    879879
    880880**Template name:**
    881881
     
    944944      page. This lets you override the default template name (see below).
    945945
    946946    * ``template_loader``: The template loader to use when loading the
    947       template. By default, it's ``django.template.loader``.
     947      template. By default, it's :mod:`django.template.loader`.
    948948
    949949    * ``extra_context``: A dictionary of values to add to the template
    950950      context. By default, this is an empty dictionary. If a value in the
     
    10291029      page. This lets you override the default template name (see below).
    10301030
    10311031    * ``template_loader``: The template loader to use when loading the
    1032       template. By default, it's ``django.template.loader``.
     1032      template. By default, it's :mod:`django.template.loader`.
    10331033
    10341034    * ``extra_context``: A dictionary of values to add to the template
    10351035      context. By default, this is an empty dictionary. If a value in the
     
    11111111      page. This lets you override the default template name (see below).
    11121112
    11131113    * ``template_loader``: The template loader to use when loading the
    1114       template. By default, it's ``django.template.loader``.
     1114      template. By default, it's :mod:`django.template.loader`.
    11151115
    11161116    * ``extra_context``: A dictionary of values to add to the template
    11171117      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 b  
    1414
    1515When a page is requested, Django creates an :class:`HttpRequest` object that
    1616contains metadata about the request. Then Django loads the appropriate view,
    17 passing the :class:`HttpRequest` as the first argument to the view function. Each
    18 view is responsible for returning an :class:`HttpResponse` object.
     17passing the :class:`HttpRequest` as the first argument to the view function.
     18Each view is responsible for returning an :class:`HttpResponse` object.
    1919
    20 This document explains the APIs for :class:`HttpRequest` and :class:`HttpResponse`
    21 objects.
     20This document explains the APIs for :class:`HttpRequest` and
     21:class:`HttpResponse` objects.
    2222
    2323HttpRequest objects
    2424===================
     
    5252    .. versionadded:: 1.0
    5353
    5454    A string representing the current encoding used to decode form submission
    55     data (or ``None``, which means the ``DEFAULT_CHARSET`` setting is used).
    56     You can write to this attribute to change the encoding used when accessing
    57     the form data. Any subsequent attribute accesses (such as reading from
    58     ``GET`` or ``POST``) will use the new ``encoding`` value.  Useful if you
    59     know the form data is not in the ``DEFAULT_CHARSET`` encoding.
     55    data (or ``None``, which means the :setting:`DEFAULT_CHARSET` setting is
     56    used).  You can write to this attribute to change the encoding used when
     57    accessing the form data. Any subsequent attribute accesses (such as reading
     58    from ``GET`` or ``POST``) will use the new ``encoding`` value.  Useful if
     59    you know the form data is not in the ``DEFAULT_CHARSET`` encoding.
    6060
    6161.. attribute:: HttpRequest.GET
    6262
    6363    A dictionary-like object containing all given HTTP GET parameters. See the
    64     ``QueryDict`` documentation below.
     64    :class:`QueryDict` documentation below.
    6565
    6666.. attribute:: HttpRequest.POST
    6767
    6868    A dictionary-like object containing all given HTTP POST parameters. See the
    69     ``QueryDict`` documentation below.
     69    :class:`QueryDict` documentation below.
    7070
    7171    It's possible that a request can come in via POST with an empty ``POST``
    7272    dictionary -- if, say, a form is requested via the POST HTTP method but
     
    9797
    9898    A dictionary-like object containing all uploaded files. Each key in
    9999    ``FILES`` is the ``name`` from the ``<input type="file" name="" />``. Each
    100     value in ``FILES`` is an ``UploadedFile`` object containing the following
    101     attributes:
     100    value in ``FILES`` is an :class:`UploadedFile` object containing the
     101    following attributes:
    102102
    103103        * ``read(num_bytes=None)`` -- Read a number of bytes from the file.
    104104        * ``name`` -- The name of the uploaded file.
    105105        * ``size`` -- The size, in bytes, of the uploaded file.
    106         * ``chunks(chunk_size=None)`` -- A generator that yields sequential chunks of data.
     106        * ``chunks(chunk_size=None)`` -- A generator that yields sequential
     107          chunks of data.
    107108
    108109    See :ref:`topics-files` for more information.
    109110
     
    151152
    152153.. attribute:: HttpRequest.user
    153154
    154     A ``django.contrib.auth.models.User`` object representing the currently
     155    A :class:`django.contrib.auth.models.User` object representing the currently
    155156    logged-in user. If the user isn't currently logged in, ``user`` will be set
    156     to an instance of ``django.contrib.auth.models.AnonymousUser``. You
    157     can tell them apart with ``is_authenticated()``, like so::
     157    to an instance of :class:`django.contrib.auth.models.AnonymousUser`. You
     158    can tell them apart with :meth:`is_authenticated`, like so::
    158159
    159160        if request.user.is_authenticated():
    160161            # Do something for logged-in users.
     
    181182
    182183    Not defined by Django itself, but will be read if other code (e.g., a custom
    183184    middleware class) sets it. When present, this will be used as the root
    184     URLconf for the current request, overriding the ``ROOT_URLCONF`` setting.
    185     See :ref:`how-django-processes-a-request` for details.
     185    URLconf for the current request, overriding the :setting:`ROOT_URLCONF`
     186    setting.  See :ref:`how-django-processes-a-request` for details.
    186187
    187188Methods
    188189-------
     
    228229
    229230   .. versionadded:: 1.0
    230231
    231    Returns ``True`` if the request was made via an ``XMLHttpRequest``, by checking
    232    the ``HTTP_X_REQUESTED_WITH`` header for the string ``'XMLHttpRequest'``. The
    233    following major JavaScript libraries all send this header:
     232   Returns ``True`` if the request was made via an ``XMLHttpRequest``, by
     233   checking the ``HTTP_X_REQUESTED_WITH`` header for the string
     234   ``'XMLHttpRequest'``. The following major JavaScript libraries all send this
     235   header:
    234236
    235237       * jQuery
    236238       * Dojo
     
    248250
    249251.. class:: QueryDict
    250252
    251 In an :class:`HttpRequest` object, the ``GET`` and ``POST`` attributes are instances
    252 of ``django.http.QueryDict``. :class:`QueryDict` is a dictionary-like
    253 class customized to deal with multiple values for the same key. This is
    254 necessary because some HTML form elements, notably
    255 ``<select multiple="multiple">``, pass multiple values for the same key.
     253In an :class:`HttpRequest` object, the ``GET`` and ``POST`` attributes are
     254instances of ``django.http.QueryDict``. ``QueryDict`` is a dictionary-like class
     255customized to deal with multiple values for the same key. This is necessary
     256because some HTML form elements, notably ``<select multiple="multiple">``, pass
     257multiple values for the same key.
    256258
    257259``QueryDict`` instances are immutable, unless you create a ``copy()`` of them.
    258260That means you can't change attributes of ``request.POST`` and ``request.GET``
     
    261263Methods
    262264-------
    263265
    264 :class:`QueryDict` implements all the standard dictionary methods, because it's
     266``QueryDict`` implements all the standard dictionary methods, because it's
    265267a subclass of dictionary. Exceptions are outlined here:
    266268
    267269.. method:: QueryDict.__getitem__(key)
     
    294296    Just like the standard dictionary ``setdefault()`` method, except it uses
    295297    ``__setitem__`` internally.
    296298
    297 .. method:: QueryDict.update(other_dict) 
     299.. method:: QueryDict.update(other_dict)
    298300
    299301    Takes either a ``QueryDict`` or standard dictionary. Just like the standard
    300302    dictionary ``update()`` method, except it *appends* to the current
     
    357359
    358360    Like :meth:`items()`, except it includes all values, as a list, for each
    359361    member of the dictionary. For example::
    360    
     362
    361363         >>> q = QueryDict('a=1&a=2&a=3')
    362364         >>> q.lists()
    363365         [('a', ['1', '2', '3'])]
    364    
     366
    365367.. method:: QueryDict.urlencode()
    366368
    367369    Returns a string of the data in query-string format.
     
    373375.. class:: HttpResponse
    374376
    375377In contrast to :class:`HttpRequest` objects, which are created automatically by
    376 Django, :class:`HttpResponse` objects are your responsibility. Each view you
     378Django, ``HttpResponse`` objects are your responsibility. Each view you
    377379write is responsible for instantiating, populating and returning an
    378 :class:`HttpResponse`.
     380``HttpResponse``.
    379381
    380 The :class:`HttpResponse` class lives in the ``django.http`` module.
     382The ``HttpResponse`` class lives in the :mod:`django.http` module.
    381383
    382384Usage
    383385-----
     
    386388~~~~~~~~~~~~~~~
    387389
    388390Typical usage is to pass the contents of the page, as a string, to the
    389 :class:`HttpResponse` constructor::
     391``HttpResponse`` constructor::
    390392
    391393    >>> response = HttpResponse("Here's the text of the Web page.")
    392394    >>> response = HttpResponse("Text only, please.", mimetype="text/plain")
     
    415417hard-coded strings. If you use this technique, follow these guidelines:
    416418
    417419    * The iterator should return strings.
    418     * If an :class:`HttpResponse` has been initialized with an iterator as its
    419       content, you can't use the class:`HttpResponse` instance as a file-like
     420    * If an ``HttpResponse`` has been initialized with an iterator as its
     421      content, you can't use the ``HttpResponse`` instance as a file-like
    420422      object. Doing so will raise ``Exception``.
    421423
    422424Setting headers
     
    452454-------
    453455
    454456.. method:: HttpResponse.__init__(content='', mimetype=None, status=200, content_type=DEFAULT_CONTENT_TYPE)
    455    
     457
    456458    Instantiates an ``HttpResponse`` object with the given page content (a
    457     string) and MIME type. The ``DEFAULT_CONTENT_TYPE`` is ``'text/html'``.
     459    string) and MIME type. The :setting:`DEFAULT_CONTENT_TYPE` is ``'text/html'``.
    458460
    459461    ``content`` can be an iterator or a string. If it's an iterator, it should
    460462    return strings, and those strings will be joined together to form the
     
    470472    encoding, which makes it more than just a MIME type specification.
    471473    If ``mimetype`` is specified (not ``None``), that value is used.
    472474    Otherwise, ``content_type`` is used. If neither is given, the
    473     ``DEFAULT_CONTENT_TYPE`` setting is used.
     475    :setting:`DEFAULT_CONTENT_TYPE` setting is used.
    474476
    475477.. method:: HttpResponse.__setitem__(header, value)
    476478
     
    519521
    520522.. method:: HttpResponse.write(content)
    521523
    522     This method makes an :class:`HttpResponse` instance a file-like object.
     524    This method makes an ``HttpResponse`` instance a file-like object.
    523525
    524526.. method:: HttpResponse.flush()
    525527
    526     This method makes an :class:`HttpResponse` instance a file-like object.
     528    This method makes an ``HttpResponse`` instance a file-like object.
    527529
    528530.. method:: HttpResponse.tell()
    529531
    530     This method makes an :class:`HttpResponse` instance a file-like object.
     532    This method makes an ``HttpResponse`` instance a file-like object.
    531533
    532534.. _HTTP Status code: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10
    533535
     
    537539HttpResponse subclasses
    538540-----------------------
    539541
    540 Django includes a number of ``HttpResponse`` subclasses that handle different
    541 types of HTTP responses. Like ``HttpResponse``, these subclasses live in
    542 :mod:`django.http`.
     542Django includes a number of :class:`HttpResponse` subclasses that handle
     543different types of HTTP responses. Like ``HttpResponse``, these subclasses live
     544in :mod:`django.http`.
    543545
    544546.. class:: HttpResponseRedirect
    545547
    546     The constructor takes a single argument -- the path to redirect to. This
    547     can be a fully qualified URL (e.g. ``'http://www.yahoo.com/search/'``) or an
    548     absolute URL with no domain (e.g. ``'/search/'``). Note that this returns
    549     an HTTP status code 302.
     548    The constructor takes a single argument -- the path to redirect to. This can
     549    be a fully qualified URL (e.g. ``'http://www.yahoo.com/search/'``) or an
     550    absolute URL with no domain (e.g. ``'/search/'``). Note that this returns an
     551    HTTP status code 302.
    550552
    551553.. class:: HttpResponsePermanentRedirect
    552554
  • docs/ref/settings.txt

    diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
    a b  
    4747
    4848The URL prefix for admin media -- CSS, JavaScript and images used by
    4949the Django administrative interface. Make sure to use a trailing
    50 slash, and to have this be different from the ``MEDIA_URL`` setting
     50slash, and to have this be different from the :setting:`MEDIA_URL` setting
    5151(since the same URL cannot be mapped onto two different sets of
    5252files).
    5353
     
    9292
    9393Whether to append trailing slashes to URLs. This is only used if
    9494``CommonMiddleware`` is installed (see :ref:`topics-http-middleware`). See also
    95 ``PREPEND_WWW``.
     95:setting:`PREPEND_WWW`.
    9696
    9797.. setting:: AUTHENTICATION_BACKENDS
    9898
     
    195195Default: ``''`` (Empty string)
    196196
    197197The name of the database to use. For SQLite, it's the full path to the database
    198 file. When specifying the path, always use forward slashes, even on Windows 
     198file. When specifying the path, always use forward slashes, even on Windows
    199199(e.g. ``C:/homes/user/mysite/sqlite3.db``).
    200200
    201201.. setting:: DATABASE_OPTIONS
     
    228228default port. Not used with SQLite.
    229229
    230230.. setting:: DATABASE_USER
    231    
     231
    232232DATABASE_USER
    233233-------------
    234234
     
    251251and ``MONTH_DAY_FORMAT``.
    252252
    253253.. setting:: DATETIME_FORMAT
    254    
     254
    255255DATETIME_FORMAT
    256256---------------
    257257
     
    519519.. warning::
    520520
    521521    **Always prefix the mode with a 0.**
    522    
     522
    523523    If you're not familiar with file modes, please note that the leading
    524524    ``0`` is very important: it indicates an octal number, which is the
    525525    way that modes must be specified. If you try to use ``644``, you'll
    526526    get totally incorrect behavior.
    527    
    528527
    529 .. _documentation for os.chmod: http://docs.python.org/lib/os-file-dir.html
     528
     529.. _documentation for os.chmod: http://docs.python.org/lib/os-file-dir.html
    530530
    531531.. setting:: FIXTURE_DIRS
    532532
     
    650650
    651651If you define a custom ``LANGUAGES`` setting, it's OK to mark the languages as
    652652translation strings (as in the default value displayed above) -- but use a
    653 "dummy" ``gettext()`` function, not the one in ``django.utils.translation``.
    654 You should *never* import ``django.utils.translation`` from within your
     653"dummy" ``gettext()`` function, not the one in :mod:`django.utils.translation`.
     654You should *never* import :mod:`django.utils.translation` from within your
    655655settings file, because that module in itself depends on the settings, and that
    656656would cause a circular import.
    657657
     
    875875
    876876.. versionadded:: 1.0
    877877
    878 Default: ``django.contrib.sessions.backends.db``
     878Default: :mod:`django.contrib.sessions.backends.db`
    879879
    880880Controls where Django stores session data. Valid values are:
    881881
     
    11651165    Django cannot reliably use alternate time zones in a Windows environment.
    11661166    If you're running Django on Windows, this variable must be set to match the
    11671167    system timezone.
    1168    
     1168
    11691169.. _See available choices: http://www.postgresql.org/docs/8.1/static/datetime-keywords.html#DATETIME-TIMEZONE-SET-TABLE
    11701170
    11711171.. 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 b  
    562562To cut down on the repetitive nature of loading and rendering
    563563templates, Django provides a shortcut function which largely
    564564automates the process: ``render_to_string()`` in
    565 ``django.template.loader``, which loads a template, renders it and
     565:mod:`django.template.loader`, which loads a template, renders it and
    566566returns the resulting string::
    567567
    568568    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 b  
    16161616-------------------------------
    16171617
    16181618Django comes with a couple of other template-tag libraries that you have to
    1619 enable explicitly in your ``INSTALLED_APPS`` setting and enable in your
     1619enable explicitly in your :setting:`INSTALLED_APPS` setting and enable in your
    16201620template with the ``{% load %}`` tag.
    16211621
    16221622django.contrib.humanize
  • docs/ref/unicode.txt

    diff --git a/docs/ref/unicode.txt b/docs/ref/unicode.txt
    a b  
    107107Conversion functions
    108108~~~~~~~~~~~~~~~~~~~~
    109109
    110 The ``django.utils.encoding`` module contains a few functions that are handy
     110The :mod:`django.utils.encoding` module contains a few functions that are handy
    111111for converting back and forth between Unicode and bytestrings.
    112112
    113113    * ``smart_unicode(s, encoding='utf-8', strings_only=False, errors='strict')``
     
    311311E-mail
    312312======
    313313
    314 Django's e-mail framework (in ``django.core.mail``) supports Unicode
     314Django's e-mail framework (in :mod:`django.core.mail`) supports Unicode
    315315transparently. You can use Unicode data in the message bodies and any headers.
    316316However, you're still obligated to respect the requirements of the e-mail
    317317specifications, 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 b  
    2727============
    2828
    2929Authentication support is bundled as a Django application in
    30 ``django.contrib.auth``. To install it, do the following:
     30:mod:`django.contrib.auth`. To install it, do the following:
    3131
    3232    1. Put ``'django.contrib.auth'`` in your :setting:`INSTALLED_APPS` setting.
    3333    2. Run the command ``manage.py syncdb``.
     
    693693
    694694.. function:: views.login()
    695695
    696     Here's what ``django.contrib.auth.views.login`` does:
     696    Here's what :func:`django.contrib.auth.views.login` does:
    697697
    698698        * If called via ``GET``, it displays a login form that POSTs to the
    699699          same URL. More on this in a bit.
     
    10371037Default permissions
    10381038-------------------
    10391039
    1040 When ``django.contrib.auth`` is listed in your :setting:`INSTALLED_APPS`
     1040When :mod:`django.contrib.auth` is listed in your :setting:`INSTALLED_APPS`
    10411041setting, it will ensure that three default permissions -- add, change and
    10421042delete -- are created for each Django model defined in one of your installed
    10431043applications.
    10441044
    10451045These permissions will be created when you run :djadmin:`manage.py syncdb
    10461046<syncdb>`; the first time you run ``syncdb`` after adding
    1047 ``django.contrib.auth`` to :setting:`INSTALLED_APPS`, the default permissions
     1047:mod:`django.contrib.auth` to :setting:`INSTALLED_APPS`, the default permissions
    10481048will be created for all previously-installed models, as well as for any new
    10491049models being installed at that time. Afterward, it will create default
    10501050permissions 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 b  
    4949or directly in memory. This is an important decision that affects your cache's
    5050performance; yes, some cache types are faster than others.
    5151
    52 Your cache preference goes in the ``CACHE_BACKEND`` setting in your settings
    53 file. Here's an explanation of all available values for CACHE_BACKEND.
     52Your cache preference goes in the :setting:`CACHE_BACKEND` setting in your
     53settings file. Here's an explanation of all available values for CACHE_BACKEND.
    5454
    5555Memcached
    5656---------
     
    8181      "Client APIs" section.
    8282
    8383.. versionadded:: 1.0
     84
    8485    The ``cmemcache`` option is new in 1.0. Previously, only
    8586    ``python-memcached`` was supported.
    8687
    87 To use Memcached with Django, set ``CACHE_BACKEND`` to
     88To use Memcached with Django, set :setting:`CACHE_BACKEND` to
    8889``memcached://ip:port/``, where ``ip`` is the IP address of the Memcached
    8990daemon and ``port`` is the port on which Memcached is running.
    9091
     
    9495
    9596One excellent feature of Memcached is its ability to share cache over multiple
    9697servers. To take advantage of this feature, include all server addresses in
    97 ``CACHE_BACKEND``, separated by semicolons. In this example, the cache is
     98:setting:`CACHE_BACKEND`, separated by semicolons. In this example, the cache is
    9899shared over Memcached instances running on IP address 172.19.26.240 and
    99100172.19.26.242, both on port 11211::
    100101
     
    122123in your database that is in the proper format that Django's database-cache
    123124system expects.
    124125
    125 Once you've created that database table, set your ``CACHE_BACKEND`` setting to
    126 ``"db://tablename"``, where ``tablename`` is the name of the database table.
    127 In this example, the cache table's name is ``my_cache_table``::
     126Once you've created that database table, set your :setting:`CACHE_BACKEND`
     127setting to ``"db://tablename"``, where ``tablename`` is the name of the database
     128table.  In this example, the cache table's name is ``my_cache_table``::
    128129
    129130    CACHE_BACKEND = 'db://my_cache_table'
    130131
     
    134135------------------
    135136
    136137To store cached items on a filesystem, use the ``"file://"`` cache type for
    137 ``CACHE_BACKEND``. For example, to store cached data in ``/var/tmp/django_cache``,
    138 use this setting::
     138:setting:`CACHE_BACKEND`. For example, to store cached data in
     139``/var/tmp/django_cache``, use this setting::
    139140
    140141    CACHE_BACKEND = 'file:///var/tmp/django_cache'
    141142
     
    158159
    159160If you want the speed advantages of in-memory caching but don't have the
    160161capability of running Memcached, consider the local-memory cache backend. This
    161 cache is multi-process and thread-safe. To use it, set ``CACHE_BACKEND`` to
    162 ``"locmem:///"``. For example::
     162cache is multi-process and thread-safe. To use it, set :setting:`CACHE_BACKEND`
     163to ``"locmem:///"``. For example::
    163164
    164165    CACHE_BACKEND = 'locmem:///'
    165    
     166
    166167Note that each process will have its own private cache instance, which means no
    167168cross-process caching is possible. This obviously also means the local memory
    168169cache isn't particularly memory-efficient, so it's probably not a good choice
     
    178179various places but a development/test environment on which you don't want to
    179180cache. As a result, your development environment won't use caching and your
    180181production environment still will. To activate dummy caching, set
    181 ``CACHE_BACKEND`` like so::
     182:setting:`CACHE_BACKEND` like so::
    182183
    183184    CACHE_BACKEND = 'dummy:///'
    184185
     
    190191While Django includes support for a number of cache backends out-of-the-box,
    191192sometimes you might want to use a customized cache backend. To use an external
    192193cache backend with Django, use a Python import path as the scheme portion (the
    193 part before the initial colon) of the ``CACHE_BACKEND`` URI, like so::
     194part before the initial colon) of the :setting:`CACHE_BACKEND` URI, like so::
    194195
    195196    CACHE_BACKEND = 'path.to.backend://'
    196197
     
    206207-----------------------
    207208
    208209All caches may take arguments. They're given in query-string style on the
    209 ``CACHE_BACKEND`` setting. Valid arguments are:
     210:setting:`CACHE_BACKEND` setting. Valid arguments are:
    210211
    211212    timeout
    212213        Default timeout, in seconds, to use for the cache. Defaults to 5
     
    241242==================
    242243
    243244.. versionchanged:: 1.0
    244     (previous versions of Django only provided a single ``CacheMiddleware`` instead
    245     of the two pieces described below).
     245
     246    (previous versions of Django only provided a single ``CacheMiddleware``
     247    instead of the two pieces described below).
    246248
    247249Once the cache is set up, the simplest way to use caching is to cache your
    248250entire site. You'll need to add
    249251``'django.middleware.cache.UpdateCacheMiddleware'`` and
    250252``'django.middleware.cache.FetchFromCacheMiddleware'`` to your
    251 ``MIDDLEWARE_CLASSES`` setting, as in this example::
     253:setting:`MIDDLEWARE_CLASSES` setting, as in this example::
    252254
    253255    MIDDLEWARE_CLASSES = (
    254256        'django.middleware.cache.UpdateCacheMiddleware',
     
    264266
    265267Then, add the following required settings to your Django settings file:
    266268
    267 * ``CACHE_MIDDLEWARE_SECONDS`` -- The number of seconds each page should be
    268   cached.
    269 * ``CACHE_MIDDLEWARE_KEY_PREFIX`` -- If the cache is shared across multiple
    270   sites using the same Django installation, set this to the name of the site,
    271   or some other string that is unique to this Django instance, to prevent key
    272   collisions. Use an empty string if you don't care.
     269* :setting:`CACHE_MIDDLEWARE_SECONDS` -- The number of seconds each page should
     270  be cached.
     271* :setting:`CACHE_MIDDLEWARE_KEY_PREFIX` -- If the cache is shared across
     272  multiple sites using the same Django installation, set this to the name of
     273  the site, or some other string that is unique to this Django instance, to
     274  prevent key collisions. Use an empty string if you don't care.
    273275
    274 The cache middleware caches every page that doesn't have GET or POST
    275 parameters. Optionally, if the ``CACHE_MIDDLEWARE_ANONYMOUS_ONLY`` setting is
     276The cache middleware caches every page that doesn't have GET or POST parameters.
     277Optionally, if the :setting:`CACHE_MIDDLEWARE_ANONYMOUS_ONLY` setting is
    276278``True``, only anonymous requests (i.e., not those made by a logged-in user)
    277279will be cached. This is a simple and effective way of disabling caching for any
    278280user-specific pages (include Django's admin interface). Note that if you use
    279 ``CACHE_MIDDLEWARE_ANONYMOUS_ONLY``, you should make sure you've activated
    280 ``AuthenticationMiddleware``.
     281:setting:`CACHE_MIDDLEWARE_ANONYMOUS_ONLY`, you should make sure you've
     282activated ``AuthenticationMiddleware``.
    281283
    282284Additionally, the cache middleware automatically sets a few headers in each
    283285``HttpResponse``:
     
    285287* Sets the ``Last-Modified`` header to the current date/time when a fresh
    286288  (uncached) version of the page is requested.
    287289* Sets the ``Expires`` header to the current date/time plus the defined
    288   ``CACHE_MIDDLEWARE_SECONDS``.
     290  :setting:`CACHE_MIDDLEWARE_SECONDS`.
    289291* Sets the ``Cache-Control`` header to give a max age for the page -- again,
    290   from the ``CACHE_MIDDLEWARE_SECONDS`` setting.
     292  from the :setting:`CACHE_MIDDLEWARE_SECONDS` setting.
    291293
    292294See :ref:`topics-http-middleware` for more on middleware.
    293295
     
    295297
    296298If a view sets its own cache expiry time (i.e. it has a ``max-age`` section in
    297299its ``Cache-Control`` header) then the page will be cached until the expiry
    298 time, rather than ``CACHE_MIDDLEWARE_SECONDS``. Using the decorators in
    299 ``django.views.decorators.cache`` you can easily set a view's expiry time
     300time, rather than :setting:`CACHE_MIDDLEWARE_SECONDS`. Using the decorators in
     301:mod:`django.views.decorators.cache` you can easily set a view's expiry time
    300302(using the ``cache_control`` decorator) or disable caching for a view (using
    301303the ``never_cache`` decorator). See the `using other headers`__ section for
    302304more on these decorators.
     
    307309==================
    308310
    309311A more granular way to use the caching framework is by caching the output of
    310 individual views. ``django.views.decorators.cache`` defines a ``cache_page``
     312individual views. :mod:`django.views.decorators.cache` defines a ``cache_page``
    311313decorator that will automatically cache the view's response for you. It's easy
    312314to use::
    313315
     
    347349    {% endcache %}
    348350
    349351Sometimes you might want to cache multiple copies of a fragment depending on
    350 some dynamic data that appears inside the fragment. For example, you might want a
    351 separate cached copy of the sidebar used in the previous example for every user
    352 of your site. Do this by passing additional arguments to the ``{% cache %}``
    353 template tag to uniquely identify the cache fragment::
     352some dynamic data that appears inside the fragment. For example, you might want
     353a separate cached copy of the sidebar used in the previous example for every
     354user of your site. Do this by passing additional arguments to the ``{% cache
     355%}`` template tag to uniquely identify the cache fragment::
    354356
    355357    {% load cache %}
    356358    {% cache 500 sidebar request.user.username %}
     
    379381intensive database query. In cases like this, you can use the low-level cache
    380382API to store objects in the cache with any level of granularity you like.
    381383
    382 The cache API is simple. The cache module, ``django.core.cache``, exports a
    383 ``cache`` object that's automatically created from the ``CACHE_BACKEND``
     384The cache API is simple. The cache module, :mod:`django.core.cache`, exports a
     385``cache`` object that's automatically created from the :setting:`CACHE_BACKEND`
    384386setting::
    385387
    386388    >>> from django.core.cache import cache
     
    392394    'hello, world!'
    393395
    394396The ``timeout_seconds`` argument is optional and defaults to the ``timeout``
    395 argument in the ``CACHE_BACKEND`` setting (explained above).
     397argument in the :setting:`CACHE_BACKEND` setting (explained above).
    396398
    397399If the object doesn't exist in the cache, ``cache.get()`` returns ``None``::
    398400
     
    618620For explanation of Cache-Control HTTP directives, see the `Cache-Control spec`_.
    619621
    620622(Note that the caching middleware already sets the cache header's max-age with
    621 the value of the ``CACHE_MIDDLEWARE_SETTINGS`` setting. If you use a custom
    622 ``max_age`` in a ``cache_control`` decorator, the decorator will take
     623the value of the :setting:`CACHE_MIDDLEWARE_SETTINGS` setting. If you use a
     624custom ``max_age`` in a ``cache_control`` decorator, the decorator will take
    623625precedence, and the header values will be merged correctly.)
    624626
    625627If you want to use headers to disable caching altogether,
    626628``django.views.decorators.cache.never_cache`` is a view decorator that adds
    627 headers to ensure the response won't be cached by browsers or other caches. Example::
     629headers to ensure the response won't be cached by browsers or other caches.
     630Example::
    628631
    629632    from django.views.decorators.cache import never_cache
    630633    @never_cache
     
    650653===========================
    651654
    652655If you use caching middleware, it's important to put each half in the right
    653 place within the ``MIDDLEWARE_CLASSES`` setting. That's because the cache
     656place within the :setting:`MIDDLEWARE_CLASSES` setting. That's because the cache
    654657middleware needs to know which headers by which to vary the cache storage.
    655658Middleware always adds something to the ``Vary`` response header when it can.
    656659
  • docs/topics/db/transactions.txt

    diff --git a/docs/topics/db/transactions.txt b/docs/topics/db/transactions.txt
    a b  
    3232transactions.
    3333
    3434To activate this feature, just add the ``TransactionMiddleware`` middleware to
    35 your ``MIDDLEWARE_CLASSES`` setting::
     35your :setting:`MIDDLEWARE_CLASSES` setting::
    3636
    3737    MIDDLEWARE_CLASSES = (
    3838        'django.contrib.sessions.middleware.SessionMiddleware',
     
    136136=================================================
    137137
    138138Control freaks can totally disable all transaction management by setting
    139 ``DISABLE_TRANSACTION_MANAGEMENT`` to ``True`` in the Django settings file.
     139:setting:`DISABLE_TRANSACTION_MANAGEMENT` to ``True`` in the Django settings
     140file.
    140141
    141142If you do this, Django won't provide any automatic transaction management
    142143whatsoever. 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 b  
    1111Django provides a couple of light wrappers over it, to make sending e-mail
    1212extra quick.
    1313
    14 The code lives in a single module: ``django.core.mail``.
     14The code lives in a single module: :mod:`django.core.mail`.
    1515
    1616.. _smtplib library: http://docs.python.org/library/smtplib.html
    1717
     
    3333
    3434.. note::
    3535
    36     The character set of e-mail sent with ``django.core.mail`` will be set to
     36    The character set of e-mail sent with :mod:`django.core.mail` will be set to
    3737    the value of your :setting:`DEFAULT_CHARSET` setting.
    3838
    3939send_mail()
     
    5858      possible exceptions, all of which are subclasses of ``SMTPException``.
    5959    * ``auth_user``: The optional username to use to authenticate to the SMTP
    6060      server. If this isn't provided, Django will use the value of the
    61       ``EMAIL_HOST_USER`` setting.
     61      :setting:`EMAIL_HOST_USER` setting.
    6262    * ``auth_password``: The optional password to use to authenticate to the
    6363      SMTP server. If this isn't provided, Django will use the value of the
    64       ``EMAIL_HOST_PASSWORD`` setting.
     64      :setting:`EMAIL_HOST_PASSWORD` setting.
    6565
    6666.. _smtplib docs: http://docs.python.org/library/smtplib.html
    6767
     
    185185
    186186Django's ``send_mail()`` and ``send_mass_mail()`` functions are actually thin
    187187wrappers that make use of the ``EmailMessage`` and ``SMTPConnection`` classes
    188 in ``django.core.mail``.  If you ever need to customize the way Django sends
     188in :mod:`django.core.mail`.  If you ever need to customize the way Django sends
    189189e-mail, you can subclass these two classes to suit your needs.
    190190
    191191.. note::
  • docs/topics/files.txt

    diff --git a/docs/topics/files.txt b/docs/topics/files.txt
    a b  
    117117-------------------------------------
    118118
    119119Django ships with a built-in ``FileSystemStorage`` class (defined in
    120 ``django.core.files.storage``) which implements basic local filesystem file
     120:mod:`django.core.files.storage`) which implements basic local filesystem file
    121121storage. Its initializer takes two arguments:
    122122
    123123======================  ===================================================
     
    125125======================  ===================================================
    126126``location``            Optional. Absolute path to the directory that will
    127127                        hold the files. If omitted, it will be set to the
    128                         value of your ``MEDIA_ROOT`` setting.
     128                        value of your :setting:`MEDIA_ROOT` setting.
    129129``base_url``            Optional. URL that serves the files stored at this
    130130                        location. If omitted, it will default to the value
    131                         of your ``MEDIA_URL`` setting.
     131                        of your :setting:`MEDIA_URL` setting.
    132132======================  ===================================================
    133133
    134134For example, the following code will store uploaded files under
    135 ``/media/photos`` regardless of what your ``MEDIA_ROOT`` setting is::
     135``/media/photos`` regardless of what your :setting:`MEDIA_ROOT` setting is::
    136136
    137137    from django.db import models
    138138    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 b  
    1212
    1313.. highlightlang:: html+django
    1414
    15 ``django.forms`` is Django's form-handling library.
     15:mod:`django.forms` is Django's form-handling library.
    1616
    1717While it is possible to process form submissions just using Django's
    1818:class:`~django.http.HttpRequest` class, using the form library takes care of a
     
    4848
    4949The library is decoupled from the other Django components, such as the database
    5050layer, views and templates. It relies only on Django settings, a couple of
    51 ``django.utils`` helper functions and Django's internationalization hooks (but
    52 you're not required to be using internationalization features to use this
     51:mod:`django.utils` helper functions and Django's internationalization hooks
     52(but you're not required to be using internationalization features to use this
    5353library).
    5454
    5555Form objects
  • docs/topics/forms/media.txt

    diff --git a/docs/topics/forms/media.txt b/docs/topics/forms/media.txt
    a b  
    2929
    3030    If you like the widgets that the Django Admin application uses,
    3131    feel free to use them in your own application! They're all stored
    32     in ``django.contrib.admin.widgets``.
     32    in :mod:`django.contrib.admin.widgets`.
    3333
    3434.. admonition:: Which JavaScript toolkit?
    3535
     
    198198Paths used to specify media can be either relative or absolute. If a path
    199199starts with '/', 'http://' or 'https://', it will be interpreted as an absolute
    200200path, and left as-is. All other paths will be prepended with the value of
    201 ``settings.MEDIA_URL``. For example, if the MEDIA_URL for your site was
     201:setting:`settings.MEDIA_URL<MEDIA_URL>`. For example, if the MEDIA_URL for your site was
    202202``http://media.example.com/``::
    203203
    204204    class CalendarWidget(forms.TextInput):
  • docs/topics/forms/modelforms.txt

    diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt
    a b  
    6464                                     below)
    6565    ``NullBooleanField``             ``CharField``
    6666    ``PhoneNumberField``             ``USPhoneNumberField``
    67                                      (from ``django.contrib.localflavor.us``)
     67                                     (from :mod:`django.contrib.localflavor.us`)
    6868    ``PositiveIntegerField``         ``IntegerField``
    6969    ``PositiveSmallIntegerField``    ``IntegerField``
    7070    ``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 b  
    136136
    137137        Defaults to your system's standard temporary directory (i.e. ``/tmp`` on
    138138        most Unix-like systems).
    139        
     139
    140140    :setting:`FILE_UPLOAD_PERMISSIONS`
    141141        The numeric mode (i.e. ``0644``) to set newly uploaded files to. For
    142142        more information about what these modes mean, see the `documentation for
    143143        os.chmod`_
    144        
     144
    145145        If this isn't given or is ``None``, you'll get operating-system
    146146        dependent behavior. On most platforms, temporary files will have a mode
    147147        of ``0600``, and files saved from memory will be saved using the
    148148        system's standard umask.
    149        
     149
    150150        .. warning::
    151        
     151
    152152            If you're not familiar with file modes, please note that the leading
    153153            ``0`` is very important: it indicates an octal number, which is the
    154154            way that modes must be specified. If you try to use ``644``, you'll
     
    169169        Which means "try to upload to memory first, then fall back to temporary
    170170        files."
    171171
    172 .. _documentation for os.chmod: http://docs.python.org/lib/os-file-dir.html 
     172.. _documentation for os.chmod: http://docs.python.org/lib/os-file-dir.html
    173173
    174174``UploadedFile`` objects
    175175========================
     
    193193    ``UploadedFile.temporary_file_path()``
    194194        Only files uploaded onto disk will have this method; it returns the full
    195195        path to the temporary uploaded file.
    196        
     196
    197197.. note::
    198198
    199199    Like regular Python files, you can read the file line-by-line simply by
    200200    iterating over the uploaded file:
    201    
     201
    202202    .. code-block:: python
    203        
     203
    204204        for line in uploadedfile:
    205205            do_something_with(line)
    206            
     206
    207207    However, *unlike* standard Python files, :class:`UploadedFile` only
    208208    understands ``\n`` (also known as "Unix-style") line endings. If you know
    209209    that you need to handle uploaded files with different line endings, you'll
     
    214214
    215215When a user uploads a file, Django passes off the file data to an *upload
    216216handler* -- a small class that handles file data as it gets uploaded. Upload
    217 handlers are initially defined in the ``FILE_UPLOAD_HANDLERS`` setting, which
    218 defaults to::
     217handlers are initially defined in the :setting:`FILE_UPLOAD_HANDLERS` setting,
     218which defaults to::
    219219
    220220    ("django.core.files.uploadhandler.MemoryFileUploadHandler",
    221221     "django.core.files.uploadhandler.TemporaryFileUploadHandler",)
     
    235235Sometimes particular views require different upload behavior. In these cases,
    236236you can override upload handlers on a per-request basis by modifying
    237237``request.upload_handlers``. By default, this list will contain the upload
    238 handlers given by ``FILE_UPLOAD_HANDLERS``, but you can modify the list as you
    239 would any other list.
     238handlers given by :setting:`FILE_UPLOAD_HANDLERS`, but you can modify the list
     239as you would any other list.
    240240
    241241For instance, suppose you've written a ``ProgressBarUploadHandler`` that
    242242provides 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 b  
    1616
    1717To enable session functionality, do the following:
    1818
    19     * Edit the ``MIDDLEWARE_CLASSES`` setting and make sure
    20       ``MIDDLEWARE_CLASSES`` contains ``'django.contrib.sessions.middleware.SessionMiddleware'``.
    21       The default ``settings.py`` created by ``django-admin.py startproject`` has
     19    * Edit the :setting:`MIDDLEWARE_CLASSES` setting and make sure
     20      :setting:`MIDDLEWARE_CLASSES` contains
     21      ``'django.contrib.sessions.middleware.SessionMiddleware'``.  The default
     22      ``settings.py`` created by ``django-admin.py startproject`` has
    2223      ``SessionMiddleware`` activated.
    2324
    24     * Add ``'django.contrib.sessions'`` to your ``INSTALLED_APPS`` setting,
    25       and run ``manage.py syncdb`` to install the single database table
     25    * Add ``'django.contrib.sessions'`` to your :setting:`INSTALLED_APPS`
     26      setting, and run ``manage.py syncdb`` to install the single database table
    2627      that stores session data.
    2728
    2829.. versionchanged:: 1.0
     30
    2931   This step is optional if you're not using the database session backend;
    3032   see `configuring the session engine`_.
    3133
    3234If you don't want to use sessions, you might as well remove the
    33 ``SessionMiddleware`` line from ``MIDDLEWARE_CLASSES`` and ``'django.contrib.sessions'``
    34 from your ``INSTALLED_APPS``. It'll save you a small bit of overhead.
     35``SessionMiddleware`` line from :setting:`MIDDLEWARE_CLASSES` and
     36``'django.contrib.sessions'`` from your :setting:`INSTALLED_APPS`. It'll save
     37you a small bit of overhead.
    3538
    3639Configuring the session engine
    3740==============================
     
    4952For better performance, you may want to use a cache-based session backend.
    5053
    5154.. versionchanged:: 1.1
     55
    5256   Django 1.0 did not include the ``cached_db`` session backend.
    5357
    5458To store session data using Django's cache system, you'll first need to make
     
    8690Using file-based sessions
    8791-------------------------
    8892
    89 To use file-based sessions, set the ``SESSION_ENGINE`` setting to
     93To use file-based sessions, set the :setting:`SESSION_ENGINE` setting to
    9094``"django.contrib.sessions.backends.file"``.
    9195
    92 You might also want to set the ``SESSION_FILE_PATH`` setting (which defaults
    93 to output from ``tempfile.gettempdir()``, most likely ``/tmp``) to control
    94 where Django stores session files. Be sure to check that your Web server has
    95 permissions to read and write to this location.
     96You might also want to set the :setting:`SESSION_FILE_PATH` setting (which
     97defaults to output from ``tempfile.gettempdir()``, most likely ``/tmp``) to
     98control where Django stores session files. Be sure to check that your Web server
     99has permissions to read and write to this location.
    96100
    97101Using sessions in views
    98102=======================
     
    133137    * ``clear()``
    134138
    135139.. versionadded:: 1.0
     140
    136141   ``setdefault()`` and ``clear()`` are new in this version.
    137142
    138143It also has these methods:
     
    192197
    193198      Returns the number of seconds until this session expires. For sessions
    194199      with no custom expiration (or those set to expire at browser close), this
    195       will equal ``settings.SESSION_COOKIE_AGE``.
     200      will equal :setting:`setting.SESSION_COOKIE_AGE<SESSION_COOKIE_AGE>`.
    196201
    197202    * ``get_expiry_date()``
    198203
     
    200205
    201206      Returns the date this session will expire. For sessions with no custom
    202207      expiration (or those set to expire at browser close), this will equal the
    203       date ``settings.SESSION_COOKIE_AGE`` seconds from now.
     208      date :setting:`settings.SESSION_COOKIE_AGE<SESSION_COOKIE_AGE>` seconds
     209      from now.
    204210
    205211    * ``get_expire_at_browser_close()``
    206212
     
    303309    datetime.datetime(2005, 8, 20, 13, 35, 0)
    304310    >>> s.save()
    305311
    306 If you're using the ``django.contrib.sessions.backends.db`` backend, each
     312If you're using the :mod:`django.contrib.sessions.backends.db` backend, each
    307313session is just a normal Django model. The ``Session`` model is defined in
    308314``django/contrib/sessions/models.py``. Because it's a normal model, you can
    309315access sessions using the normal Django database API::
     
    347353
    348354    request.session.modified = True
    349355
    350 To change this default behavior, set the ``SESSION_SAVE_EVERY_REQUEST`` setting
    351 to ``True``. If ``SESSION_SAVE_EVERY_REQUEST`` is ``True``, Django will save
    352 the session to the database on every single request.
     356To change this default behavior, set the :setting:`SESSION_SAVE_EVERY_REQUEST`
     357setting to ``True``. If ``SESSION_SAVE_EVERY_REQUEST`` is ``True``, Django will
     358save the session to the database on every single request.
    353359
    354360Note that the session cookie is only sent when a session has been created or
    355361modified. If ``SESSION_SAVE_EVERY_REQUEST`` is ``True``, the session cookie
     
    362368===============================================
    363369
    364370You can control whether the session framework uses browser-length sessions vs.
    365 persistent sessions with the ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` setting.
     371persistent sessions with the :setting:`SESSION_EXPIRE_AT_BROWSER_CLOSE` setting.
    366372
    367373By default, ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` is set to ``False``, which
    368374means session cookies will be stored in users' browsers for as long as
    369 ``SESSION_COOKIE_AGE``. Use this if you don't want people to have to log in
     375:setting:`SESSION_COOKIE_AGE`. Use this if you don't want people to have to log in
    370376every time they open a browser.
    371377
    372378If ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` is set to ``True``, Django will use
     
    400406Settings
    401407========
    402408
    403 A few :ref:`Django settings <ref-settings>` give you control over session behavior:
     409A few :ref:`Django settings <ref-settings>` give you control over session
     410behavior:
    404411
    405412SESSION_ENGINE
    406413--------------
    407414
    408415.. versionadded:: 1.0
    409416
    410 Default: ``django.contrib.sessions.backends.db``
     417Default: :mod:`django.contrib.sessions.backends.db`
    411418
    412419Controls where Django stores session data. Valid values are:
    413420
  • docs/topics/http/shortcuts.txt

    diff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt
    a b  
    44Django shortcut functions
    55=========================
    66
    7 The package ``django.shortcuts`` collects helper functions and classes that
     7The package :mod:`django.shortcuts` collects helper functions and classes that
    88"span" multiple levels of MVC. In other words, these functions/classes
    99introduce controlled coupling for convenience's sake.
    1010
  • docs/topics/http/urls.txt

    diff --git a/docs/topics/http/urls.txt b/docs/topics/http/urls.txt
    a b  
    3636When a user requests a page from your Django-powered site, this is the
    3737algorithm the system follows to determine which Python code to execute:
    3838
    39     1. Django determines the root URLconf module to use. Ordinarily,
    40        this is the value of the ``ROOT_URLCONF`` setting, but if the incoming
     39    1. Django determines the root URLconf module to use. Ordinarily, this is the
     40       value of the :setting:`ROOT_URLCONF` setting, but if the incoming
    4141       ``HttpRequest`` object has an attribute called ``urlconf``, its value
    4242       will be used in place of the ``ROOT_URLCONF`` setting.
    43    
     43
    4444    2. Django loads that Python module and looks for the variable
    4545       ``urlpatterns``. This should be a Python list, in the format returned by
    4646       the function ``django.conf.urls.defaults.patterns()``.
    47    
     47
    4848    3. Django runs through each URL pattern, in order, and stops at the first
    4949       one that matches the requested URL.
    50    
     50
    5151    4. Once one of the regexes matches, Django imports and calls the given
    5252       view, which is a simple Python function. The view gets passed an
    5353       :class:`~django.http.HttpRequest` as its first argument and any values
     
    595595
    596596If you need to use something similar to the :ttag:`url` template tag in
    597597your code, Django provides the following method (in the
    598 ``django.core.urlresolvers`` module):
     598:mod:`django.core.urlresolvers` module):
    599599
    600600.. currentmodule:: django.core.urlresolvers
    601601.. 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 b  
    3232Let's step through this code one line at a time:
    3333
    3434    * First, we import the class ``HttpResponse``, which lives in the
    35       ``django.http`` module, along with Python's ``datetime`` library.
     35      :mod:`django.http` module, along with Python's ``datetime`` library.
    3636
    3737    * Next, we define a function called ``current_datetime``. This is the view
    3838      function. Each view function takes an ``HttpRequest`` object as its first
     
    4949      later.)
    5050
    5151.. admonition:: Django's Time Zone
    52    
    53     Django includes a ``TIME_ZONE`` setting that defaults to
     52
     53    Django includes a :setting:`TIME_ZONE` setting that defaults to
    5454    ``America/Chicago``. This probably isn't where you live, so you might want
    5555    to change it in your settings file.
    5656
     
    165165      in the 404.
    166166
    167167    * The 404 view is passed a ``RequestContext`` and will have access to
    168       variables supplied by your ``TEMPLATE_CONTEXT_PROCESSORS`` setting (e.g.,
    169       ``MEDIA_URL``).
     168      variables supplied by your :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting
     169      (e.g., :setting:`MEDIA_URL`).
    170170
    171     * If ``DEBUG`` is set to ``True`` (in your settings module), then your 404
    172       view will never be used, and the traceback will be displayed instead.
     171    * If :setting:`DEBUG` is set to ``True`` (in your settings module), then
     172      your 404 view will never be used, and the traceback will be displayed
     173      instead.
    173174
    174175The 500 (server error) view
    175176----------------------------
     
    190191
    191192    handler500 = 'mysite.views.my_custom_error_view'
    192193
    193 Behind the scenes, Django determines the error view by looking for ``handler500``.
    194 By default, URLconfs contain the following line::
     194Behind the scenes, Django determines the error view by looking for
     195``handler500``.  By default, URLconfs contain the following line::
    195196
    196197    from django.conf.urls.defaults import *
    197198
  • docs/topics/i18n.txt

    diff --git a/docs/topics/i18n.txt b/docs/topics/i18n.txt
    a b  
    4040optimizations so as not to load the internationalization machinery.
    4141
    4242You'll probably also want to remove ``'django.core.context_processors.i18n'``
    43 from your ``TEMPLATE_CONTEXT_PROCESSORS`` setting.
     43from your :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.
    4444
    4545If you do need internationalization: three steps
    4646================================================
     
    293293
    294294Each ``RequestContext`` has access to three translation-specific variables:
    295295
    296     * ``LANGUAGES`` is a list of tuples in which the first element is the
     296    * :setting:`LANGUAGES` is a list of tuples in which the first element is the
    297297      language code and the second is the language name (translated into the
    298298      currently active locale).
    299299
     
    368368The allow_lazy() decorator
    369369~~~~~~~~~~~~~~~~~~~~~~~~~~
    370370
    371 Django offers many utility functions (particularly in ``django.utils``) that
     371Django offers many utility functions (particularly in :mod:`django.utils`) that
    372372take a string as their first argument and do something to that string. These
    373373functions are used by template filters as well as directly in other code.
    374374
     
    592592selection based on data from the request. It customizes content for each user.
    593593
    594594To use ``LocaleMiddleware``, add ``'django.middleware.locale.LocaleMiddleware'``
    595 to your ``MIDDLEWARE_CLASSES`` setting. Because middleware order matters, you
    596 should follow these guidelines:
     595to your :setting:`MIDDLEWARE_CLASSES` setting. Because middleware order matters,
     596you should follow these guidelines:
    597597
    598598    * Make sure it's one of the first middlewares installed.
    599599    * It should come after ``SessionMiddleware``, because ``LocaleMiddleware``
    600600      makes use of session data.
    601601    * If you use ``CacheMiddleware``, put ``LocaleMiddleware`` after it.
    602602
    603 For example, your ``MIDDLEWARE_CLASSES`` might look like this::
     603For example, your :setting:`MIDDLEWARE_CLASSES` might look like this::
    604604
    605605    MIDDLEWARE_CLASSES = (
    606606       'django.contrib.sessions.middleware.SessionMiddleware',
     
    623623
    624624      In Django version 0.96 and before, the cookie's name is hard-coded to
    625625      ``django_language``. In Django 1,0, The cookie name is set by the
    626       ``LANGUAGE_COOKIE_NAME`` setting. (The default name is
     626      :setting:`LANGUAGE_COOKIE_NAME` setting. (The default name is
    627627      ``django_language``.)
    628628
    629629    * Failing that, it looks at the ``Accept-Language`` HTTP header. This
     
    631631      prefer, in order by priority. Django tries each language in the header
    632632      until it finds one with available translations.
    633633
    634     * Failing that, it uses the global ``LANGUAGE_CODE`` setting.
     634    * Failing that, it uses the global :setting:`LANGUAGE_CODE` setting.
    635635
    636636.. _locale-middleware-notes:
    637637
     
    649649    * Only languages listed in the :setting:`LANGUAGES` setting can be selected.
    650650      If you want to restrict the language selection to a subset of provided
    651651      languages (because your application doesn't provide all those languages),
    652       set ``LANGUAGES`` to a list of languages. For example::
     652      set :setting:`LANGUAGES` to a list of languages. For example::
    653653
    654654          LANGUAGES = (
    655655            ('de', _('German')),
     
    662662
    663663      .. _LANGUAGES setting: ../settings/#languages
    664664
    665     * If you define a custom ``LANGUAGES`` setting, as explained in the
    666       previous bullet, it's OK to mark the languages as translation strings
    667       -- but use a "dummy" ``ugettext()`` function, not the one in
    668       ``django.utils.translation``. You should *never* import
    669       ``django.utils.translation`` from within your settings file, because that
    670       module in itself depends on the settings, and that would cause a circular
    671       import.
     665    * If you define a custom :setting:`LANGUAGES` setting, as explained in the
     666      previous bullet, it's OK to mark the languages as translation strings --
     667      but use a "dummy" ``ugettext()`` function, not the one in
     668      :mod:`django.utils.translation`. You should *never* import
     669      :mod:`django.utils.translation` from within your settings file, because
     670      that module in itself depends on the settings, and that would cause a
     671      circular import.
    672672
    673673      The solution is to use a "dummy" ``ugettext()`` function. Here's a sample
    674674      settings file::
     
    683683      With this arrangement, ``django-admin.py makemessages`` will still find
    684684      and mark these strings for translation, but the translation won't happen
    685685      at runtime -- so you'll have to remember to wrap the languages in the
    686       *real* ``ugettext()`` in any code that uses ``LANGUAGES`` at runtime.
     686      *real* ``ugettext()`` in any code that uses :setting:`LANGUAGES` at
     687      runtime.
    687688
    688689    * The ``LocaleMiddleware`` can only select languages for which there is a
    689690      Django-provided base translation. If you want to provide translations
     
    700701      Technical message IDs are easily recognized; they're all upper case. You
    701702      don't translate the message ID as with other messages, you provide the
    702703      correct local variant on the provided English value. For example, with
    703       ``DATETIME_FORMAT`` (or ``DATE_FORMAT`` or ``TIME_FORMAT``), this would
    704       be the format string that you want to use in your language. The format
    705       is identical to the format strings used by the ``now`` template tag.
     704      :setting:`DATETIME_FORMAT` (or :setting:`DATE_FORMAT` or
     705      :setting:`TIME_FORMAT`), this would be the format string that you want to
     706      use in your language. The format is identical to the format strings used
     707      by the ``now`` template tag.
    706708
    707709Once ``LocaleMiddleware`` determines the user's preference, it makes this
    708710preference available as ``request.LANGUAGE_CODE`` for each
     
    716718            return HttpResponse("You prefer to read another language.")
    717719
    718720Note that, with static (middleware-less) translation, the language is in
    719 ``settings.LANGUAGE_CODE``, while with dynamic (middleware) translation, it's
    720 in ``request.LANGUAGE_CODE``.
     721:setting:`settings.LANGUAGE_CODE<LANGUAGE_CODE>`, while with dynamic
     722(middleware) translation, it's in ``request.LANGUAGE_CODE``.
    721723
    722724.. _settings file: ../settings/
    723725.. _middleware documentation: ../middleware/
     
    757759
    758760    * ``$APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)``
    759761    * ``$PROJECTPATH/locale/<language>/LC_MESSAGES/django.(po|mo)``
    760     * All paths listed in ``LOCALE_PATHS`` in your settings file are
     762    * All paths listed in :setting:`LOCALE_PATHS` in your settings file are
    761763      searched in that order for ``<language>/LC_MESSAGES/django.(po|mo)``
    762764    * ``$PYTHONPATH/django/conf/locale/<language>/LC_MESSAGES/django.(po|mo)``
    763765
     
    769771to produce the binary ``django.mo`` files that are used by ``gettext``.
    770772
    771773You can also run ``django-admin.py compilemessages --settings=path.to.settings``
    772 to make the compiler process all the directories in your ``LOCALE_PATHS``
     774to make the compiler process all the directories in your :setting:`LOCALE_PATHS`
    773775setting.
    774776
    775777Application message files are a bit complicated to discover -- they need the
     
    806808parameter set in request. If session support is enabled, the view
    807809saves the language choice in the user's session. Otherwise, it saves the
    808810language choice in a cookie that is by default named ``django_language``.
    809 (The name can be changed through the ``LANGUAGE_COOKIE_NAME`` setting.)
     811(The name can be changed through the :setting:`LANGUAGE_COOKIE_NAME` setting.)
    810812
    811813After setting the language choice, Django redirects the user, following this
    812814algorithm:
     
    867869        (r'^jsi18n/$', 'django.views.i18n.javascript_catalog', js_info_dict),
    868870    )
    869871
    870 Each string in ``packages`` should be in Python dotted-package syntax (the
    871 same format as the strings in ``INSTALLED_APPS``) and should refer to a package
    872 that contains a ``locale`` directory. If you specify multiple packages, all
    873 those catalogs are merged into one catalog. This is useful if you have
     872Each string in ``packages`` should be in Python dotted-package syntax (the same
     873format as the strings in :setting:`INSTALLED_APPS`) and should refer to a
     874package that contains a ``locale`` directory. If you specify multiple packages,
     875all those catalogs are merged into one catalog. This is useful if you have
    874876JavaScript that uses strings from different applications.
    875877
    876878You can make the view dynamic by putting the packages into the URL pattern::
     
    883885signs in the URL. This is especially useful if your pages use code from
    884886different apps and this changes often and you don't want to pull in one big
    885887catalog file. As a security measure, these values can only be either
    886 ``django.conf`` or any package from the ``INSTALLED_APPS`` setting.
     888``django.conf`` or any package from the :setting:`INSTALLED_APPS` setting.
    887889
    888890Using the JavaScript translation catalog
    889891----------------------------------------
     
    995997      * Add ``;C:\Program Files\gettext-utils\bin`` at the end of the
    996998        ``Variable value`` field
    997999
    998 You may also use ``gettext`` binaries you have obtained elsewhere, so long as 
     1000You may also use ``gettext`` binaries you have obtained elsewhere, so long as
    9991001the ``xgettext --version`` command works properly. Some version 0.14.4 binaries
    1000 have been found to not support this command. Do not attempt to use Django 
     1002have been found to not support this command. Do not attempt to use Django
    10011003translation utilities with a ``gettext`` package if the command ``xgettext
    10021004--version`` entered at a Windows command prompt causes a popup window saying
    10031005"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 b  
    9898In the above example, ``{{ section.title }}`` will be replaced with the
    9999``title`` attribute of the ``section`` object.
    100100
    101 If you use a variable that doesn't exist, the template system will insert
    102 the value of the ``TEMPLATE_STRING_IF_INVALID`` setting, which is set to ``''``
    103 (the empty string) by default.
     101If you use a variable that doesn't exist, the template system will insert the
     102value of the :setting:`TEMPLATE_STRING_IF_INVALID` setting, which is set to
     103``''`` (the empty string) by default.
    104104
    105105See `Using the built-in reference`_, below, for help on finding what variables
    106106are available in a given template.
     
    140140
    141141        If ``value`` isn't provided or is empty, the above will display
    142142        "``nothing``".
    143        
     143
    144144    :tfilter:`length`
    145145        Returns the length of the value. This works for both strings and lists;
    146146        for example::
     
    148148            {{ value|length }}
    149149
    150150        If ``value`` is ``['a', 'b', 'c', 'd']``, the output will be ``4``.
    151    
     151
    152152    :tfilter:`striptags`
    153153        Strips all [X]HTML tags. For example::
    154154
     
    187187                <li>{{ athlete.name }}</li>
    188188            {% endfor %}
    189189            </ul>
    190        
     190
    191191    :ttag:`if` and :ttag:`else`
    192192        Evaluates a variable, and if that variable is "true" the contents of the
    193193        block are displayed::
     
    200200
    201201        In the above, if ``athlete_list`` is not empty, the number of athletes
    202202        will be displayed by the ``{{ athlete_list|length }}`` variable.
    203        
     203
    204204    :ttag:`ifequal` and :ttag:`ifnotequal`
    205205        Display some contents if two arguments are or are not equal. For example::
    206206
     
    213213            {% ifnotequal athlete.name "Joe" %}
    214214                ...
    215215            {% endifnotequal %}
    216    
     216
    217217    :ttag:`block` and :ttag:`extends`
    218218        Set up `template inheritance`_ (see below), a powerful way
    219219        of cutting down on "boilerplate" in templates.
     
    629629Example::
    630630
    631631    {% load comments i18n %}
    632    
     632
    633633See :ref:`howto-custom-template-tags` for information on writing your own custom
    634634template libraries.
    635635
  • docs/topics/testing.txt

    diff --git a/docs/topics/testing.txt b/docs/topics/testing.txt
    a b  
    258258Note that we used ``animals``, not ``myproject.animals``.
    259259
    260260.. versionadded:: 1.0
     261
    261262   You can now choose which test to run.
    262263
    263264If you use unit tests, as opposed to
     
    416417Overview and a quick example
    417418~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    418419
    419 To use the test client, instantiate ``django.test.client.Client`` and retrieve
    420 Web pages::
     420To use the test client, instantiate :class:`django.test.client.Client` and
     421retrieve Web pages::
    421422
    422423    >>> from django.test.client import Client
    423424    >>> c = Client()
     
    470471Making requests
    471472~~~~~~~~~~~~~~~
    472473
    473 Use the ``django.test.client.Client`` class to make requests. It requires no
    474 arguments at time of construction:
     474Use the :class:`django.test.client.Client` class to make requests. It requires
     475no arguments at time of construction:
    475476
    476477.. class:: Client()
    477478
     
    779780This class provides some additional capabilities that can be useful for testing
    780781Web sites.
    781782
    782 Converting a normal ``unittest.TestCase`` to a Django ``TestCase`` is easy:
    783 just change the base class of your test from ``unittest.TestCase`` to
    784 ``django.test.TestCase``. All of the standard Python unit test functionality
    785 will continue to be available, but it will be augmented with some useful
    786 additions.
     783Converting a normal ``unittest.TestCase`` to a Django ``TestCase`` is easy: just
     784change the base class of your test from ``unittest.TestCase`` to
     785:class:`django.test.TestCase`. All of the standard Python unit test
     786functionality will continue to be available, but it will be augmented with some
     787useful additions.
    787788
    788789.. versionadded:: 1.1
    789790
    790791.. class:: TransactionTestCase()
    791792
    792 Django ``TestCase`` classes make use of database transaction facilities, if 
    793 available, to speed up the process of resetting the database to a known state 
    794 at the beginning of each test. A consequence of this, however, is that the 
    795 effects of transaction commit and rollback cannot be tested by a Django 
    796 ``TestCase`` class. If your test requires testing of such transactional 
     793Django ``TestCase`` classes make use of database transaction facilities, if
     794available, to speed up the process of resetting the database to a known state
     795at the beginning of each test. A consequence of this, however, is that the
     796effects of transaction commit and rollback cannot be tested by a Django
     797``TestCase`` class. If your test requires testing of such transactional
    797798behavior, you should use a Django ``TransactionTestCase``.
    798799
    799 ``TransactionTestCase`` and ``TestCase`` are identical except for the manner 
    800 in which the database is reset to a known state and the ability for test code 
    801 to test the effects of commit and rollback. A ``TranscationTestCase`` resets 
    802 the database before the test runs by truncating all tables and reloading 
    803 initial data. A ``TransactionTestCase`` may call commit and rollback and 
    804 observe the effects of these calls on the database. 
     800``TransactionTestCase`` and ``TestCase`` are identical except for the manner
     801in which the database is reset to a known state and the ability for test code
     802to test the effects of commit and rollback. A ``TranscationTestCase`` resets
     803the database before the test runs by truncating all tables and reloading
     804initial data. A ``TransactionTestCase`` may call commit and rollback and
     805observe the effects of these calls on the database.
    805806
    806 A ``TestCase``, on the other hand, does not truncate tables and reload initial 
    807 data at the beginning of a test. Instead, it encloses the test code in a 
    808 database transaction that is rolled back at the end of the test.  It also 
    809 prevents the code under test from issuing any commit or rollback operations 
    810 on the database, to ensure that the rollback at the end of the test restores 
    811 the database to its initial state. In order to guarantee that all ``TestCase`` 
    812 code starts with a clean database, the Django test runner runs all ``TestCase`` 
    813 tests first, before any other tests (e.g. doctests) that may alter the 
     807A ``TestCase``, on the other hand, does not truncate tables and reload initial
     808data at the beginning of a test. Instead, it encloses the test code in a
     809database transaction that is rolled back at the end of the test.  It also
     810prevents the code under test from issuing any commit or rollback operations
     811on the database, to ensure that the rollback at the end of the test restores
     812the database to its initial state. In order to guarantee that all ``TestCase``
     813code starts with a clean database, the Django test runner runs all ``TestCase``
     814tests first, before any other tests (e.g. doctests) that may alter the
    814815database without restoring it to its original state.
    815816
    816 When running on a database that does not support rollback (e.g. MySQL with the 
    817 MyISAM storage engine), ``TestCase`` falls back to initializing the database 
     817When running on a database that does not support rollback (e.g. MySQL with the
     818MyISAM storage engine), ``TestCase`` falls back to initializing the database
    818819by truncating tables and reloading initial data.
    819820
    820821
    821822.. note::
    822     The ``TestCase`` use of rollback to un-do the effects of the test code 
    823     may reveal previously-undetected errors in test code.  For example, 
    824     test code that assumes primary keys values will be assigned starting at 
    825     one may find that assumption no longer holds true when rollbacks instead 
    826     of table truncation are being used to reset the database.  Similarly, 
    827     the reordering of tests so that all ``TestCase`` classes run first may 
    828     reveal unexpected dependencies on test case ordering.  In such cases a 
     823    The ``TestCase`` use of rollback to un-do the effects of the test code
     824    may reveal previously-undetected errors in test code.  For example,
     825    test code that assumes primary keys values will be assigned starting at
     826    one may find that assumption no longer holds true when rollbacks instead
     827    of table truncation are being used to reset the database.  Similarly,
     828    the reordering of tests so that all ``TestCase`` classes run first may
     829    reveal unexpected dependencies on test case ordering.  In such cases a
    829830    quick fix is to switch the ``TestCase`` to a ``TransactionTestCase``.
    830831    A better long-term fix, that allows the test to take advantage of the
    831832    speed benefit of ``TestCase``, is to fix the underlying test problem.
    832              
     833
    833834
    834835Default test client
    835836~~~~~~~~~~~~~~~~~~~
     
    838839
    839840.. attribute:: TestCase.client
    840841
    841 Every test case in a ``django.test.TestCase`` instance has access to an
     842Every test case in a :class:`django.test.TestCase` instance has access to an
    842843instance of a Django test client. This client can be accessed as
    843844``self.client``. This client is recreated for each test, so you don't have to
    844845worry about state (such as cookies) carrying over from one test to another.
     
    903904
    904905Once you've created a fixture and placed it somewhere in your Django project,
    905906you can use it in your unit tests by specifying a ``fixtures`` class attribute
    906 on your ``django.test.TestCase`` subclass::
     907on your :class:`django.test.TestCase` subclass::
    907908
    908909    from django.test import TestCase
    909910    from myapp.models import Animal
     
    946947particular URL.
    947948
    948949In order to provide a reliable URL space for your test,
    949 ``django.test.TestCase`` provides the ability to customize the URLconf
     950:class:`django.test.TestCase` provides the ability to customize the URLconf
    950951configuration for the duration of the execution of a test suite. If your
    951952``TestCase`` instance defines an ``urls`` attribute, the ``TestCase`` will use
    952 the value of that attribute as the ``ROOT_URLCONF`` for the duration of that
    953 test.
     953the value of that attribute as the :setting:`ROOT_URLCONF` for the duration of
     954that test.
    954955
    955956For example::
    956957
     
    11741175   :synopsis: Helpers to write custom test runners.
    11751176
    11761177To assist in the creation of your own test runner, Django provides a number of
    1177 utility methods in the ``django.test.utils`` module.
     1178utility methods in the :mod:`django.test.utils` module.
    11781179
    11791180.. function:: setup_test_environment()
    11801181
     
    12091210    Returns the name of the test database that it created.
    12101211
    12111212    ``create_test_db()`` has the side effect of modifying
    1212     ``settings.DATABASE_NAME`` to match the name of the test database.
     1213    :setting:`settings.DATABASE_NAME<DATABASE_NAME>` to match the name of the
     1214    test database.
    12131215
    12141216    .. versionchanged:: 1.0
     1217
    12151218       ``create_test_db()`` now returns the name of the test database.
    12161219
    12171220.. function:: destroy_test_db(old_database_name, verbosity=1)
Back to Top