Ticket #9502: t9502-1.0.X-r9729.diff

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

Patch for 1.0.X branch as of r9729 as the docs contents have started to diverge from trunk.

  • 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
     
    152152it when running interactively.
    153153
    154154This command is only available if Django's :ref:`authentication system
    155 <topics-auth>` (``django.contrib.auth``) is installed.
     155<topics-auth>` (:mod:`django.contrib.auth`) is installed.
    156156
    157157dbshell
    158158-------
     
    160160.. django-admin:: dbshell
    161161
    162162Runs the command-line client for the database engine specified in your
    163 ``DATABASE_ENGINE`` setting, with the connection parameters specified in your
    164 ``DATABASE_USER``, ``DATABASE_PASSWORD``, etc., settings.
     163:setting:`DATABASE_ENGINE` setting, with the connection parameters specified in your
     164:setting:`DATABASE_USER`, :setting:`DATABASE_PASSWORD`, etc., settings.
    165165
    166166    * For PostgreSQL, this runs the ``psql`` command-line client.
    167167    * For MySQL, this runs the ``mysql`` command-line client.
     
    181181settings.
    182182
    183183Settings that don't appear in the defaults are followed by ``"###"``. For
    184 example, the default settings don't define ``ROOT_URLCONF``, so
     184example, the default settings don't define :setting:`ROOT_URLCONF`, so
    185185``ROOT_URLCONF`` is followed by ``"###"`` in the output of ``diffsettings``.
    186186
    187187Note that Django's default settings live in ``django/conf/global_settings.py``,
     
    252252---------
    253253
    254254Introspects the database tables in the database pointed-to by the
    255 ``DATABASE_NAME`` setting and outputs a Django model module (a ``models.py``
     255:setting:`DATABASE_NAME` setting and outputs a Django model module (a ``models.py``
    256256file) to standard output.
    257257
    258258Use this if you have a legacy database with which you'd like to use Django.
     
    301301Django will search in three locations for fixtures:
    302302
    303303   1. In the ``fixtures`` directory of every installed application
    304    2. In any directory named in the ``FIXTURE_DIRS`` setting
     304   2. In any directory named in the :setting:`FIXTURE_DIRS` setting
    305305   3. In the literal path named by the fixture
    306306
    307307Django will load any and all fixtures it finds in these locations that match
     
    336336
    337337would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed
    338338application,  ``<dirname>/foo/bar/mydata.json`` for each directory in
    339 ``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``.
     339:setting:`FIXTURE_DIRS`, and the literal path ``foo/bar/mydata.json``.
    340340
    341341Note that the order in which fixture files are processed is undefined. However,
    342342all fixture data is installed as a single transaction, so data in
     
    541541~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    542542
    543543By default, the development server doesn't serve any static files for your site
    544 (such as CSS files, images, things under ``MEDIA_URL`` and so forth). If
     544(such as CSS files, images, things under :setting:`MEDIA_URL` and so forth). If
    545545you want to configure Django to serve static media, read :ref:`howto-static-files`.
    546546
    547547Turning off auto-reload
     
    645645syncdb
    646646------
    647647
    648 Creates the database tables for all apps in ``INSTALLED_APPS`` whose tables
     648Creates the database tables for all apps in :setting:`INSTALLED_APPS` whose tables
    649649have not already been created.
    650650
    651651Use this command when you've added new applications to your project and want to
    652652install them in the database. This includes any apps shipped with Django that
    653 might be in ``INSTALLED_APPS`` by default. When you start a new project, run
     653might be in :setting:`INSTALLED_APPS` by default. When you start a new project, run
    654654this command to install the default apps.
    655655
    656656.. admonition:: Syncdb will not alter existing tables
     
    666666   to match, use the ``sql`` command to display the new SQL structure and
    667667   compare that to your existing table schema to work out the changes.
    668668
    669 If you're installing the ``django.contrib.auth`` application, ``syncdb`` will
     669If you're installing the :mod:`django.contrib.auth` application, ``syncdb`` will
    670670give you the option of creating a superuser immediately.
    671671
    672672``syncdb`` will also search for and install any fixture named ``initial_data``
     
    799799validate
    800800--------
    801801
    802 Validates all installed models (according to the ``INSTALLED_APPS`` setting)
     802Validates all installed models (according to the :setting:`INSTALLED_APPS` setting)
    803803and prints validation errors to standard output.
    804804
    805805Default 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
     
    186186      page. This lets you override the default template name (see below).
    187187
    188188    * ``template_loader``: The template loader to use when loading the
    189       template. By default, it's ``django.template.loader``.
     189      template. By default, it's :mod:`django.template.loader`.
    190190
    191191    * ``extra_context``: A dictionary of values to add to the template
    192192      context. By default, this is an empty dictionary. If a value in the
     
    202202      the view's template.
    203203
    204204    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    205       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     205      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    206206
    207207    * ``allow_future``: A boolean specifying whether to include "future"
    208208      objects on this page, where "future" means objects in which the field
     
    271271      page. This lets you override the default template name (see below).
    272272
    273273    * ``template_loader``: The template loader to use when loading the
    274       template. By default, it's ``django.template.loader``.
     274      template. By default, it's :mod:`django.template.loader`.
    275275
    276276    * ``extra_context``: A dictionary of values to add to the template
    277277      context. By default, this is an empty dictionary. If a value in the
     
    299299      this is ``False``.
    300300
    301301    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    302       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     302      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    303303
    304304    * ``allow_future``: A boolean specifying whether to include "future"
    305305      objects on this page, where "future" means objects in which the field
     
    365365      page. This lets you override the default template name (see below).
    366366
    367367    * ``template_loader``: The template loader to use when loading the
    368       template. By default, it's ``django.template.loader``.
     368      template. By default, it's :mod:`django.template.loader`.
    369369
    370370    * ``extra_context``: A dictionary of values to add to the template
    371371      context. By default, this is an empty dictionary. If a value in the
     
    386386      determining the variable's name.
    387387
    388388    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    389       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     389      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    390390
    391391    * ``allow_future``: A boolean specifying whether to include "future"
    392392      objects on this page, where "future" means objects in which the field
     
    446446      page. This lets you override the default template name (see below).
    447447
    448448    * ``template_loader``: The template loader to use when loading the
    449       template. By default, it's ``django.template.loader``.
     449      template. By default, it's :mod:`django.template.loader`.
    450450
    451451    * ``extra_context``: A dictionary of values to add to the template
    452452      context. By default, this is an empty dictionary. If a value in the
     
    467467      determining the variable's name.
    468468
    469469    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    470       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     470      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    471471
    472472    * ``allow_future``: A boolean specifying whether to include "future"
    473473      objects on this page, where "future" means objects in which the field
     
    531531      page. This lets you override the default template name (see below).
    532532
    533533    * ``template_loader``: The template loader to use when loading the
    534       template. By default, it's ``django.template.loader``.
     534      template. By default, it's :mod:`django.template.loader`.
    535535
    536536    * ``extra_context``: A dictionary of values to add to the template
    537537      context. By default, this is an empty dictionary. If a value in the
     
    552552      determining the variable's name.
    553553
    554554    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    555       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     555      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    556556
    557557    * ``allow_future``: A boolean specifying whether to include "future"
    558558      objects on this page, where "future" means objects in which the field
     
    648648      It's a bit of a brain-bender, but it's useful in some cases.
    649649
    650650    * ``template_loader``: The template loader to use when loading the
    651       template. By default, it's ``django.template.loader``.
     651      template. By default, it's :mod:`django.template.loader`.
    652652
    653653    * ``extra_context``: A dictionary of values to add to the template
    654654      context. By default, this is an empty dictionary. If a value in the
     
    662662      to use in the template context. By default, this is ``'object'``.
    663663
    664664    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    665       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     665      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    666666
    667667    * ``allow_future``: A boolean specifying whether to include "future"
    668668      objects on this page, where "future" means objects in which the field
     
    717717      page. This lets you override the default template name (see below).
    718718
    719719    * ``template_loader``: The template loader to use when loading the
    720       template. By default, it's ``django.template.loader``.
     720      template. By default, it's :mod:`django.template.loader`.
    721721
    722722    * ``extra_context``: A dictionary of values to add to the template
    723723      context. By default, this is an empty dictionary. If a value in the
     
    738738      determining the variable's name.
    739739
    740740    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    741       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     741      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    742742
    743743**Template name:**
    744744
     
    843843      It's a bit of a brain-bender, but it's useful in some cases.
    844844
    845845    * ``template_loader``: The template loader to use when loading the
    846       template. By default, it's ``django.template.loader``.
     846      template. By default, it's :mod:`django.template.loader`.
    847847
    848848    * ``extra_context``: A dictionary of values to add to the template
    849849      context. By default, this is an empty dictionary. If a value in the
     
    857857      to use in the template context. By default, this is ``'object'``.
    858858
    859859    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    860       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     860      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    861861
    862862**Template name:**
    863863
     
    926926      page. This lets you override the default template name (see below).
    927927
    928928    * ``template_loader``: The template loader to use when loading the
    929       template. By default, it's ``django.template.loader``.
     929      template. By default, it's :mod:`django.template.loader`.
    930930
    931931    * ``extra_context``: A dictionary of values to add to the template
    932932      context. By default, this is an empty dictionary. If a value in the
     
    10111011      page. This lets you override the default template name (see below).
    10121012
    10131013    * ``template_loader``: The template loader to use when loading the
    1014       template. By default, it's ``django.template.loader``.
     1014      template. By default, it's :mod:`django.template.loader`.
    10151015
    10161016    * ``extra_context``: A dictionary of values to add to the template
    10171017      context. By default, this is an empty dictionary. If a value in the
     
    10931093      page. This lets you override the default template name (see below).
    10941094
    10951095    * ``template_loader``: The template loader to use when loading the
    1096       template. By default, it's ``django.template.loader``.
     1096      template. By default, it's :mod:`django.template.loader`.
    10971097
    10981098    * ``extra_context``: A dictionary of values to add to the template
    10991099      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  
    15871587-------------------------------
    15881588
    15891589Django comes with a couple of other template-tag libraries that you have to
    1590 enable explicitly in your ``INSTALLED_APPS`` setting and enable in your
     1590enable explicitly in your :setting:`INSTALLED_APPS` setting and enable in your
    15911591template with the ``{% load %}`` tag.
    15921592
    15931593django.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==============================
     
    4646Using file-based sessions
    4747-------------------------
    4848
    49 To use file-based sessions, set the ``SESSION_ENGINE`` setting to
     49To use file-based sessions, set the :setting:`SESSION_ENGINE` setting to
    5050``"django.contrib.sessions.backends.file"``.
    5151
    52 You might also want to set the ``SESSION_FILE_PATH`` setting (which defaults
     52You might also want to set the :setting:`SESSION_FILE_PATH` setting (which defaults
    5353to output from ``tempfile.gettempdir()``, most likely ``/tmp``) to control
    5454where Django stores session files. Be sure to check that your Web server has
    5555permissions to read and write to this location.
     
    5757Using cache-based sessions
    5858--------------------------
    5959
    60 To store session data using Django's cache system, set ``SESSION_ENGINE``
     60To store session data using Django's cache system, set :setting:`SESSION_ENGINE`
    6161to ``"django.contrib.sessions.backends.cache"``. You'll want to make sure
    6262you've configured your cache; see the :ref:`cache documentation <topics-cache>` for details.
    6363
     
    169169
    170170      Returns the number of seconds until this session expires. For sessions
    171171      with no custom expiration (or those set to expire at browser close), this
    172       will equal ``settings.SESSION_COOKIE_AGE``.
     172      will equal :setting:`setting.SESSION_COOKIE_AGE<SESSION_COOKIE_AGE>`.
    173173
    174174    * ``get_expiry_date()``
    175175
     
    177177
    178178      Returns the date this session will expire. For sessions with no custom
    179179      expiration (or those set to expire at browser close), this will equal the
    180       date ``settings.SESSION_COOKIE_AGE`` seconds from now.
     180      date :setting:`settings.SESSION_COOKIE_AGE<SESSION_COOKIE_AGE>` seconds from now.
    181181
    182182    * ``get_expire_at_browser_close()``
    183183
     
    280280    datetime.datetime(2005, 8, 20, 13, 35, 0)
    281281    >>> s.save()
    282282
    283 If you're using the ``django.contrib.sessions.backends.db`` backend, each
     283If you're using the :mod:`django.contrib.sessions.backends.db` backend, each
    284284session is just a normal Django model. The ``Session`` model is defined in
    285285``django/contrib/sessions/models.py``. Because it's a normal model, you can
    286286access sessions using the normal Django database API::
     
    324324
    325325    request.session.modified = True
    326326
    327 To change this default behavior, set the ``SESSION_SAVE_EVERY_REQUEST`` setting
     327To change this default behavior, set the :setting:`SESSION_SAVE_EVERY_REQUEST` setting
    328328to ``True``. If ``SESSION_SAVE_EVERY_REQUEST`` is ``True``, Django will save
    329329the session to the database on every single request.
    330330
     
    339339===============================================
    340340
    341341You can control whether the session framework uses browser-length sessions vs.
    342 persistent sessions with the ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` setting.
     342persistent sessions with the :setting:`SESSION_EXPIRE_AT_BROWSER_CLOSE` setting.
    343343
    344344By default, ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` is set to ``False``, which
    345345means session cookies will be stored in users' browsers for as long as
    346 ``SESSION_COOKIE_AGE``. Use this if you don't want people to have to log in
     346:setting:`SESSION_COOKIE_AGE`. Use this if you don't want people to have to log in
    347347every time they open a browser.
    348348
    349349If ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` is set to ``True``, Django will use
     
    384384
    385385.. versionadded:: 1.0
    386386
    387 Default: ``django.contrib.sessions.backends.db``
     387Default: :mod:`django.contrib.sessions.backends.db`
    388388
    389389Controls where Django stores session data. Valid values are:
    390390
  • 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()
     
    727727
    728728Converting a normal ``unittest.TestCase`` to a Django ``TestCase`` is easy:
    729729just change the base class of your test from ``unittest.TestCase`` to
    730 ``django.test.TestCase``. All of the standard Python unit test functionality
     730:class:`django.test.TestCase`. All of the standard Python unit test functionality
    731731will continue to be available, but it will be augmented with some useful
    732732additions.
    733733
     
    738738
    739739.. attribute:: TestCase.client
    740740
    741 Every test case in a ``django.test.TestCase`` instance has access to an
     741Every test case in a :class:`django.test.TestCase` instance has access to an
    742742instance of a Django test client. This client can be accessed as
    743743``self.client``. This client is recreated for each test, so you don't have to
    744744worry about state (such as cookies) carrying over from one test to another.
     
    803803
    804804Once you've created a fixture and placed it somewhere in your Django project,
    805805you can use it in your unit tests by specifying a ``fixtures`` class attribute
    806 on your ``django.test.TestCase`` subclass::
     806on your :class:`django.test.TestCase` subclass::
    807807
    808808    from django.test import TestCase
    809809    from myapp.models import Animal
     
    846846particular URL.
    847847
    848848In order to provide a reliable URL space for your test,
    849 ``django.test.TestCase`` provides the ability to customize the URLconf
     849:class:`django.test.TestCase` provides the ability to customize the URLconf
    850850configuration for the duration of the execution of a test suite. If your
    851851``TestCase`` instance defines an ``urls`` attribute, the ``TestCase`` will use
    852 the value of that attribute as the ``ROOT_URLCONF`` for the duration of that
     852the value of that attribute as the :setting:`ROOT_URLCONF` for the duration of that
    853853test.
    854854
    855855For example::
     
    10741074   :synopsis: Helpers to write custom test runners.
    10751075
    10761076To assist in the creation of your own test runner, Django provides a number of
    1077 utility methods in the ``django.test.utils`` module.
     1077utility methods in the :mod:`django.test.utils` module.
    10781078
    10791079.. function:: setup_test_environment()
    10801080
     
    11091109    Returns the name of the test database that it created.
    11101110
    11111111    ``create_test_db()`` has the side effect of modifying
    1112     ``settings.DATABASE_NAME`` to match the name of the test database.
     1112    :setting:`settings.DATABASE_NAME<DATABASE_NAME>` to match the name of the test database.
    11131113
    11141114    .. versionchanged:: 1.0
    11151115       ``create_test_db()`` now returns the name of the test database.
Back to Top