Ticket #9502: t9502-r9729.diff

File t9502-r9729.diff, 113.3 KB (added by Ramiro Morales, 16 years ago)

Patch upated to apply cleanly after r9727

  • 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
     64Django won't bother displaying the filter for a :class:`ManyToManyField` if there
    6565are fewer than two related objects.
    6666
    6767For example, if your ``list_filter`` includes ``sites``, and there's only one
  • 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
     17:data:`connection.queries` is only available if :setting:`DEBUG` is ``True``. It's a list
    1818of dictionaries in order of query execution. Each dictionary has the following::
    1919
    2020    ``sql`` -- The raw SQL statement
    2121    ``time`` -- How long the statement took to execute, in seconds.
    2222
    23 ``connection.queries`` includes all SQL statements -- INSERTs, UPDATES,
     23:data:`connection.queries` includes all SQL statements -- INSERTs, UPDATES,
    2424SELECTs, etc. Each time your app hits the database, the query will be recorded.
    2525
    2626Can I use Django with a pre-existing database?
     
    7979
    8080Django isn't known to leak memory. If you find your Django processes are
    8181allocating 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
     82sure your :setting:`DEBUG` setting is set to ``False``. If ``DEBUG`` is ``True``, then
    8383Django saves a copy of every SQL statement it has executed.
    8484
    85 (The queries are saved in ``django.db.connection.queries``. See
     85(The queries are saved in :data:`django.db.connection.queries`. See
    8686`How can I see the raw SQL queries Django is running?`_.)
    8787
    88 To fix the problem, set ``DEBUG`` to ``False``.
     88To fix the problem, set :setting:`DEBUG` to ``False``.
    8989
    9090If you need to clear the query list manually at any point in your functions,
    91 just call ``reset_queries()``, like this::
     91just call :func:`reset_queries`, like this::
    9292
    9393    from django import db
    9494    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  
    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 be a
     66: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
     76The code provided on :class:`Storage` retains only alpha-numeric characters, periods
    7777and underscores from the original filename, removing everything else.
    7878
    7979``get_available_name(name)``
     
    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------------------
     
    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
     291``datetime``. The simplest way to handle this in a :meth:`db_type` method is to
    292292import the Django settings module and check the :setting:`DATABASE_ENGINE` setting.
    293293For example::
    294294
     
    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
     421database. As the default implementation just calls :meth:`get_db_prep_value`, you
    422422shouldn't need to implement this method unless your custom field need a special
    423423conversion when being saved that is not the same as the used for normal query
    424 parameters (which is implemented by ``get_db_prep_value``).
     424parameters (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`, :lookup:`icontains`,
     457:lookup:`gt`, :lookup:`gte`, :lookup:`lt`, :lookup:`lte`, :lookup:`in`, :lookup:`startswith`, :lookup:`istartswith`,
     458:lookup:`endswith`, :lookup:`iendswith`, :lookup:`range`, :lookup:`year`, :lookup:`month`, :lookup:`day`,
     459:lookup:`isnull`, :lookup:`search`, :lookup:`regex`, and :lookup:`iregex`.
    460460
    461461Your 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
     462should raise either a :exc:`ValueError` if the ``value`` is of the wrong sort (a
    463463list when you were expecting an object, for example) or a ``TypeError`` if
    464464your field does not support that type of lookup. For many fields, you can get
    465465by with handling the lookup types that need special handling for your field
    466466and pass the rest of the :meth:`get_db_prep_lookup` method of the parent class.
    467467
    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.
     468If you needed to implement :meth:`get_db_prep_save`, you will usually need to
     469implement :meth:`get_db_prep_lookup`. If you don't, :meth:`get_db_prep_value` will be
     470called by the default implementation, to manage :lookup:`exact`, :lookup:`gt`, :lookup:`gte`,
     471:lookup:`lt`, :lookup:`lte`, :lookup:`in` and :lookup:`range` lookups.
    472472
    473473You may also want to implement this method to limit the lookup types that could
    474474be used with your custom field type.
    475475
    476 Note that, for ``range`` and ``in`` lookups, ``get_db_prep_lookup`` will receive
     476Note that, for :lookup:`range` and :lookup:`in` lookups, :meth:`get_db_prep_lookup` will receive
    477477a list of objects (presumably of the right type) and will need to convert them
    478478to 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
     479time, you can reuse :meth:`get_db_prep_value`, or at least factor out some common
    480480pieces.
    481481
    482 For example, the following code implements ``get_db_prep_lookup`` to limit the
    483 accepted lookup types to ``exact`` and ``in``::
     482For example, the following code implements :meth:`get_db_prep_lookup` to limit the
     483accepted lookup types to :lookup:`exact` and ``in``::
    484484
    485485    class HandField(models.Field):
    486486        # ...
     
    608608
    609609In addition to the above methods, fields that deal with files have a few other
    610610special requirements which must be taken into account. The majority of the
    611 mechanics provided by ``FileField``, such as controlling database storage and
     611mechanics provided by :class:`FileField`, such as controlling database storage and
    612612retrieval, can remain unchanged, leaving subclasses to deal with the challenge
    613613of supporting a particular type of file.
    614614
    615 Django provides a ``File`` class, which is used as a proxy to the file's
     615Django provides a :class:`File` class, which is used as a proxy to the file's
    616616contents and operations. This can be subclassed to customize how the file is
    617617accessed, and what methods are available. It lives at
    618 ``django.db.models.fields.files``, and its default behavior is explained in the
     618:mod:`django.db.models.fields.files`, and its default behavior is explained in the
    619619:ref:`file documentation <ref-files-file>`.
    620620
    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.
     621Once a subclass of :class:`File` is created, the new :class:`FileField` subclass must be
     622told to use it. To do so, simply assign the new :class:`File` subclass to the special
     623:attr:`attr_class` attribute of the ``FileField`` subclass.
    624624
    625625A few suggestions
    626626------------------
     
    628628In addition to the above details, there are a few guidelines which can greatly
    629629improve the efficiency and readability of the field's code.
    630630
    631     1. The source for Django's own ``ImageField`` (in
     631    1. The source for Django's own :class:`ImageField` (in
    632632       ``django/db/models/fields/files.py``) is a great example of how to
    633633       subclass ``FileField`` to support a particular type of file, as it
    634634       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
     60named ``register`` that is a :class:`template.Library` instance, in which all the
    6161tags and filters are registered. So, near the top of your module, put the
    6262following::
    6363
     
    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 template language::
    131131
    132132    register.filter('cut', cut)
    133133    register.filter('lower', lower)
    134134
    135 The ``Library.filter()`` method takes two arguments:
     135The :meth:`Library.filter` method takes two arguments:
    136136
    137137    1. The name of the filter -- a string.
    138138    2. The compilation function -- a Python function (not the name of the
    139139       function as a string).
    140140
    141 If you're using Python 2.4 or above, you can use ``register.filter()`` as a
     141If you're using Python 2.4 or above, you can use :func:`register.filter` as a
    142142decorator instead::
    143143
    144144    @register.filter(name='cut')
     
    172172      They're commonly used for output that contains raw HTML that is intended
    173173      to be interpreted as-is on the client side.
    174174
    175       Internally, these strings are of type ``SafeString`` or ``SafeUnicode``.
    176       They share a common base class of ``SafeData``, so you can test
     175      Internally, these strings are of type :class:`SafeString` or :class:`SafeUnicode`.
     176      They share a common base class of :class:`SafeData`, so you can test
    177177      for them using code like::
    178178
    179179          if isinstance(value, SafeData):
     
    184184      These strings are only escaped once, however, even if auto-escaping
    185185      applies.
    186186
    187       Internally, these strings are of type ``EscapeString`` or
    188       ``EscapeUnicode``. Generally you don't have to worry about these; they
     187      Internally, these strings are of type :class:`EscapeString` or
     188      :class:`EscapeUnicode`. Generally you don't have to worry about these; they
    189189      exist for the implementation of the ``escape`` filter.
    190190
    191191Template filter code falls into one of two situations:
     
    209209       introduce any possibility of unsafe HTML."
    210210
    211211       The reason ``is_safe`` is necessary is because there are plenty of
    212        normal string operations that will turn a ``SafeData`` object back into
     212       normal string operations that will turn a :class:`SafeData` object back into
    213213       a normal ``str`` or ``unicode`` object and, rather than try to catch
    214214       them all, which would be very difficult, Django repairs the damage after
    215215       the filter has completed.
     
    289289       ``autoescape`` keyword argument mean that our function will know whether
    290290       automatic escaping is in effect when the filter is called. We use
    291291       ``autoescape`` to decide whether the input data needs to be passed
    292        through ``django.utils.html.conditional_escape`` or not. (In the latter
     292       through :func:`django.utils.html.conditional_escape` or not. (In the latter
    293293       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``
     294       :func:`conditional_escape` function is like :func:`escape` except it only
     295       escapes input that is **not** a :class:`SafeData` instance. If a ``SafeData``
    296296       instance is passed to ``conditional_escape()``, the data is returned
    297297       unchanged.
    298298
     
    318318how the compilation works and how the rendering works.
    319319
    320320When 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``
     321''nodes''. Each node is an instance of :class:`django.template.Node` and has
     322a ``render()`` method. A compiled template is, simply, a list of :class:`Node`
    323323objects. When you call ``render()`` on a compiled template object, the template
    324324calls ``render()`` on each ``Node`` in its node list, with the given context.
    325325The results are all concatenated together to form the output of the template.
     
    346346
    347347.. _`strftime syntax`: http://docs.python.org/library/time.html#time.strftime
    348348
    349 The parser for this function should grab the parameter and create a ``Node``
     349The parser for this function should grab the parameter and create a :class:`Node`
    350350object::
    351351
    352352    from django import template
     
    368368    * ``token.contents`` is a string of the raw contents of the tag. In our
    369369      example, it's ``'current_time "%Y-%m-%d %I:%M %p"'``.
    370370
    371     * The ``token.split_contents()`` method separates the arguments on spaces
     371    * The :meth:`token.split_contents` method separates the arguments on spaces
    372372      while keeping quoted strings together. The more straightforward
    373       ``token.contents.split()`` wouldn't be as robust, as it would naively
     373      :func:`token.contents.split` wouldn't be as robust, as it would naively
    374374      split on *all* spaces, including those within quoted strings. It's a good
    375       idea to always use ``token.split_contents()``.
     375      idea to always use :meth:`token.split_contents`.
    376376
    377377    * This function is responsible for raising
    378       ``django.template.TemplateSyntaxError``, with helpful messages, for
     378      :exc:`django.template.TemplateSyntaxError`, with helpful messages, for
    379379      any syntax error.
    380380
    381     * The ``TemplateSyntaxError`` exceptions use the ``tag_name`` variable.
     381    * The :exc:`TemplateSyntaxError` exceptions use the ``tag_name`` variable.
    382382      Don't hard-code the tag's name in your error messages, because that
    383383      couples the tag's name to your function. ``token.contents.split()[0]``
    384384      will ''always'' be the name of your tag -- even when the tag has no
     
    397397Writing the renderer
    398398~~~~~~~~~~~~~~~~~~~~
    399399
    400 The second step in writing custom tags is to define a ``Node`` subclass that
    401 has a ``render()`` method.
     400The second step in writing custom tags is to define a :class:`Node` subclass that
     401has a :meth:`render` method.
    402402
    403403Continuing the above example, we need to define ``CurrentTimeNode``::
    404404
     
    443443
    444444Also, if your template tag creates a new context for performing some
    445445sub-rendering, set the auto-escape attribute to the current context's value.
    446 The ``__init__`` method for the ``Context`` class takes a parameter called
     446The ``__init__`` method for the :class:`Context` class takes a parameter called
    447447``autoescape`` that you can use for this purpose. For example::
    448448
    449449    def render(self, context):
     
    466466Registering the tag
    467467~~~~~~~~~~~~~~~~~~~
    468468
    469 Finally, register the tag with your module's ``Library`` instance, as explained
     469Finally, register the tag with your module's :class:`Library` instance, as explained
    470470in "Writing custom template filters" above. Example::
    471471
    472472    register.tag('current_time', do_current_time)
     
    496496~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    497497
    498498Although you can pass any number of arguments to a template tag using
    499 ``token.split_contents()``, the arguments are all unpacked as
     499:meth:`token.split_contents`, the arguments are all unpacked as
    500500string literals. A little more work is required in order to pass dynamic
    501501content (a template variable) to a template tag as an argument.
    502502
    503503While 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
     504returned the string, suppose you wanted to pass in a :class:`DateTimeField` from an
    505505object and have the template tag format that date-time:
    506506
    507507.. code-block:: html+django
    508508
    509509    <p>This post was last updated at {% format_time blog_entry.date_updated "%Y-%m-%d %I:%M %p" %}.</p>
    510510
    511 Initially, ``token.split_contents()`` will return three values:
     511Initially, :meth:`token.split_contents` will return three values:
    512512
    513513    1. The tag name ``format_time``.
    514514    2. The string "blog_entry.date_updated" (without the surrounding quotes).
     
    531531
    532532.. versionchanged:: 1.0
    533533    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.
     534    has been deprecated in favor of a new :class:`template.Variable` class.
    535535
    536536You also have to change the renderer to retrieve the actual contents of the
    537537``date_updated`` property of the ``blog_entry`` object.  This can be
    538 accomplished by using the ``Variable()`` class in ``django.template``.
     538accomplished by using the :class:`Variable` class in :mod:`django.template`.
    539539
    540 To use the ``Variable`` class, simply instantiate it with the name of the
     540To use the :class:`Variable` class, simply instantiate it with the name of the
    541541variable to be resolved, and then call ``variable.resolve(context)``. So,
    542542for example::
    543543
     
    553553            except template.VariableDoesNotExist:
    554554                return ''
    555555
    556 Variable resolution will throw a ``VariableDoesNotExist`` exception if it cannot
     556Variable resolution will throw a :exc:`VariableDoesNotExist` exception if it cannot
    557557resolve the string passed to it in the current context of the page.
    558558
    559559Shortcut for simple tags
     
    567567
    568568To ease the creation of the types of tags, Django provides a helper function,
    569569``simple_tag``. This function, which is a method of
    570 ``django.template.Library``, takes a function that accepts any number of
     570:class:`django.template.Library`, takes a function that accepts any number of
    571571arguments, wraps it in a ``render`` function and the other necessary bits
    572572mentioned above and registers it with the template system.
    573573
     
    652652    </ul>
    653653
    654654Now, 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
     655method on a :class:`Library` object. Following our example, if the above template is
    656656in a file called ``results.html`` in a directory that's searched by the template
    657657loader, we'd register the tag like this::
    658658
     
    690690
    691691(Note that the first parameter to the function *must* be called ``context``.)
    692692
    693 In that ``register.inclusion_tag()`` line, we specified ``takes_context=True``
     693In that :func:`register.inclusion_tag` line, we specified ``takes_context=True``
    694694and the name of the template. Here's what the template ``link.html`` might look
    695695like:
    696696
     
    802802            return ''
    803803
    804804``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
     805returns an instance of :class:`django.template.NodeList`, which is a list of
     806all :class:`Node` objects that the parser encountered ''before'' it encountered
    807807any of the tags named in the tuple.
    808808
    809809In ``"nodelist = parser.parse(('endcomment',))"`` in the above example,
     
    813813
    814814After ``parser.parse()`` is called, the parser hasn't yet "consumed" the
    815815``{% endcomment %}`` tag, so the code needs to explicitly call
    816 ``parser.delete_first_token()``.
     816:func:`parser.delete_first_token`.
    817817
    818818``CommentNode.render()`` simply returns an empty string. Anything between
    819819``{% 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  
    158158     
    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
     161      :setting:`DATABASE_NAME` should be the full absolute path, including filename, of
    162162      that file. If the file doesn't exist, it will automatically be created
    163163      when you synchronize the database for the first time (see below).
    164164     
  • docs/misc/api-stability.txt

    diff --git a/docs/misc/api-stability.txt b/docs/misc/api-stability.txt
    a b  
    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 the following parts of :mod:`django.utils` can be considered stable:
    100100
    101     - ``django.utils.cache``
    102     - ``django.utils.datastructures.SortedDict`` -- only this single class; the
     101    - :mod:`django.utils.cache`
     102    - :class:`django.utils.datastructures.SortedDict` -- only this single class; the
    103103      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``
     104    - :mod:`django.utils.encoding`
     105    - :mod:`django.utils.feedgenerator`
     106    - :mod:`django.utils.http`
     107    - :mod:`django.utils.safestring`
     108    - :mod:`django.utils.translation`
     109    - :mod:`django.utils.tzinfo`
    110110   
    111111Exceptions
    112112==========
     
    134134``django.contrib.flatpages``, we'll make sure you can still use the Django 1.4
    135135version alongside Django 1.5. This will continue to allow for easy upgrades.
    136136
    137 Historically, apps in ``django.contrib`` have been more stable than the core, so
     137Historically, apps in :mod:`django.contrib` have been more stable than the core, so
    138138in 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``.
     139worth noting if you're building apps that depend on :mod:`django.contrib`.
    140140
    141141APIs marked as internal
    142142-----------------------
  • docs/misc/design-philosophies.txt

    diff --git a/docs/misc/design-philosophies.txt b/docs/misc/design-philosophies.txt
    a b  
    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
     133This is also why the ``select_related()`` :class:`QuerySet` method exists. It's an
    134134optional performance booster for the common case of selecting "every related
    135135object."
    136136
  • 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` model::
    116116
    117117    class FlatPageAdmin(admin.ModelAdmin):
    118118        fieldsets = (
     
    184184Use this option as an alternative to ``fieldsets`` if the layout does not
    185185matter and if you want to only show a subset of the available fields in the
    186186form. For example, you could define a simpler version of the admin form for
    187 the ``django.contrib.flatpages.FlatPage`` model as follows::
     187the :class:`django.contrib.flatpages.FlatPage` model as follows::
    188188
    189189    class FlatPageAdmin(admin.ModelAdmin):
    190190        fields = ('url', 'title', 'content')
     
    411411field should be either a ``BooleanField``, ``CharField``, ``DateField``,
    412412``DateTimeField``, ``IntegerField`` or ``ForeignKey``.
    413413
    414 This example, taken from the ``django.contrib.auth.models.User`` model, shows
     414This example, taken from the :class:`django.contrib.auth.models.User` model, shows
    415415how both ``list_display`` and ``list_filter`` work::
    416416
    417417    class UserAdmin(admin.ModelAdmin):
     
    495495        radio_fields = {"group": admin.VERTICAL}
    496496
    497497You have the choice of using ``HORIZONTAL`` or ``VERTICAL`` from the
    498 ``django.contrib.admin`` module.
     498:mod:`django.contrib.admin` module.
    499499
    500500Don't include a field in ``radio_fields`` unless it's a ``ForeignKey`` or has
    501501``choices`` set.
     
    646646            }
    647647            js = ("my_code.js",)
    648648
    649 Keep in mind that this will be prepended with ``MEDIA_URL``. The same rules
     649Keep in mind that this will be prepended with :setting:`MEDIA_URL`. The same rules
    650650apply as :ref:`regular media definitions on forms <topics-forms-media>`.
    651651
    652652Adding custom validation to the admin
     
    871871
    872872If you want to allow editing and creating ``Image`` instance on the ``Product``
    873873add/change views you can simply use ``GenericInlineModelAdmin`` provided by
    874 ``django.contrib.contenttypes.generic``. In your ``admin.py`` for this
     874:mod:`django.contrib.contenttypes.generic`. In your ``admin.py`` for this
    875875example app::
    876876
    877877    from django.contrib import admin
     
    889889   
    890890    admin.site.register(Product, ProductAdmin)
    891891
    892 ``django.contrib.contenttypes.generic`` provides both a ``GenericTabularInline``
     892:mod:`django.contrib.contenttypes.generic` provides both a ``GenericTabularInline``
    893893and ``GenericStackedInline`` and behave just like any other inline. See the
    894894:ref:`contenttypes documentation <ref-contrib-contenttypes>` for more specific
    895895information.
     
    909909
    910910In order to override one or more of them, first create an ``admin`` directory in
    911911your project's ``templates`` directory. This can be any of the directories you
    912 specified in ``TEMPLATE_DIRS``.
     912specified in :setting:`TEMPLATE_DIRS`.
    913913
    914914Within this ``admin`` directory, create sub-directories named after your app.
    915915Within these app subdirectories create sub-directories named after your models.
     
    998998=====================
    999999
    10001000A Django administrative site is represented by an instance of
    1001 ``django.contrib.admin.sites.AdminSite``; by default, an instance of
     1001:class:`django.contrib.admin.sites.AdminSite`; by default, an instance of
    10021002this class is created as ``django.contrib.admin.site`` and you can
    10031003register your models and ``ModelAdmin`` instances with it.
    10041004
     
    10311031    )
    10321032
    10331033Above we used ``admin.autodiscover()`` to automatically load the
    1034 ``INSTALLED_APPS`` admin.py modules.
     1034:setting:`INSTALLED_APPS` admin.py modules.
    10351035
    10361036In this example, we register the ``AdminSite`` instance
    10371037``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."
     32The app (i.e. entry in :setting:`INSTALLED_APPS`) responsible for all "business logic."
    3333You can change this to provide custom comment models and forms, though this is
    3434currently 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
     19    ``'django.contrib.admin'``) to your :setting:`INSTALLED_APPS` setting and re-run
    2020    ``manage.py syncdb``.
    2121
    2222.. _"batteries included" philosophy: http://docs.python.org/tut/node12.html#batteries-included
     
    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  
    6464    * `United Kingdom`_
    6565    * `United States of America`_
    6666
    67 The ``django.contrib.localflavor`` package also includes a ``generic`` subpackage,
     67The :mod:`django.contrib.localflavor` package also includes a ``generic`` subpackage,
    6868containing useful code that is not specific to one particular country or
    6969culture. Currently, it defines date and datetime input fields based on those
    7070from :ref:`forms <topics-forms-index>`, but with non-US default formats.
  • 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  
    173173       :setting:`DATABASE_PORT`
    174174    3. MySQL option files.
    175175
    176 In other words, if you set the name of the database in ``DATABASE_OPTIONS``,
    177 this will take precedence over ``DATABASE_NAME``, which would override
     176In other words, if you set the name of the database in :setting:`DATABASE_OPTIONS`,
     177this will take precedence over :setting:`DATABASE_NAME`, which would override
    178178anything in a `MySQL option file`_.
    179179
    180180Here's a sample configuration which uses a MySQL option file::
  • 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``
     62the package containing your models. For example, if your :setting:`INSTALLED_APPS`
    6363contains the string ``'mysite.blog'``, the app name is ``blog``.
    6464
    6565Determining the version
     
    148148it when running interactively.
    149149
    150150This command is only available if Django's :ref:`authentication system
    151 <topics-auth>` (``django.contrib.auth``) is installed.
     151<topics-auth>` (:mod:`django.contrib.auth`) is installed.
    152152
    153153dbshell
    154154-------
     
    156156.. django-admin:: dbshell
    157157
    158158Runs 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.
     159:setting:`DATABASE_ENGINE` setting, with the connection parameters specified in your
     160:setting:`DATABASE_USER`, :setting:`DATABASE_PASSWORD`, etc., settings.
    161161
    162162    * For PostgreSQL, this runs the ``psql`` command-line client.
    163163    * For MySQL, this runs the ``mysql`` command-line client.
     
    177177settings.
    178178
    179179Settings that don't appear in the defaults are followed by ``"###"``. For
    180 example, the default settings don't define ``ROOT_URLCONF``, so
     180example, the default settings don't define :setting:`ROOT_URLCONF`, so
    181181``ROOT_URLCONF`` is followed by ``"###"`` in the output of ``diffsettings``.
    182182
    183183Note that Django's default settings live in ``django/conf/global_settings.py``,
     
    248248---------
    249249
    250250Introspects the database tables in the database pointed-to by the
    251 ``DATABASE_NAME`` setting and outputs a Django model module (a ``models.py``
     251:setting:`DATABASE_NAME` setting and outputs a Django model module (a ``models.py``
    252252file) to standard output.
    253253
    254254Use this if you have a legacy database with which you'd like to use Django.
     
    300300Django will search in three locations for fixtures:
    301301
    302302   1. In the ``fixtures`` directory of every installed application
    303    2. In any directory named in the ``FIXTURE_DIRS`` setting
     303   2. In any directory named in the :setting:`FIXTURE_DIRS` setting
    304304   3. In the literal path named by the fixture
    305305
    306306Django will load any and all fixtures it finds in these locations that match
     
    331331
    332332would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed
    333333application,  ``<dirname>/foo/bar/mydata.json`` for each directory in
    334 ``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``.
     334:setting:`FIXTURE_DIRS`, and the literal path ``foo/bar/mydata.json``.
    335335
    336336Note that the order in which fixture files are processed is undefined. However,
    337337all fixture data is installed as a single transaction, so data in
     
    525525~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    526526
    527527By 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
     528(such as CSS files, images, things under :setting:`MEDIA_URL` and so forth). If
    529529you want to configure Django to serve static media, read :ref:`howto-static-files`.
    530530
    531531Turning off auto-reload
     
    629629syncdb
    630630------
    631631
    632 Creates the database tables for all apps in ``INSTALLED_APPS`` whose tables
     632Creates the database tables for all apps in :setting:`INSTALLED_APPS` whose tables
    633633have not already been created.
    634634
    635635Use this command when you've added new applications to your project and want to
    636636install 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
     637might be in :setting:`INSTALLED_APPS` by default. When you start a new project, run
    638638this command to install the default apps.
    639639
    640640.. admonition:: Syncdb will not alter existing tables
     
    650650   to match, use the ``sql`` command to display the new SQL structure and
    651651   compare that to your existing table schema to work out the changes.
    652652
    653 If you're installing the ``django.contrib.auth`` application, ``syncdb`` will
     653If you're installing the :mod:`django.contrib.auth` application, ``syncdb`` will
    654654give you the option of creating a superuser immediately.
    655655
    656656``syncdb`` will also search for and install any fixture named ``initial_data``
     
    741741validate
    742742--------
    743743
    744 Validates all installed models (according to the ``INSTALLED_APPS`` setting)
     744Validates all installed models (according to the :setting:`INSTALLED_APPS` setting)
    745745and prints validation errors to standard output.
    746746
    747747Default options
  • 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,
     135Each :class:`Field` in a :class:`Form` class is responsible not only for validating data,
    136136but also for "cleaning" it -- normalizing it to a consistent format. This is a
    137137nice feature, because it allows data for a particular field to be input in
    138138a 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``
     146Once you've created a :class:`Form` instance with a set of data and validated it,
     147you can access the clean data via the :attr:`cleaned_data` attribute of the ``Form``
    148148object::
    149149
    150150    >>> data = {'subject': 'hello',
     
    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`` --
     163Note that any text-based field -- such as :class:`CharField` or :class:`EmailField` --
    164164always cleans the input into a Unicode string. We'll cover the encoding
    165165implications 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
     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 this
    184184example, we pass a bunch of extra fields to the ``ContactForm`` constructor,
    185 but ``cleaned_data`` contains only the form's fields::
     185but :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
     200:attr:`cleaned_data` will include a key and value for *all* fields defined in the
     201:class:`Form`, even if the data didn't include a value for fields that are not
    202202required. 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::
     203``nick_name`` field, but :attr:`cleaned_data` includes it, with an empty value::
    204204
    205205    >>> class OptionalPersonForm(Form):
    206206    ...     first_name = CharField()
     
    213213    >>> f.cleaned_data
    214214    {'nick_name': u'', 'first_name': u'John', 'last_name': u'Lennon'}
    215215
    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
     216In this above example, the :attr:`cleaned_data` value for ``nick_name`` is set to an
     217empty string, because ``nick_name`` is :class:`CharField`, and :class:`CharField`\s treat
    218218empty 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
     219is -- e.g., for :class:`DateField`, it's ``None`` instead of the empty string. For
    220220full 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.
     221for each field in the "Built-in :class:`Field` classes" section below.
    222222
    223223You can write code to perform validation for particular form fields (based on
    224224their name) or for the form as a whole (considering combinations of various
     
    227227Outputting forms as HTML
    228228------------------------
    229229
    230 The second task of a ``Form`` object is to render itself as HTML. To do so,
     230The second task of a :class:`Form` object is to render itself as HTML. To do so,
    231231simply ``print`` it::
    232232
    233233    >>> f = ContactForm()
     
    261261      ``</table>`` tags, nor does it include the ``<form>`` and ``</form>``
    262262      tags or an ``<input type="submit">`` tag. It's your job to do that.
    263263
    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
     264    * Each field type has a default HTML representation. :class:`CharField` and
     265      :class:`EmailField` are represented by an ``<input type="text">``.
     266      :class:`BooleanField` is represented by an ``<input type="checkbox">``. Note
    267267      these are merely sensible defaults; you can specify which HTML to use for
    268268      a given field by using widgets, which we'll explain shortly.
    269269
     
    288288``as_p()``
    289289~~~~~~~~~~
    290290
    291 ``Form.as_p()`` renders the form as a series of ``<p>`` tags, with each ``<p>``
     291:meth:`Form.as_p` renders the form as a series of ``<p>`` tags, with each ``<p>``
    292292containing one field::
    293293
    294294    >>> f = ContactForm()
     
    303303``as_ul()``
    304304~~~~~~~~~~~
    305305
    306 ``Form.as_ul()`` renders the form as a series of ``<li>`` tags, with each
     306:meth:`Form.as_ul` renders the form as a series of ``<li>`` tags, with each
    307307``<li>`` containing one field. It does *not* include the ``<ul>`` or ``</ul>``,
    308308so that you can specify any HTML attributes on the ``<ul>`` for flexibility::
    309309
     
    319319``as_table()``
    320320~~~~~~~~~~~~~~
    321321
    322 Finally, ``Form.as_table()`` outputs the form as an HTML ``<table>``. This is
     322Finally, :meth:`Form.as_table` outputs the form as an HTML ``<table>``. This is
    323323exactly the same as ``print``. In fact, when you ``print`` a form object, it
    324 calls its ``as_table()`` method behind the scenes::
     324calls its :meth:`as_table` method behind the scenes::
    325325
    326326    >>> f = ContactForm()
    327327    >>> f.as_table()
     
    347347This behavior is configurable, though, if you want to change the ``id``
    348348convention or remove HTML ``id`` attributes and ``<label>`` tags entirely.
    349349
    350 Use the ``auto_id`` argument to the ``Form`` constructor to control the label
     350Use the ``auto_id`` argument to the :class:`Form` constructor to control the label
    351351and ``id`` behavior. This argument must be ``True``, ``False`` or a string.
    352352
    353353If ``auto_id`` is ``False``, then the form output will not include ``<label>``
     
    442442Notes on field ordering
    443443~~~~~~~~~~~~~~~~~~~~~~~
    444444
    445 In the ``as_p()``, ``as_ul()`` and ``as_table()`` shortcuts, the fields are
     445In the :meth:`as_p`, :meth:`as_ul` and :meth:`as_table` shortcuts, the fields are
    446446displayed in the order in which you define them in your form class. For
    447447example, in the ``ContactForm`` example, the fields are defined in the order
    448448``subject``, ``message``, ``sender``, ``cc_myself``. To reorder the HTML
     
    451451How errors are displayed
    452452~~~~~~~~~~~~~~~~~~~~~~~~
    453453
    454 If you render a bound ``Form`` object, the act of rendering will automatically
     454If you render a bound :class:`Form` object, the act of rendering will automatically
    455455run the form's validation if it hasn't already happened, and the HTML output
    456456will include the validation errors as a ``<ul class="errorlist">`` near the
    457457field. The particular positioning of the error messages depends on the output
     
    483483Customizing the error list format
    484484~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    485485
    486 By default, forms use ``django.forms.util.ErrorList`` to format validation
     486By default, forms use :class:`django.forms.util.ErrorList` to format validation
    487487errors. If you'd like to use an alternate class for displaying errors, you can
    488488pass that in at construction time::
    489489
     
    506506More granular output
    507507~~~~~~~~~~~~~~~~~~~~
    508508
    509 The ``as_p()``, ``as_ul()`` and ``as_table()`` methods are simply shortcuts for
     509The :meth:`as_p`, :meth:`as_ul` and :meth:`as_table` methods are simply shortcuts for
    510510lazy developers -- they're not the only way a form object can be displayed.
    511511
    512512To display the HTML for a single field in your form, use dictionary lookup
     
    549549    >>> print f['message']
    550550    <input type="text" name="message" id="id_message" />
    551551
    552 For a field's list of errors, access the field's ``errors`` attribute. This
     552For a field's list of errors, access the field's :attr:`errors` attribute. This
    553553is a list-like object that is displayed as an HTML ``<ul class="errorlist">``
    554554when printed::
    555555
     
    575575
    576576.. versionadded:: 1.0
    577577
    578 Dealing with forms that have ``FileField`` and ``ImageField`` fields
     578Dealing with forms that have :class:`FileField` and :class:`ImageField` fields
    579579is a little more complicated than a normal form.
    580580
    581581Firstly, in order to upload files, you'll need to make sure that your
     
    586586
    587587Secondly, when you use the form, you need to bind the file data. File
    588588data is handled separately to normal form data, so when your form
    589 contains a ``FileField`` and ``ImageField``, you will need to specify
     589contains a :class:`FileField` and :class:`ImageField`, you will need to specify
    590590a second argument when you bind your form. So if we extend our
    591 ContactForm to include an ``ImageField`` called ``mugshot``, we
     591ContactForm to include an :class:`ImageField` called ``mugshot``, we
    592592need to bind the file data containing the mugshot image::
    593593
    594594    # Bound form with an image field
     
    600600    >>> file_data = {'mugshot': SimpleUploadedFile('face.jpg', <file data>)}
    601601    >>> f = ContactFormWithMugshot(data, file_data)
    602602
    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
     603In practice, you will usually specify :attr:`request.FILES` as the source
     604of file data (just like you use :attr:`request.POST` as the source of
    605605form data)::
    606606
    607607    # Bound form with an image field, data from the request
     
    617617~~~~~~~~~~~~~~~~~~~~~~~~~~~
    618618
    619619If 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
     620whether your form is a multipart form or not. The :meth:`is_multipart` method
    621621tells you whether the form requires multipart encoding for submission::
    622622
    623623    >>> f = ContactFormWithMugshot()
     
    637637Subclassing forms
    638638-----------------
    639639
    640 If you have multiple ``Form`` classes that share fields, you can use
     640If you have multiple :class:`Form` classes that share fields, you can use
    641641subclassing to remove redundancy.
    642642
    643 When you subclass a custom ``Form`` class, the resulting subclass will
     643When you subclass a custom :class:`Form` class, the resulting subclass will
    644644include all fields of the parent class(es), followed by the fields you define
    645645in the subclass.
    646646
     
    685685.. attribute:: Form.prefix
    686686
    687687You can put several Django forms inside one ``<form>`` tag. To give each
    688 ``Form`` its own namespace, use the ``prefix`` keyword argument::
     688:class:`Form` its own namespace, use the ``prefix`` keyword argument::
    689689
    690690    >>> mother = PersonForm(prefix="mother")
    691691    >>> 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  
    725725.. attribute:: URLField.validator_user_agent
    726726
    727727    String used as the user-agent used when checking for a URL's existence.
    728     Defaults to the value of the ``URL_VALIDATOR_USER_AGENT`` setting.
     728    Defaults to the value of the :setting:`URL_VALIDATOR_USER_AGENT` setting.
    729729
    730730Slightly complex built-in ``Field`` classes
    731731-------------------------------------------
  • 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  
    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).
     55    data (or ``None``, which means the :setting:`DEFAULT_CHARSET` setting is used).
    5656    You can write to this attribute to change the encoding used when accessing
    5757    the form data. Any subsequent attribute accesses (such as reading from
    5858    ``GET`` or ``POST``) will use the new ``encoding`` value.  Useful if you
     
    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
     100    value in ``FILES`` is an :class:`UploadedFile` object containing the following
    101101    attributes:
    102102
    103103        * ``read(num_bytes=None)`` -- Read a number of bytes from the file.
     
    151151
    152152.. attribute:: HttpRequest.user
    153153
    154     A ``django.contrib.auth.models.User`` object representing the currently
     154    A :class:`django.contrib.auth.models.User` object representing the currently
    155155    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::
     156    to an instance of :class:`django.contrib.auth.models.AnonymousUser`. You
     157    can tell them apart with :meth:`is_authenticated`, like so::
    158158
    159159        if request.user.is_authenticated():
    160160            # Do something for logged-in users.
     
    181181
    182182    Not defined by Django itself, but will be read if other code (e.g., a custom
    183183    middleware class) sets it. When present, this will be used as the root
    184     URLconf for the current request, overriding the ``ROOT_URLCONF`` setting.
     184    URLconf for the current request, overriding the :setting:`ROOT_URLCONF` setting.
    185185    See :ref:`how-django-processes-a-request` for details.
    186186
    187187Methods
     
    249249.. class:: QueryDict
    250250
    251251In an :class:`HttpRequest` object, the ``GET`` and ``POST`` attributes are instances
    252 of ``django.http.QueryDict``. :class:`QueryDict` is a dictionary-like
     252of ``django.http.QueryDict``. ``QueryDict`` is a dictionary-like
    253253class customized to deal with multiple values for the same key. This is
    254254necessary because some HTML form elements, notably
    255255``<select multiple="multiple">``, pass multiple values for the same key.
     
    261261Methods
    262262-------
    263263
    264 :class:`QueryDict` implements all the standard dictionary methods, because it's
     264``QueryDict`` implements all the standard dictionary methods, because it's
    265265a subclass of dictionary. Exceptions are outlined here:
    266266
    267267.. method:: QueryDict.__getitem__(key)
     
    294294    Just like the standard dictionary ``setdefault()`` method, except it uses
    295295    ``__setitem__`` internally.
    296296
    297 .. method:: QueryDict.update(other_dict) 
     297.. method:: QueryDict.update(other_dict)
    298298
    299299    Takes either a ``QueryDict`` or standard dictionary. Just like the standard
    300300    dictionary ``update()`` method, except it *appends* to the current
     
    357357
    358358    Like :meth:`items()`, except it includes all values, as a list, for each
    359359    member of the dictionary. For example::
    360    
     360
    361361         >>> q = QueryDict('a=1&a=2&a=3')
    362362         >>> q.lists()
    363363         [('a', ['1', '2', '3'])]
    364    
     364
    365365.. method:: QueryDict.urlencode()
    366366
    367367    Returns a string of the data in query-string format.
     
    373373.. class:: HttpResponse
    374374
    375375In contrast to :class:`HttpRequest` objects, which are created automatically by
    376 Django, :class:`HttpResponse` objects are your responsibility. Each view you
     376Django, ``HttpResponse`` objects are your responsibility. Each view you
    377377write is responsible for instantiating, populating and returning an
    378 :class:`HttpResponse`.
     378``HttpResponse``.
    379379
    380 The :class:`HttpResponse` class lives in the ``django.http`` module.
     380The ``HttpResponse`` class lives in the :mod:`django.http` module.
    381381
    382382Usage
    383383-----
     
    386386~~~~~~~~~~~~~~~
    387387
    388388Typical usage is to pass the contents of the page, as a string, to the
    389 :class:`HttpResponse` constructor::
     389``HttpResponse`` constructor::
    390390
    391391    >>> response = HttpResponse("Here's the text of the Web page.")
    392392    >>> response = HttpResponse("Text only, please.", mimetype="text/plain")
     
    415415hard-coded strings. If you use this technique, follow these guidelines:
    416416
    417417    * 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
     418    * If an ``HttpResponse`` has been initialized with an iterator as its
     419      content, you can't use the ``HttpResponse`` instance as a file-like
    420420      object. Doing so will raise ``Exception``.
    421421
    422422Setting headers
     
    452452-------
    453453
    454454.. method:: HttpResponse.__init__(content='', mimetype=None, status=200, content_type=DEFAULT_CONTENT_TYPE)
    455    
     455
    456456    Instantiates an ``HttpResponse`` object with the given page content (a
    457     string) and MIME type. The ``DEFAULT_CONTENT_TYPE`` is ``'text/html'``.
     457    string) and MIME type. The :setting:`DEFAULT_CONTENT_TYPE` is ``'text/html'``.
    458458
    459459    ``content`` can be an iterator or a string. If it's an iterator, it should
    460460    return strings, and those strings will be joined together to form the
     
    470470    encoding, which makes it more than just a MIME type specification.
    471471    If ``mimetype`` is specified (not ``None``), that value is used.
    472472    Otherwise, ``content_type`` is used. If neither is given, the
    473     ``DEFAULT_CONTENT_TYPE`` setting is used.
     473    :setting:`DEFAULT_CONTENT_TYPE` setting is used.
    474474
    475475.. method:: HttpResponse.__setitem__(header, value)
    476476
     
    519519
    520520.. method:: HttpResponse.write(content)
    521521
    522     This method makes an :class:`HttpResponse` instance a file-like object.
     522    This method makes an ``HttpResponse`` instance a file-like object.
    523523
    524524.. method:: HttpResponse.flush()
    525525
    526     This method makes an :class:`HttpResponse` instance a file-like object.
     526    This method makes an ``HttpResponse`` instance a file-like object.
    527527
    528528.. method:: HttpResponse.tell()
    529529
    530     This method makes an :class:`HttpResponse` instance a file-like object.
     530    This method makes an ``HttpResponse`` instance a file-like object.
    531531
    532532.. _HTTP Status code: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10
    533533
     
    537537HttpResponse subclasses
    538538-----------------------
    539539
    540 Django includes a number of ``HttpResponse`` subclasses that handle different
     540Django includes a number of :class:`HttpResponse` subclasses that handle different
    541541types of HTTP responses. Like ``HttpResponse``, these subclasses live in
    542542:mod:`django.http`.
    543543
  • 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``.
     
    680680
    681681.. function:: views.login()
    682682
    683     Here's what ``django.contrib.auth.views.login`` does:
     683    Here's what :func:`django.contrib.auth.views.login` does:
    684684
    685685        * If called via ``GET``, it displays a login form that POSTs to the same
    686686          URL. More on this in a bit.
     
    10001000Default permissions
    10011001-------------------
    10021002
    1003 When ``django.contrib.auth`` is listed in your :setting:`INSTALLED_APPS`
     1003When :mod:`django.contrib.auth` is listed in your :setting:`INSTALLED_APPS`
    10041004setting, it will ensure that three default permissions -- add, change
    10051005and delete -- are created for each Django model defined in one of your
    10061006installed applications.
    10071007
    10081008These permissions will be created when you run
    10091009:djadmin:`manage.py syncdb <syncdb>`; the first time you run ``syncdb`` after
    1010 adding ``django.contrib.auth`` to :setting:`INSTALLED_APPS`, the default
     1010adding :mod:`django.contrib.auth` to :setting:`INSTALLED_APPS`, the default
    10111011permissions will be created for all previously-installed models, as well as
    10121012for any new models being installed at that time. Afterward, it will create
    10131013default permissions for new models each time you run
  • 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
     52Your cache preference goes in the :setting:`CACHE_BACKEND` setting in your settings
    5353file. Here's an explanation of all available values for CACHE_BACKEND.
    5454
    5555Memcached
     
    8484    The ``cmemcache`` option is new in 1.0. Previously, only
    8585    ``python-memcached`` was supported.
    8686
    87 To use Memcached with Django, set ``CACHE_BACKEND`` to
     87To use Memcached with Django, set :setting:`CACHE_BACKEND` to
    8888``memcached://ip:port/``, where ``ip`` is the IP address of the Memcached
    8989daemon and ``port`` is the port on which Memcached is running.
    9090
     
    9494
    9595One excellent feature of Memcached is its ability to share cache over multiple
    9696servers. To take advantage of this feature, include all server addresses in
    97 ``CACHE_BACKEND``, separated by semicolons. In this example, the cache is
     97:setting:`CACHE_BACKEND`, separated by semicolons. In this example, the cache is
    9898shared over Memcached instances running on IP address 172.19.26.240 and
    9999172.19.26.242, both on port 11211::
    100100
     
    122122in your database that is in the proper format that Django's database-cache
    123123system expects.
    124124
    125 Once you've created that database table, set your ``CACHE_BACKEND`` setting to
     125Once you've created that database table, set your :setting:`CACHE_BACKEND` setting to
    126126``"db://tablename"``, where ``tablename`` is the name of the database table.
    127127In this example, the cache table's name is ``my_cache_table``::
    128128
     
    134134------------------
    135135
    136136To 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``,
     137:setting:`CACHE_BACKEND`. For example, to store cached data in ``/var/tmp/django_cache``,
    138138use this setting::
    139139
    140140    CACHE_BACKEND = 'file:///var/tmp/django_cache'
     
    158158
    159159If you want the speed advantages of in-memory caching but don't have the
    160160capability 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
     161cache is multi-process and thread-safe. To use it, set :setting:`CACHE_BACKEND` to
    162162``"locmem:///"``. For example::
    163163
    164164    CACHE_BACKEND = 'locmem:///'
     
    178178various places but a development/test environment on which you don't want to
    179179cache. As a result, your development environment won't use caching and your
    180180production environment still will. To activate dummy caching, set
    181 ``CACHE_BACKEND`` like so::
     181:setting:`CACHE_BACKEND` like so::
    182182
    183183    CACHE_BACKEND = 'dummy:///'
    184184
     
    190190While Django includes support for a number of cache backends out-of-the-box,
    191191sometimes you might want to use a customized cache backend. To use an external
    192192cache 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::
     193part before the initial colon) of the :setting:`CACHE_BACKEND` URI, like so::
    194194
    195195    CACHE_BACKEND = 'path.to.backend://'
    196196
     
    206206-----------------------
    207207
    208208All caches may take arguments. They're given in query-string style on the
    209 ``CACHE_BACKEND`` setting. Valid arguments are:
     209:setting:`CACHE_BACKEND` setting. Valid arguments are:
    210210
    211211    timeout
    212212        Default timeout, in seconds, to use for the cache. Defaults to 5
     
    248248entire site. You'll need to add
    249249``'django.middleware.cache.UpdateCacheMiddleware'`` and
    250250``'django.middleware.cache.FetchFromCacheMiddleware'`` to your
    251 ``MIDDLEWARE_CLASSES`` setting, as in this example::
     251:setting:`MIDDLEWARE_CLASSES` setting, as in this example::
    252252
    253253    MIDDLEWARE_CLASSES = (
    254254        'django.middleware.cache.UpdateCacheMiddleware',
     
    264264
    265265Then, add the following required settings to your Django settings file:
    266266
    267 * ``CACHE_MIDDLEWARE_SECONDS`` -- The number of seconds each page should be
     267* :setting:`CACHE_MIDDLEWARE_SECONDS` -- The number of seconds each page should be
    268268  cached.
    269 * ``CACHE_MIDDLEWARE_KEY_PREFIX`` -- If the cache is shared across multiple
     269* :setting:`CACHE_MIDDLEWARE_KEY_PREFIX` -- If the cache is shared across multiple
    270270  sites using the same Django installation, set this to the name of the site,
    271271  or some other string that is unique to this Django instance, to prevent key
    272272  collisions. Use an empty string if you don't care.
    273273
    274274The cache middleware caches every page that doesn't have GET or POST
    275 parameters. Optionally, if the ``CACHE_MIDDLEWARE_ANONYMOUS_ONLY`` setting is
     275parameters. Optionally, if the :setting:`CACHE_MIDDLEWARE_ANONYMOUS_ONLY` setting is
    276276``True``, only anonymous requests (i.e., not those made by a logged-in user)
    277277will be cached. This is a simple and effective way of disabling caching for any
    278278user-specific pages (include Django's admin interface). Note that if you use
    279 ``CACHE_MIDDLEWARE_ANONYMOUS_ONLY``, you should make sure you've activated
     279:setting:`CACHE_MIDDLEWARE_ANONYMOUS_ONLY`, you should make sure you've activated
    280280``AuthenticationMiddleware``.
    281281
    282282Additionally, the cache middleware automatically sets a few headers in each
     
    285285* Sets the ``Last-Modified`` header to the current date/time when a fresh
    286286  (uncached) version of the page is requested.
    287287* Sets the ``Expires`` header to the current date/time plus the defined
    288   ``CACHE_MIDDLEWARE_SECONDS``.
     288  :setting:`CACHE_MIDDLEWARE_SECONDS`.
    289289* Sets the ``Cache-Control`` header to give a max age for the page -- again,
    290   from the ``CACHE_MIDDLEWARE_SECONDS`` setting.
     290  from the :setting:`CACHE_MIDDLEWARE_SECONDS` setting.
    291291
    292292See :ref:`topics-http-middleware` for more on middleware.
    293293
     
    295295
    296296If a view sets its own cache expiry time (i.e. it has a ``max-age`` section in
    297297its ``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
     298time, rather than :setting:`CACHE_MIDDLEWARE_SECONDS`. Using the decorators in
     299:mod:`django.views.decorators.cache` you can easily set a view's expiry time
    300300(using the ``cache_control`` decorator) or disable caching for a view (using
    301301the ``never_cache`` decorator). See the `using other headers`__ section for
    302302more on these decorators.
     
    307307==================
    308308
    309309A 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``
     310individual views. :mod:`django.views.decorators.cache` defines a ``cache_page``
    311311decorator that will automatically cache the view's response for you. It's easy
    312312to use::
    313313
     
    379379intensive database query. In cases like this, you can use the low-level cache
    380380API to store objects in the cache with any level of granularity you like.
    381381
    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``
     382The cache API is simple. The cache module, :mod:`django.core.cache`, exports a
     383``cache`` object that's automatically created from the :setting:`CACHE_BACKEND`
    384384setting::
    385385
    386386    >>> from django.core.cache import cache
     
    392392    'hello, world!'
    393393
    394394The ``timeout_seconds`` argument is optional and defaults to the ``timeout``
    395 argument in the ``CACHE_BACKEND`` setting (explained above).
     395argument in the :setting:`CACHE_BACKEND` setting (explained above).
    396396
    397397If the object doesn't exist in the cache, ``cache.get()`` returns ``None``::
    398398
     
    618618For explanation of Cache-Control HTTP directives, see the `Cache-Control spec`_.
    619619
    620620(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
     621the value of the :setting:`CACHE_MIDDLEWARE_SETTINGS` setting. If you use a custom
    622622``max_age`` in a ``cache_control`` decorator, the decorator will take
    623623precedence, and the header values will be merged correctly.)
    624624
     
    650650===========================
    651651
    652652If 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
     653place within the :setting:`MIDDLEWARE_CLASSES` setting. That's because the cache
    654654middleware needs to know which headers by which to vary the cache storage.
    655655Middleware always adds something to the ``Vary`` response header when it can.
    656656
  • 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 file.
    140140
    141141If you do this, Django won't provide any automatic transaction management
    142142whatsoever. 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
     51:mod:`django.utils` helper functions and Django's internationalization hooks (but
    5252you're not required to be using internationalization features to use this
    5353library).
    5454
  • 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  
    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
     217handlers are initially defined in the :setting:`FILE_UPLOAD_HANDLERS` setting, which
    218218defaults to::
    219219
    220220    ("django.core.files.uploadhandler.MemoryFileUploadHandler",
     
    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
     238handlers given by :setting:`FILE_UPLOAD_HANDLERS`, but you can modify the list as you
    239239would any other list.
    240240
    241241For instance, suppose you've written a ``ProgressBarUploadHandler`` that
  • 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'``.
     19    * Edit the :setting:`MIDDLEWARE_CLASSES` setting and make sure
     20      :setting:`MIDDLEWARE_CLASSES` contains ``'django.contrib.sessions.middleware.SessionMiddleware'``.
    2121      The default ``settings.py`` created by ``django-admin.py startproject`` has
    2222      ``SessionMiddleware`` activated.
    2323
    24     * Add ``'django.contrib.sessions'`` to your ``INSTALLED_APPS`` setting,
     24    * Add ``'django.contrib.sessions'`` to your :setting:`INSTALLED_APPS` setting,
    2525      and run ``manage.py syncdb`` to install the single database table
    2626      that stores session data.
    2727
     
    3030   see `configuring the session engine`_.
    3131
    3232If 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.
     33``SessionMiddleware`` line from :setting:`MIDDLEWARE_CLASSES` and ``'django.contrib.sessions'``
     34from your :setting:`INSTALLED_APPS`. It'll save you a small bit of overhead.
    3535
    3636Configuring the session engine
    3737==============================
     
    8686Using file-based sessions
    8787-------------------------
    8888
    89 To use file-based sessions, set the ``SESSION_ENGINE`` setting to
     89To use file-based sessions, set the :setting:`SESSION_ENGINE` setting to
    9090``"django.contrib.sessions.backends.file"``.
    9191
    92 You might also want to set the ``SESSION_FILE_PATH`` setting (which defaults
     92You might also want to set the :setting:`SESSION_FILE_PATH` setting (which defaults
    9393to output from ``tempfile.gettempdir()``, most likely ``/tmp``) to control
    9494where Django stores session files. Be sure to check that your Web server has
    9595permissions to read and write to this location.
     
    192192
    193193      Returns the number of seconds until this session expires. For sessions
    194194      with no custom expiration (or those set to expire at browser close), this
    195       will equal ``settings.SESSION_COOKIE_AGE``.
     195      will equal :setting:`setting.SESSION_COOKIE_AGE<SESSION_COOKIE_AGE>`.
    196196
    197197    * ``get_expiry_date()``
    198198
     
    200200
    201201      Returns the date this session will expire. For sessions with no custom
    202202      expiration (or those set to expire at browser close), this will equal the
    203       date ``settings.SESSION_COOKIE_AGE`` seconds from now.
     203      date :setting:`settings.SESSION_COOKIE_AGE<SESSION_COOKIE_AGE>` seconds from now.
    204204
    205205    * ``get_expire_at_browser_close()``
    206206
     
    303303    datetime.datetime(2005, 8, 20, 13, 35, 0)
    304304    >>> s.save()
    305305
    306 If you're using the ``django.contrib.sessions.backends.db`` backend, each
     306If you're using the :mod:`django.contrib.sessions.backends.db` backend, each
    307307session is just a normal Django model. The ``Session`` model is defined in
    308308``django/contrib/sessions/models.py``. Because it's a normal model, you can
    309309access sessions using the normal Django database API::
     
    347347
    348348    request.session.modified = True
    349349
    350 To change this default behavior, set the ``SESSION_SAVE_EVERY_REQUEST`` setting
     350To change this default behavior, set the :setting:`SESSION_SAVE_EVERY_REQUEST` setting
    351351to ``True``. If ``SESSION_SAVE_EVERY_REQUEST`` is ``True``, Django will save
    352352the session to the database on every single request.
    353353
     
    362362===============================================
    363363
    364364You can control whether the session framework uses browser-length sessions vs.
    365 persistent sessions with the ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` setting.
     365persistent sessions with the :setting:`SESSION_EXPIRE_AT_BROWSER_CLOSE` setting.
    366366
    367367By default, ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` is set to ``False``, which
    368368means 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
     369:setting:`SESSION_COOKIE_AGE`. Use this if you don't want people to have to log in
    370370every time they open a browser.
    371371
    372372If ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` is set to ``True``, Django will use
     
    407407
    408408.. versionadded:: 1.0
    409409
    410 Default: ``django.contrib.sessions.backends.db``
     410Default: :mod:`django.contrib.sessions.backends.db`
    411411
    412412Controls where Django stores session data. Valid values are:
    413413
  • 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  
    3737algorithm the system follows to determine which Python code to execute:
    3838
    3939    1. Django determines the root URLconf module to use. Ordinarily,
    40        this is the value of the ``ROOT_URLCONF`` setting, but if the incoming
     40       this is the 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
     
    5050
    5151.. admonition:: Django's Time Zone
    5252   
    53     Django includes a ``TIME_ZONE`` setting that defaults to
     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 (e.g.,
     169      :setting:`MEDIA_URL`).
    170170
    171     * If ``DEBUG`` is set to ``True`` (in your settings module), then your 404
     171    * If :setting:`DEBUG` is set to ``True`` (in your settings module), then your 404
    172172      view will never be used, and the traceback will be displayed instead.
    173173
    174174The 500 (server error) view
  • 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
     595to your :setting:`MIDDLEWARE_CLASSES` setting. Because middleware order matters, you
    596596should follow these guidelines:
    597597
    598598    * Make sure it's one of the first middlewares installed.
     
    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
     665    * If you define a custom :setting:`LANGUAGES` setting, as explained in the
    666666      previous bullet, it's OK to mark the languages as translation strings
    667667      -- 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
     668      :mod:`django.utils.translation`. You should *never* import
     669      :mod:`django.utils.translation` from within your settings file, because that
    670670      module in itself depends on the settings, and that would cause a circular
    671671      import.
    672672
     
    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 runtime.
    687687
    688688    * The ``LocaleMiddleware`` can only select languages for which there is a
    689689      Django-provided base translation. If you want to provide translations
     
    700700      Technical message IDs are easily recognized; they're all upper case. You
    701701      don't translate the message ID as with other messages, you provide the
    702702      correct local variant on the provided English value. For example, with
    703       ``DATETIME_FORMAT`` (or ``DATE_FORMAT`` or ``TIME_FORMAT``), this would
     703      :setting:`DATETIME_FORMAT` (or :setting:`DATE_FORMAT` or :setting:`TIME_FORMAT`), this would
    704704      be the format string that you want to use in your language. The format
    705705      is identical to the format strings used by the ``now`` template tag.
    706706
     
    716716            return HttpResponse("You prefer to read another language.")
    717717
    718718Note that, with static (middleware-less) translation, the language is in
    719 ``settings.LANGUAGE_CODE``, while with dynamic (middleware) translation, it's
     719:setting:`settings.LANGUAGE_CODE<LANGUAGE_CODE>`, while with dynamic (middleware) translation, it's
    720720in ``request.LANGUAGE_CODE``.
    721721
    722722.. _settings file: ../settings/
     
    757757
    758758    * ``$APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)``
    759759    * ``$PROJECTPATH/locale/<language>/LC_MESSAGES/django.(po|mo)``
    760     * All paths listed in ``LOCALE_PATHS`` in your settings file are
     760    * All paths listed in :setting:`LOCALE_PATHS` in your settings file are
    761761      searched in that order for ``<language>/LC_MESSAGES/django.(po|mo)``
    762762    * ``$PYTHONPATH/django/conf/locale/<language>/LC_MESSAGES/django.(po|mo)``
    763763
     
    769769to produce the binary ``django.mo`` files that are used by ``gettext``.
    770770
    771771You can also run ``django-admin.py compilemessages --settings=path.to.settings``
    772 to make the compiler process all the directories in your ``LOCALE_PATHS``
     772to make the compiler process all the directories in your :setting:`LOCALE_PATHS`
    773773setting.
    774774
    775775Application message files are a bit complicated to discover -- they need the
     
    806806parameter set in request. If session support is enabled, the view
    807807saves the language choice in the user's session. Otherwise, it saves the
    808808language choice in a cookie that is by default named ``django_language``.
    809 (The name can be changed through the ``LANGUAGE_COOKIE_NAME`` setting.)
     809(The name can be changed through the :setting:`LANGUAGE_COOKIE_NAME` setting.)
    810810
    811811After setting the language choice, Django redirects the user, following this
    812812algorithm:
     
    868868    )
    869869
    870870Each 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
     871same format as the strings in :setting:`INSTALLED_APPS`) and should refer to a package
    872872that contains a ``locale`` directory. If you specify multiple packages, all
    873873those catalogs are merged into one catalog. This is useful if you have
    874874JavaScript that uses strings from different applications.
     
    883883signs in the URL. This is especially useful if your pages use code from
    884884different apps and this changes often and you don't want to pull in one big
    885885catalog file. As a security measure, these values can only be either
    886 ``django.conf`` or any package from the ``INSTALLED_APPS`` setting.
     886``django.conf`` or any package from the :setting:`INSTALLED_APPS` setting.
    887887
    888888Using the JavaScript translation catalog
    889889----------------------------------------
     
    995995      * Add ``;C:\Program Files\gettext-utils\bin`` at the end of the
    996996        ``Variable value`` field
    997997
    998 You may also use ``gettext`` binaries you have obtained elsewhere, so long as 
     998You may also use ``gettext`` binaries you have obtained elsewhere, so long as
    999999the ``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 
     1000have been found to not support this command. Do not attempt to use Django
    10011001translation utilities with a ``gettext`` package if the command ``xgettext
    10021002--version`` entered at a Windows command prompt causes a popup window saying
    10031003"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  
    9999``title`` attribute of the ``section`` object.
    100100
    101101If 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 ``''``
     102the value of the :setting:`TEMPLATE_STRING_IF_INVALID` setting, which is set to ``''``
    103103(the empty string) by default.
    104104
    105105See `Using the built-in reference`_, below, for help on finding what variables
  • docs/topics/testing.txt

    diff --git a/docs/topics/testing.txt b/docs/topics/testing.txt
    a b  
    416416Overview and a quick example
    417417~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    418418
    419 To use the test client, instantiate ``django.test.client.Client`` and retrieve
     419To use the test client, instantiate :class:`django.test.client.Client` and retrieve
    420420Web pages::
    421421
    422422    >>> from django.test.client import Client
     
    470470Making requests
    471471~~~~~~~~~~~~~~~
    472472
    473 Use the ``django.test.client.Client`` class to make requests. It requires no
     473Use the :class:`django.test.client.Client` class to make requests. It requires no
    474474arguments at time of construction:
    475475
    476476.. class:: Client()
     
    781781
    782782Converting a normal ``unittest.TestCase`` to a Django ``TestCase`` is easy:
    783783just change the base class of your test from ``unittest.TestCase`` to
    784 ``django.test.TestCase``. All of the standard Python unit test functionality
     784:class:`django.test.TestCase`. All of the standard Python unit test functionality
    785785will continue to be available, but it will be augmented with some useful
    786786additions.
    787787
     
    792792
    793793.. attribute:: TestCase.client
    794794
    795 Every test case in a ``django.test.TestCase`` instance has access to an
     795Every test case in a :class:`django.test.TestCase` instance has access to an
    796796instance of a Django test client. This client can be accessed as
    797797``self.client``. This client is recreated for each test, so you don't have to
    798798worry about state (such as cookies) carrying over from one test to another.
     
    857857
    858858Once you've created a fixture and placed it somewhere in your Django project,
    859859you can use it in your unit tests by specifying a ``fixtures`` class attribute
    860 on your ``django.test.TestCase`` subclass::
     860on your :class:`django.test.TestCase` subclass::
    861861
    862862    from django.test import TestCase
    863863    from myapp.models import Animal
     
    900900particular URL.
    901901
    902902In order to provide a reliable URL space for your test,
    903 ``django.test.TestCase`` provides the ability to customize the URLconf
     903:class:`django.test.TestCase` provides the ability to customize the URLconf
    904904configuration for the duration of the execution of a test suite. If your
    905905``TestCase`` instance defines an ``urls`` attribute, the ``TestCase`` will use
    906 the value of that attribute as the ``ROOT_URLCONF`` for the duration of that
     906the value of that attribute as the :setting:`ROOT_URLCONF` for the duration of that
    907907test.
    908908
    909909For example::
     
    11281128   :synopsis: Helpers to write custom test runners.
    11291129
    11301130To assist in the creation of your own test runner, Django provides a number of
    1131 utility methods in the ``django.test.utils`` module.
     1131utility methods in the :mod:`django.test.utils` module.
    11321132
    11331133.. function:: setup_test_environment()
    11341134
     
    11631163    Returns the name of the test database that it created.
    11641164
    11651165    ``create_test_db()`` has the side effect of modifying
    1166     ``settings.DATABASE_NAME`` to match the name of the test database.
     1166    :setting:`settings.DATABASE_NAME<DATABASE_NAME>` to match the name of the test database.
    11671167
    11681168    .. versionchanged:: 1.0
    11691169       ``create_test_db()`` now returns the name of the test database.
Back to Top