Ticket #9502: t9502-r9526.diff

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

Patch updated with a few more settings xrefs, applies cleanly to trunk and 1.0.x as of r9526

  • 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  
    138138
    139139This code is straightforward. It imports the settings and checks the value of
    140140the :setting:`DEBUG` setting. If it evaluates to ``True``, then ``site_media``
    141 will be associated with the ``django.views.static.serve`` view. If not, then the
     141will be associated with the :func:`django.views.static.serve` view. If not, then the
    142142view won't be made available.
    143143
    144144Of course, the catch here is that you'll have to remember to set ``DEBUG=False``
  • docs/internals/committers.txt

    diff --git a/docs/internals/committers.txt b/docs/internals/committers.txt
    a b  
    190190    University of Houston who enjoys studying legal topics related to
    191191    intellectual property and spatial law.
    192192   
    193     Justin is the primary developer of ``django.contrib.gis``, a.k.a.
     193    Justin is the primary developer of :mod:`django.contrib.gis`, a.k.a.
    194194    GeoDjango_.
    195195   
    196196.. _GeoDjango: http://geodjango.org/
  • docs/internals/contributing.txt

    diff --git a/docs/internals/contributing.txt b/docs/internals/contributing.txt
    a b  
    752752    ./runtests.py --settings=path.to.django.settings
    753753
    754754Yes, the unit tests need a settings module, but only for database connection
    755 info, with the ``DATABASE_ENGINE`` setting.
     755info, with the :setting:`DATABASE_ENGINE` setting.
    756756
    757757If you're using the ``sqlite3`` database backend, no further settings are
    758758needed. A temporary database will be created in memory when running the tests.
     
    771771
    772772You will also need to ensure that your database uses UTF-8 as the default
    773773character set. If your database server doesn't use UTF-8 as a default charset,
    774 you will need to include a value for ``TEST_DATABASE_CHARSET`` in your settings
     774you will need to include a value for :setting:`TEST_DATABASE_CHARSET` in your settings
    775775file.
    776776
    777777If you want to run the full suite of tests, you'll need to install a number of
  • docs/intro/tutorial01.txt

    diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt
    a b  
    158158     
    159159    * :setting:`DATABASE_NAME` -- The name of your database. If you're using
    160160      SQLite, the database will be a file on your computer; in that case,
    161       ``DATABASE_NAME`` should be the full absolute path, including filename, of
     161      :setting:`DATABASE_NAME` should be the full absolute path, including filename, of
    162162      that file. If the file doesn't exist, it will automatically be created
    163163      when you synchronize the database for the first time (see below).
    164164     
  • docs/misc/api-stability.txt

    diff --git a/docs/misc/api-stability.txt b/docs/misc/api-stability.txt
    a b  
    9696``django.utils``
    9797----------------
    9898
    99 Most of the modules in ``django.utils`` are designed for internal use. Only the following parts of ``django.utils`` can be considered stable:
     99Most of the modules in :mod:`django.utils` are designed for internal use. Only the following parts of :mod:`django.utils` can be considered stable:
    100100
    101     - ``django.utils.cache``
    102     - ``django.utils.datastructures.SortedDict`` -- only this single class; the
     101    - :mod:`django.utils.cache`
     102    - :class:`django.utils.datastructures.SortedDict` -- only this single class; the
    103103      rest of the module is for internal use.
    104     - ``django.utils.encoding``
    105     - ``django.utils.feedgenerator``
    106     - ``django.utils.http``
    107     - ``django.utils.safestring``
    108     - ``django.utils.translation``
    109     - ``django.utils.tzinfo``
     104    - :mod:`django.utils.encoding`
     105    - :mod:`django.utils.feedgenerator`
     106    - :mod:`django.utils.http`
     107    - :mod:`django.utils.safestring`
     108    - :mod:`django.utils.translation`
     109    - :mod:`django.utils.tzinfo`
    110110   
    111111Exceptions
    112112==========
     
    134134``django.contrib.flatpages``, we'll make sure you can still use the Django 1.4
    135135version alongside Django 1.5. This will continue to allow for easy upgrades.
    136136
    137 Historically, apps in ``django.contrib`` have been more stable than the core, so
     137Historically, apps in :mod:`django.contrib` have been more stable than the core, so
    138138in practice we probably won't have to ever make this exception. However, it's
    139 worth noting if you're building apps that depend on ``django.contrib``.
     139worth noting if you're building apps that depend on :mod:`django.contrib`.
    140140
    141141APIs marked as internal
    142142-----------------------
  • docs/misc/design-philosophies.txt

    diff --git a/docs/misc/design-philosophies.txt b/docs/misc/design-philosophies.txt
    a b  
    130130This is why developers need to call ``save()`` explicitly, rather than the
    131131framework saving things behind the scenes silently.
    132132
    133 This is also why the ``select_related()`` ``QuerySet`` method exists. It's an
     133This is also why the ``select_related()`` :class:`QuerySet` method exists. It's an
    134134optional performance booster for the common case of selecting "every related
    135135object."
    136136
  • docs/ref/contrib/admin.txt

    diff --git a/docs/ref/contrib/admin.txt b/docs/ref/contrib/admin.txt
    a b  
    2525
    2626There are five steps in activating the Django admin site:
    2727
    28     1. Add ``django.contrib.admin`` to your ``INSTALLED_APPS`` setting.
     28    1. Add ``django.contrib.admin`` to your :setting:`INSTALLED_APPS` setting.
    2929
    3030    2. Determine which of your application's models should be editable in the
    3131       admin interface.
     
    112112dictionary of information about the fieldset, including a list of fields to be
    113113displayed in it.
    114114
    115 A full example, taken from the ``django.contrib.flatpages.FlatPage`` model::
     115A full example, taken from the :class:`django.contrib.flatpages.FlatPage` model::
    116116
    117117    class FlatPageAdmin(admin.ModelAdmin):
    118118        fieldsets = (
     
    184184Use this option as an alternative to ``fieldsets`` if the layout does not
    185185matter and if you want to only show a subset of the available fields in the
    186186form. For example, you could define a simpler version of the admin form for
    187 the ``django.contrib.flatpages.FlatPage`` model as follows::
     187the :class:`django.contrib.flatpages.FlatPage` model as follows::
    188188
    189189    class FlatPageAdmin(admin.ModelAdmin):
    190190        fields = ('url', 'title', 'content')
     
    411411field should be either a ``BooleanField``, ``CharField``, ``DateField``,
    412412``DateTimeField``, ``IntegerField`` or ``ForeignKey``.
    413413
    414 This example, taken from the ``django.contrib.auth.models.User`` model, shows
     414This example, taken from the :class:`django.contrib.auth.models.User` model, shows
    415415how both ``list_display`` and ``list_filter`` work::
    416416
    417417    class UserAdmin(admin.ModelAdmin):
     
    495495        radio_fields = {"group": admin.VERTICAL}
    496496
    497497You have the choice of using ``HORIZONTAL`` or ``VERTICAL`` from the
    498 ``django.contrib.admin`` module.
     498:mod:`django.contrib.admin` module.
    499499
    500500Don't include a field in ``radio_fields`` unless it's a ``ForeignKey`` or has
    501501``choices`` set.
     
    646646            }
    647647            js = ("my_code.js",)
    648648
    649 Keep in mind that this will be prepended with ``MEDIA_URL``. The same rules
     649Keep in mind that this will be prepended with :setting:`MEDIA_URL`. The same rules
    650650apply as :ref:`regular media definitions on forms <topics-forms-media>`.
    651651
    652652Adding custom validation to the admin
     
    871871
    872872If you want to allow editing and creating ``Image`` instance on the ``Product``
    873873add/change views you can simply use ``GenericInlineModelAdmin`` provided by
    874 ``django.contrib.contenttypes.generic``. In your ``admin.py`` for this
     874:mod:`django.contrib.contenttypes.generic`. In your ``admin.py`` for this
    875875example app::
    876876
    877877    from django.contrib import admin
     
    889889   
    890890    admin.site.register(Product, ProductAdmin)
    891891
    892 ``django.contrib.contenttypes.generic`` provides both a ``GenericTabularInline``
     892:mod:`django.contrib.contenttypes.generic` provides both a ``GenericTabularInline``
    893893and ``GenericStackedInline`` and behave just like any other inline. See the
    894894:ref:`contenttypes documentation <ref-contrib-contenttypes>` for more specific
    895895information.
     
    909909
    910910In order to override one or more of them, first create an ``admin`` directory in
    911911your project's ``templates`` directory. This can be any of the directories you
    912 specified in ``TEMPLATE_DIRS``.
     912specified in :setting:`TEMPLATE_DIRS`.
    913913
    914914Within this ``admin`` directory, create sub-directories named after your app.
    915915Within these app subdirectories create sub-directories named after your models.
     
    998998=====================
    999999
    10001000A Django administrative site is represented by an instance of
    1001 ``django.contrib.admin.sites.AdminSite``; by default, an instance of
     1001:class:`django.contrib.admin.sites.AdminSite`; by default, an instance of
    10021002this class is created as ``django.contrib.admin.site`` and you can
    10031003register your models and ``ModelAdmin`` instances with it.
    10041004
     
    10311031    )
    10321032
    10331033Above we used ``admin.autodiscover()`` to automatically load the
    1034 ``INSTALLED_APPS`` admin.py modules.
     1034:setting:`INSTALLED_APPS` admin.py modules.
    10351035
    10361036In this example, we register the ``AdminSite`` instance
    10371037``myproject.admin.admin_site`` at the URL ``/myadmin/`` ::
  • docs/ref/contrib/comments/settings.txt

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

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

    diff --git a/docs/ref/contrib/localflavor.txt b/docs/ref/contrib/localflavor.txt
    a b  
    6464    * `United Kingdom`_
    6565    * `United States of America`_
    6666
    67 The ``django.contrib.localflavor`` package also includes a ``generic`` subpackage,
     67The :mod:`django.contrib.localflavor` package also includes a ``generic`` subpackage,
    6868containing useful code that is not specific to one particular country or
    6969culture. Currently, it defines date and datetime input fields based on those
    7070from :ref:`forms <topics-forms-index>`, but with non-US default formats.
  • docs/ref/contrib/webdesign.txt

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

    diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt
    a b  
    173173       :setting:`DATABASE_PORT`
    174174    3. MySQL option files.
    175175
    176 In other words, if you set the name of the database in ``DATABASE_OPTIONS``,
    177 this will take precedence over ``DATABASE_NAME``, which would override
     176In other words, if you set the name of the database in :setting:`DATABASE_OPTIONS`,
     177this will take precedence over :setting:`DATABASE_NAME`, which would override
    178178anything in a `MySQL option file`_.
    179179
    180180Here's a sample configuration which uses a MySQL option file::
  • docs/ref/django-admin.txt

    diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
    a b  
    5959---------
    6060
    6161Many subcommands take a list of "app names." An "app name" is the basename of
    62 the package containing your models. For example, if your ``INSTALLED_APPS``
     62the package containing your models. For example, if your :setting:`INSTALLED_APPS`
    6363contains the string ``'mysite.blog'``, the app name is ``blog``.
    6464
    6565Determining the version
     
    148148it when running interactively.
    149149
    150150This command is only available if Django's :ref:`authentication system
    151 <topics-auth>` (``django.contrib.auth``) is installed.
     151<topics-auth>` (:mod:`django.contrib.auth`) is installed.
    152152
    153153dbshell
    154154-------
     
    156156.. django-admin:: dbshell
    157157
    158158Runs the command-line client for the database engine specified in your
    159 ``DATABASE_ENGINE`` setting, with the connection parameters specified in your
    160 ``DATABASE_USER``, ``DATABASE_PASSWORD``, etc., settings.
     159:setting:`DATABASE_ENGINE` setting, with the connection parameters specified in your
     160:setting:`DATABASE_USER`, :setting:`DATABASE_PASSWORD`, etc., settings.
    161161
    162162    * For PostgreSQL, this runs the ``psql`` command-line client.
    163163    * For MySQL, this runs the ``mysql`` command-line client.
     
    177177settings.
    178178
    179179Settings that don't appear in the defaults are followed by ``"###"``. For
    180 example, the default settings don't define ``ROOT_URLCONF``, so
     180example, the default settings don't define :setting:`ROOT_URLCONF`, so
    181181``ROOT_URLCONF`` is followed by ``"###"`` in the output of ``diffsettings``.
    182182
    183183Note that Django's default settings live in ``django/conf/global_settings.py``,
     
    248248---------
    249249
    250250Introspects the database tables in the database pointed-to by the
    251 ``DATABASE_NAME`` setting and outputs a Django model module (a ``models.py``
     251:setting:`DATABASE_NAME` setting and outputs a Django model module (a ``models.py``
    252252file) to standard output.
    253253
    254254Use this if you have a legacy database with which you'd like to use Django.
     
    297297Django will search in three locations for fixtures:
    298298
    299299   1. In the ``fixtures`` directory of every installed application
    300    2. In any directory named in the ``FIXTURE_DIRS`` setting
     300   2. In any directory named in the :setting:`FIXTURE_DIRS` setting
    301301   3. In the literal path named by the fixture
    302302
    303303Django will load any and all fixtures it finds in these locations that match
     
    332332
    333333would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed
    334334application,  ``<dirname>/foo/bar/mydata.json`` for each directory in
    335 ``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``.
     335:setting:`FIXTURE_DIRS`, and the literal path ``foo/bar/mydata.json``.
    336336
    337337Note that the order in which fixture files are processed is undefined. However,
    338338all fixture data is installed as a single transaction, so data in
     
    509509~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    510510
    511511By default, the development server doesn't serve any static files for your site
    512 (such as CSS files, images, things under ``MEDIA_URL`` and so forth). If
     512(such as CSS files, images, things under :setting:`MEDIA_URL` and so forth). If
    513513you want to configure Django to serve static media, read :ref:`howto-static-files`.
    514514
    515515Turning off auto-reload
     
    613613syncdb
    614614------
    615615
    616 Creates the database tables for all apps in ``INSTALLED_APPS`` whose tables
     616Creates the database tables for all apps in :setting:`INSTALLED_APPS` whose tables
    617617have not already been created.
    618618
    619619Use this command when you've added new applications to your project and want to
    620620install them in the database. This includes any apps shipped with Django that
    621 might be in ``INSTALLED_APPS`` by default. When you start a new project, run
     621might be in :setting:`INSTALLED_APPS` by default. When you start a new project, run
    622622this command to install the default apps.
    623623
    624624.. admonition:: Syncdb will not alter existing tables
     
    634634   to match, use the ``sql`` command to display the new SQL structure and
    635635   compare that to your existing table schema to work out the changes.
    636636
    637 If you're installing the ``django.contrib.auth`` application, ``syncdb`` will
     637If you're installing the :mod:`django.contrib.auth` application, ``syncdb`` will
    638638give you the option of creating a superuser immediately.
    639639
    640640``syncdb`` will also search for and install any fixture named ``initial_data``
     
    725725validate
    726726--------
    727727
    728 Validates all installed models (according to the ``INSTALLED_APPS`` setting)
     728Validates all installed models (according to the :setting:`INSTALLED_APPS` setting)
    729729and prints validation errors to standard output.
    730730
    731731Default 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
     
    175175      page. This lets you override the default template name (see below).
    176176
    177177    * ``template_loader``: The template loader to use when loading the
    178       template. By default, it's ``django.template.loader``.
     178      template. By default, it's :mod:`django.template.loader`.
    179179
    180180    * ``extra_context``: A dictionary of values to add to the template
    181181      context. By default, this is an empty dictionary. If a value in the
     
    191191      the view's template.
    192192
    193193    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    194       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     194      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    195195
    196196    * ``allow_future``: A boolean specifying whether to include "future"
    197197      objects on this page, where "future" means objects in which the field
     
    260260      page. This lets you override the default template name (see below).
    261261
    262262    * ``template_loader``: The template loader to use when loading the
    263       template. By default, it's ``django.template.loader``.
     263      template. By default, it's :mod:`django.template.loader`.
    264264
    265265    * ``extra_context``: A dictionary of values to add to the template
    266266      context. By default, this is an empty dictionary. If a value in the
     
    288288      this is ``False``.
    289289
    290290    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    291       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     291      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    292292
    293293    * ``allow_future``: A boolean specifying whether to include "future"
    294294      objects on this page, where "future" means objects in which the field
     
    354354      page. This lets you override the default template name (see below).
    355355
    356356    * ``template_loader``: The template loader to use when loading the
    357       template. By default, it's ``django.template.loader``.
     357      template. By default, it's :mod:`django.template.loader`.
    358358
    359359    * ``extra_context``: A dictionary of values to add to the template
    360360      context. By default, this is an empty dictionary. If a value in the
     
    375375      determining the variable's name.
    376376
    377377    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    378       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     378      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    379379
    380380    * ``allow_future``: A boolean specifying whether to include "future"
    381381      objects on this page, where "future" means objects in which the field
     
    435435      page. This lets you override the default template name (see below).
    436436
    437437    * ``template_loader``: The template loader to use when loading the
    438       template. By default, it's ``django.template.loader``.
     438      template. By default, it's :mod:`django.template.loader`.
    439439
    440440    * ``extra_context``: A dictionary of values to add to the template
    441441      context. By default, this is an empty dictionary. If a value in the
     
    456456      determining the variable's name.
    457457
    458458    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    459       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     459      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    460460
    461461    * ``allow_future``: A boolean specifying whether to include "future"
    462462      objects on this page, where "future" means objects in which the field
     
    520520      page. This lets you override the default template name (see below).
    521521
    522522    * ``template_loader``: The template loader to use when loading the
    523       template. By default, it's ``django.template.loader``.
     523      template. By default, it's :mod:`django.template.loader`.
    524524
    525525    * ``extra_context``: A dictionary of values to add to the template
    526526      context. By default, this is an empty dictionary. If a value in the
     
    541541      determining the variable's name.
    542542
    543543    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    544       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     544      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    545545
    546546    * ``allow_future``: A boolean specifying whether to include "future"
    547547      objects on this page, where "future" means objects in which the field
     
    637637      It's a bit of a brain-bender, but it's useful in some cases.
    638638
    639639    * ``template_loader``: The template loader to use when loading the
    640       template. By default, it's ``django.template.loader``.
     640      template. By default, it's :mod:`django.template.loader`.
    641641
    642642    * ``extra_context``: A dictionary of values to add to the template
    643643      context. By default, this is an empty dictionary. If a value in the
     
    651651      to use in the template context. By default, this is ``'object'``.
    652652
    653653    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    654       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     654      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    655655
    656656    * ``allow_future``: A boolean specifying whether to include "future"
    657657      objects on this page, where "future" means objects in which the field
     
    706706      page. This lets you override the default template name (see below).
    707707
    708708    * ``template_loader``: The template loader to use when loading the
    709       template. By default, it's ``django.template.loader``.
     709      template. By default, it's :mod:`django.template.loader`.
    710710
    711711    * ``extra_context``: A dictionary of values to add to the template
    712712      context. By default, this is an empty dictionary. If a value in the
     
    727727      determining the variable's name.
    728728
    729729    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    730       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     730      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    731731
    732732**Template name:**
    733733
     
    832832      It's a bit of a brain-bender, but it's useful in some cases.
    833833
    834834    * ``template_loader``: The template loader to use when loading the
    835       template. By default, it's ``django.template.loader``.
     835      template. By default, it's :mod:`django.template.loader`.
    836836
    837837    * ``extra_context``: A dictionary of values to add to the template
    838838      context. By default, this is an empty dictionary. If a value in the
     
    846846      to use in the template context. By default, this is ``'object'``.
    847847
    848848    * ``mimetype``: The MIME type to use for the resulting document. Defaults
    849       to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
     849      to the value of the :setting:`DEFAULT_CONTENT_TYPE` setting.
    850850
    851851**Template name:**
    852852
     
    915915      page. This lets you override the default template name (see below).
    916916
    917917    * ``template_loader``: The template loader to use when loading the
    918       template. By default, it's ``django.template.loader``.
     918      template. By default, it's :mod:`django.template.loader`.
    919919
    920920    * ``extra_context``: A dictionary of values to add to the template
    921921      context. By default, this is an empty dictionary. If a value in the
     
    10001000      page. This lets you override the default template name (see below).
    10011001
    10021002    * ``template_loader``: The template loader to use when loading the
    1003       template. By default, it's ``django.template.loader``.
     1003      template. By default, it's :mod:`django.template.loader`.
    10041004
    10051005    * ``extra_context``: A dictionary of values to add to the template
    10061006      context. By default, this is an empty dictionary. If a value in the
     
    10821082      page. This lets you override the default template name (see below).
    10831083
    10841084    * ``template_loader``: The template loader to use when loading the
    1085       template. By default, it's ``django.template.loader``.
     1085      template. By default, it's :mod:`django.template.loader`.
    10861086
    10871087    * ``extra_context``: A dictionary of values to add to the template
    10881088      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.
     
    144144
    145145.. attribute:: HttpRequest.user
    146146
    147     A ``django.contrib.auth.models.User`` object representing the currently
     147    A :class:`django.contrib.auth.models.User` object representing the currently
    148148    logged-in user. If the user isn't currently logged in, ``user`` will be set
    149     to an instance of ``django.contrib.auth.models.AnonymousUser``. You
    150     can tell them apart with ``is_authenticated()``, like so::
     149    to an instance of :class:`django.contrib.auth.models.AnonymousUser`. You
     150    can tell them apart with :meth:`is_authenticated`, like so::
    151151
    152152        if request.user.is_authenticated():
    153153            # Do something for logged-in users.
     
    174174
    175175    Not defined by Django itself, but will be read if other code (e.g., a custom
    176176    middleware class) sets it. When present, this will be used as the root
    177     URLconf for the current request, overriding the ``ROOT_URLCONF`` setting.
     177    URLconf for the current request, overriding the :setting:`ROOT_URLCONF` setting.
    178178    See :ref:`how-django-processes-a-request` for details.
    179179
    180180Methods
     
    242242.. class:: QueryDict
    243243
    244244In an :class:`HttpRequest` object, the ``GET`` and ``POST`` attributes are instances
    245 of ``django.http.QueryDict``. :class:`QueryDict` is a dictionary-like
     245of ``django.http.QueryDict``. ``QueryDict`` is a dictionary-like
    246246class customized to deal with multiple values for the same key. This is
    247247necessary because some HTML form elements, notably
    248248``<select multiple="multiple">``, pass multiple values for the same key.
     
    254254Methods
    255255-------
    256256
    257 :class:`QueryDict` implements all the standard dictionary methods, because it's
     257``QueryDict`` implements all the standard dictionary methods, because it's
    258258a subclass of dictionary. Exceptions are outlined here:
    259259
    260260.. method:: QueryDict.__getitem__(key)
     
    287287    Just like the standard dictionary ``setdefault()`` method, except it uses
    288288    ``__setitem__`` internally.
    289289
    290 .. method:: QueryDict.update(other_dict) 
     290.. method:: QueryDict.update(other_dict)
    291291
    292292    Takes either a ``QueryDict`` or standard dictionary. Just like the standard
    293293    dictionary ``update()`` method, except it *appends* to the current
     
    350350
    351351    Like :meth:`items()`, except it includes all values, as a list, for each
    352352    member of the dictionary. For example::
    353    
     353
    354354         >>> q = QueryDict('a=1&a=2&a=3')
    355355         >>> q.lists()
    356356         [('a', ['1', '2', '3'])]
    357    
     357
    358358.. method:: QueryDict.urlencode()
    359359
    360360    Returns a string of the data in query-string format.
     
    366366.. class:: HttpResponse
    367367
    368368In contrast to :class:`HttpRequest` objects, which are created automatically by
    369 Django, :class:`HttpResponse` objects are your responsibility. Each view you
     369Django, ``HttpResponse`` objects are your responsibility. Each view you
    370370write is responsible for instantiating, populating and returning an
    371 :class:`HttpResponse`.
     371``HttpResponse``.
    372372
    373 The :class:`HttpResponse` class lives in the ``django.http`` module.
     373The ``HttpResponse`` class lives in the :mod:`django.http` module.
    374374
    375375Usage
    376376-----
     
    379379~~~~~~~~~~~~~~~
    380380
    381381Typical usage is to pass the contents of the page, as a string, to the
    382 :class:`HttpResponse` constructor::
     382``HttpResponse`` constructor::
    383383
    384384    >>> response = HttpResponse("Here's the text of the Web page.")
    385385    >>> response = HttpResponse("Text only, please.", mimetype="text/plain")
     
    408408hard-coded strings. If you use this technique, follow these guidelines:
    409409
    410410    * The iterator should return strings.
    411     * If an :class:`HttpResponse` has been initialized with an iterator as its
    412       content, you can't use the class:`HttpResponse` instance as a file-like
     411    * If an ``HttpResponse`` has been initialized with an iterator as its
     412      content, you can't use the ``HttpResponse`` instance as a file-like
    413413      object. Doing so will raise ``Exception``.
    414414
    415415Setting headers
     
    445445-------
    446446
    447447.. method:: HttpResponse.__init__(content='', mimetype=None, status=200, content_type=DEFAULT_CONTENT_TYPE)
    448    
     448
    449449    Instantiates an ``HttpResponse`` object with the given page content (a
    450     string) and MIME type. The ``DEFAULT_CONTENT_TYPE`` is ``'text/html'``.
     450    string) and MIME type. The :setting:`DEFAULT_CONTENT_TYPE` is ``'text/html'``.
    451451
    452452    ``content`` can be an iterator or a string. If it's an iterator, it should
    453453    return strings, and those strings will be joined together to form the
     
    463463    encoding, which makes it more than just a MIME type specification.
    464464    If ``mimetype`` is specified (not ``None``), that value is used.
    465465    Otherwise, ``content_type`` is used. If neither is given, the
    466     ``DEFAULT_CONTENT_TYPE`` setting is used.
     466    :setting:`DEFAULT_CONTENT_TYPE` setting is used.
    467467
    468468.. method:: HttpResponse.__setitem__(header, value)
    469469
     
    512512
    513513.. method:: HttpResponse.write(content)
    514514
    515     This method makes an :class:`HttpResponse` instance a file-like object.
     515    This method makes an ``HttpResponse`` instance a file-like object.
    516516
    517517.. method:: HttpResponse.flush()
    518518
    519     This method makes an :class:`HttpResponse` instance a file-like object.
     519    This method makes an ``HttpResponse`` instance a file-like object.
    520520
    521521.. method:: HttpResponse.tell()
    522522
    523     This method makes an :class:`HttpResponse` instance a file-like object.
     523    This method makes an ``HttpResponse`` instance a file-like object.
    524524
    525525.. _HTTP Status code: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10
    526526
     
    530530HttpResponse subclasses
    531531-----------------------
    532532
    533 Django includes a number of ``HttpResponse`` subclasses that handle different
     533Django includes a number of :class:`HttpResponse` subclasses that handle different
    534534types of HTTP responses. Like ``HttpResponse``, these subclasses live in
    535535:mod:`django.http`.
    536536
  • 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``.
     
    665665
    666666.. function:: views.login()
    667667
    668     Here's what ``django.contrib.auth.views.login`` does:
     668    Here's what :func:`django.contrib.auth.views.login` does:
    669669
    670670        * If called via ``GET``, it displays a login form that POSTs to the same
    671671          URL. More on this in a bit.
     
    985985Default permissions
    986986-------------------
    987987
    988 When ``django.contrib.auth`` is listed in your :setting:`INSTALLED_APPS`
     988When :mod:`django.contrib.auth` is listed in your :setting:`INSTALLED_APPS`
    989989setting, it will ensure that three default permissions -- add, change
    990990and delete -- are created for each Django model defined in one of your
    991991installed applications.
    992992
    993993These permissions will be created when you run
    994994:djadmin:`manage.py syncdb <syncdb>`; the first time you run ``syncdb`` after
    995 adding ``django.contrib.auth`` to :setting:`INSTALLED_APPS`, the default
     995adding :mod:`django.contrib.auth` to :setting:`INSTALLED_APPS`, the default
    996996permissions will be created for all previously-installed models, as well as
    997997for any new models being installed at that time. Afterward, it will create
    998998default 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
     
    247247entire site. You'll need to add
    248248``'django.middleware.cache.UpdateCacheMiddleware'`` and
    249249``'django.middleware.cache.FetchFromCacheMiddleware'`` to your
    250 ``MIDDLEWARE_CLASSES`` setting, as in this example::
     250:setting:`MIDDLEWARE_CLASSES` setting, as in this example::
    251251
    252252    MIDDLEWARE_CLASSES = (
    253253        'django.middleware.cache.UpdateCacheMiddleware',
     
    263263
    264264Then, add the following required settings to your Django settings file:
    265265
    266 * ``CACHE_MIDDLEWARE_SECONDS`` -- The number of seconds each page should be
     266* :setting:`CACHE_MIDDLEWARE_SECONDS` -- The number of seconds each page should be
    267267  cached.
    268 * ``CACHE_MIDDLEWARE_KEY_PREFIX`` -- If the cache is shared across multiple
     268* :setting:`CACHE_MIDDLEWARE_KEY_PREFIX` -- If the cache is shared across multiple
    269269  sites using the same Django installation, set this to the name of the site,
    270270  or some other string that is unique to this Django instance, to prevent key
    271271  collisions. Use an empty string if you don't care.
    272272
    273273The cache middleware caches every page that doesn't have GET or POST
    274 parameters. Optionally, if the ``CACHE_MIDDLEWARE_ANONYMOUS_ONLY`` setting is
     274parameters. Optionally, if the :setting:`CACHE_MIDDLEWARE_ANONYMOUS_ONLY` setting is
    275275``True``, only anonymous requests (i.e., not those made by a logged-in user)
    276276will be cached. This is a simple and effective way of disabling caching for any
    277277user-specific pages (include Django's admin interface). Note that if you use
    278 ``CACHE_MIDDLEWARE_ANONYMOUS_ONLY``, you should make sure you've activated
     278:setting:`CACHE_MIDDLEWARE_ANONYMOUS_ONLY`, you should make sure you've activated
    279279``AuthenticationMiddleware``.
    280280
    281281Additionally, the cache middleware automatically sets a few headers in each
     
    284284* Sets the ``Last-Modified`` header to the current date/time when a fresh
    285285  (uncached) version of the page is requested.
    286286* Sets the ``Expires`` header to the current date/time plus the defined
    287   ``CACHE_MIDDLEWARE_SECONDS``.
     287  :setting:`CACHE_MIDDLEWARE_SECONDS`.
    288288* Sets the ``Cache-Control`` header to give a max age for the page -- again,
    289   from the ``CACHE_MIDDLEWARE_SECONDS`` setting.
     289  from the :setting:`CACHE_MIDDLEWARE_SECONDS` setting.
    290290
    291291See :ref:`topics-http-middleware` for more on middleware.
    292292
     
    294294
    295295If a view sets its own cache expiry time (i.e. it has a ``max-age`` section in
    296296its ``Cache-Control`` header) then the page will be cached until the expiry
    297 time, rather than ``CACHE_MIDDLEWARE_SECONDS``. Using the decorators in
    298 ``django.views.decorators.cache`` you can easily set a view's expiry time
     297time, rather than :setting:`CACHE_MIDDLEWARE_SECONDS`. Using the decorators in
     298:mod:`django.views.decorators.cache` you can easily set a view's expiry time
    299299(using the ``cache_control`` decorator) or disable caching for a view (using
    300300the ``never_cache`` decorator). See the `using other headers`__ section for
    301301more on these decorators.
     
    306306==================
    307307
    308308A more granular way to use the caching framework is by caching the output of
    309 individual views. ``django.views.decorators.cache`` defines a ``cache_page``
     309individual views. :mod:`django.views.decorators.cache` defines a ``cache_page``
    310310decorator that will automatically cache the view's response for you. It's easy
    311311to use::
    312312
     
    378378intensive database query. In cases like this, you can use the low-level cache
    379379API to store objects in the cache with any level of granularity you like.
    380380
    381 The cache API is simple. The cache module, ``django.core.cache``, exports a
    382 ``cache`` object that's automatically created from the ``CACHE_BACKEND``
     381The cache API is simple. The cache module, :mod:`django.core.cache`, exports a
     382``cache`` object that's automatically created from the :setting:`CACHE_BACKEND`
    383383setting::
    384384
    385385    >>> from django.core.cache import cache
     
    391391    'hello, world!'
    392392
    393393The ``timeout_seconds`` argument is optional and defaults to the ``timeout``
    394 argument in the ``CACHE_BACKEND`` setting (explained above).
     394argument in the :setting:`CACHE_BACKEND` setting (explained above).
    395395
    396396If the object doesn't exist in the cache, ``cache.get()`` returns ``None``::
    397397
     
    617617For explanation of Cache-Control HTTP directives, see the `Cache-Control spec`_.
    618618
    619619(Note that the caching middleware already sets the cache header's max-age with
    620 the value of the ``CACHE_MIDDLEWARE_SETTINGS`` setting. If you use a custom
     620the value of the :setting:`CACHE_MIDDLEWARE_SETTINGS` setting. If you use a custom
    621621``max_age`` in a ``cache_control`` decorator, the decorator will take
    622622precedence, and the header values will be merged correctly.)
    623623
     
    649649===========================
    650650
    651651If you use caching middleware, it's important to put each half in the right
    652 place within the ``MIDDLEWARE_CLASSES`` setting. That's because the cache
     652place within the :setting:`MIDDLEWARE_CLASSES` setting. That's because the cache
    653653middleware needs to know which headers by which to vary the cache storage.
    654654Middleware always adds something to the ``Vary`` response header when it can.
    655655
  • 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()
     
    781781
    782782Converting a normal ``unittest.TestCase`` to a Django ``TestCase`` is easy:
    783783just change the base class of your test from ``unittest.TestCase`` to
    784 ``django.test.TestCase``. All of the standard Python unit test functionality
     784:class:`django.test.TestCase`. All of the standard Python unit test functionality
    785785will continue to be available, but it will be augmented with some useful
    786786additions.
    787787
     
    792792
    793793.. attribute:: TestCase.client
    794794
    795 Every test case in a ``django.test.TestCase`` instance has access to an
     795Every test case in a :class:`django.test.TestCase` instance has access to an
    796796instance of a Django test client. This client can be accessed as
    797797``self.client``. This client is recreated for each test, so you don't have to
    798798worry about state (such as cookies) carrying over from one test to another.
     
    857857
    858858Once you've created a fixture and placed it somewhere in your Django project,
    859859you can use it in your unit tests by specifying a ``fixtures`` class attribute
    860 on your ``django.test.TestCase`` subclass::
     860on your :class:`django.test.TestCase` subclass::
    861861
    862862    from django.test import TestCase
    863863    from myapp.models import Animal
     
    900900particular URL.
    901901
    902902In order to provide a reliable URL space for your test,
    903 ``django.test.TestCase`` provides the ability to customize the URLconf
     903:class:`django.test.TestCase` provides the ability to customize the URLconf
    904904configuration for the duration of the execution of a test suite. If your
    905905``TestCase`` instance defines an ``urls`` attribute, the ``TestCase`` will use
    906 the value of that attribute as the ``ROOT_URLCONF`` for the duration of that
     906the value of that attribute as the :setting:`ROOT_URLCONF` for the duration of that
    907907test.
    908908
    909909For example::
     
    11281128   :synopsis: Helpers to write custom test runners.
    11291129
    11301130To assist in the creation of your own test runner, Django provides a number of
    1131 utility methods in the ``django.test.utils`` module.
     1131utility methods in the :mod:`django.test.utils` module.
    11321132
    11331133.. function:: setup_test_environment()
    11341134
     
    11631163    Returns the name of the test database that it created.
    11641164
    11651165    ``create_test_db()`` has the side effect of modifying
    1166     ``settings.DATABASE_NAME`` to match the name of the test database.
     1166    :setting:`settings.DATABASE_NAME<DATABASE_NAME>` to match the name of the test database.
    11671167
    11681168    .. versionchanged:: 1.0
    11691169       ``create_test_db()`` now returns the name of the test database.
Back to Top