Code

Ticket #16586: 16586.3.patch

File 16586.3.patch, 78.4 KB (added by aaugustin, 3 years ago)
  • docs/glossary.txt

     
    4343 
    4444    property 
    4545        Also known as "managed attributes", and a feature of Python since 
    46         version 2.2. From `the property documentation`__: 
     46        version 2.2. This is a neat way to implement attributes whose usage 
     47        resembles attribute access, but whose implementation uses method calls. 
    4748 
    48             Properties are a neat way to implement attributes whose usage 
    49             resembles attribute access, but whose implementation uses method 
    50             calls. [...] You 
    51             could only do this by overriding ``__getattr__`` and 
    52             ``__setattr__``; but overriding ``__setattr__`` slows down all 
    53             attribute assignments considerably, and overriding ``__getattr__`` 
    54             is always a bit tricky to get right. Properties let you do this 
    55             painlessly, without having to override ``__getattr__`` or 
    56             ``__setattr__``. 
     49        See :func:`property`. 
    5750 
    58         __ http://www.python.org/download/releases/2.2/descrintro/#property 
    59  
    6051    queryset 
    6152        An object representing some set of rows to be fetched from the database. 
    6253 
  • docs/misc/design-philosophies.txt

     
    7373Explicit is better than implicit 
    7474-------------------------------- 
    7575 
    76 This, a `core Python principle`_, means Django shouldn't do too much "magic." 
    77 Magic shouldn't happen unless there's a really good reason for it. Magic is 
    78 worth using only if it creates a huge convenience unattainable in other ways, 
    79 and it isn't implemented in a way that confuses developers who are trying to 
    80 learn how to use the feature. 
     76This is a core Python principle listed in :pep:`20`, and it means Django 
     77shouldn't do too much "magic." Magic shouldn't happen unless there's a really 
     78good reason for it. Magic is worth using only if it creates a huge convenience 
     79unattainable in other ways, and it isn't implemented in a way that confuses 
     80developers who are trying to learn how to use the feature. 
    8181 
    82 .. _`core Python principle`: http://www.python.org/dev/peps/pep-0020/ 
    83  
    8482.. _consistency: 
    8583 
    8684Consistency 
  • docs/intro/tutorial03.txt

     
    122122``http://www.example.com/myapp/?page=3``, the URLconf will look for ``myapp/``. 
    123123 
    124124If you need help with regular expressions, see `Wikipedia's entry`_ and the 
    125 `Python documentation`_. Also, the O'Reilly book "Mastering Regular Expressions" 
    126 by Jeffrey Friedl is fantastic. 
     125documentation of the :mod:`re` module. Also, the O'Reilly book "Mastering 
     126Regular Expressions" by Jeffrey Friedl is fantastic. 
    127127 
    128128Finally, a performance note: these regular expressions are compiled the first 
    129129time the URLconf module is loaded. They're super fast. 
    130130 
    131131.. _Wikipedia's entry: http://en.wikipedia.org/wiki/Regular_expression 
    132 .. _Python documentation: http://docs.python.org/library/re.html 
    133132 
    134133Write your first view 
    135134===================== 
  • docs/internals/contributing/writing-documentation.txt

     
    4343Then, building the HTML is easy; just ``make html`` (or ``make.bat html`` on 
    4444Windows) from the ``docs`` directory. 
    4545 
    46 To get started contributing, you'll want to read the `reStructuredText 
    47 Primer`__. After that, you'll want to read about the `Sphinx-specific markup`__ 
    48 that's used to manage metadata, indexing, and cross-references. 
     46To get started contributing, you'll want to read the :ref:`reStructuredText 
     47Primer <sphinx:rst-primer>`. After that, you'll want to read about the 
     48:ref:`Sphinx-specific markup <sphinx:sphinxmarkup>` that's used to manage 
     49metadata, indexing, and cross-references. 
    4950 
    50 __ http://sphinx.pocoo.org/rest.html 
    51 __ http://sphinx.pocoo.org/markup/ 
    52  
    5351Commonly used terms 
    5452------------------- 
    5553 
     
    113111      greatly helps readers. There's basically no limit to the amount of 
    114112      useful markup you can add. 
    115113 
     114    * Use :mod:`~sphinx.ext.intersphinx` to reference Python's and Sphinx' 
     115      documentation. 
     116 
    116117Django-specific markup 
    117118---------------------- 
    118119 
     
    220221        You can find both in the :doc:`settings reference document 
    221222        </ref/settings>`. 
    222223 
    223       We use the Sphinx doc_ cross reference element when we want to link to 
    224       another document as a whole and the ref_ element when we want to link to 
    225       an arbitrary location in a document. 
     224      We use the Sphinx :rst:role:`doc` cross reference element when we want to 
     225      link to another document as a whole and the :rst:role:`ref` element when 
     226      we want to link to an arbitrary location in a document. 
    226227 
    227 .. _doc: http://sphinx.pocoo.org/markup/inline.html#role-doc 
    228 .. _ref: http://sphinx.pocoo.org/markup/inline.html#role-ref 
    229  
    230228    * Next, notice how the settings are annotated: 
    231229 
    232230      .. code-block:: rst 
  • docs/internals/contributing/writing-code/coding-style.txt

     
    1010    * Unless otherwise specified, follow :pep:`8`. 
    1111 
    1212      You could use a tool like `pep8`_ to check for some problems in this 
    13       area, but remember that PEP 8 is only a guide, so respect the style of 
     13      area, but remember that :pep:`8` is only a guide, so respect the style of 
    1414      the surrounding code as a primary goal. 
    1515 
    1616    * Use four spaces for indentation. 
  • docs/internals/contributing/writing-code/branch-policy.txt

     
    146146location of the branch's ``django`` package. If you want to switch back, just 
    147147change the symlink to point to the old code. 
    148148 
    149 A third option is to use a `path file`_ (``<something>.pth``). First, make sure 
    150 there are no files, directories or symlinks named ``django`` in your 
    151 ``site-packages`` directory. Then create a text file named ``django.pth`` and 
    152 save it to your ``site-packages`` directory. That file should contain a path to 
    153 your copy of Django on a single line and optional comments. Here is an example 
    154 that points to multiple branches. Just uncomment the line for the branch you 
    155 want to use ('Trunk' in this example) and make sure all other lines are 
    156 commented:: 
     149A third option is to use a path file (``<something>.pth``). This is a feature of 
     150the :mod:`site` module. First, make sure there are no files, directories or 
     151symlinks named ``django`` in your ``site-packages`` directory. Then create a 
     152text file named ``django.pth`` and save it to your ``site-packages`` directory. 
     153That file should contain a path to your copy of Django on a single line and 
     154optional comments. Here is an example that points to multiple branches. Just 
     155uncomment the line for the branch you want to use ('trunk' in this example) and 
     156make sure all other lines are commented:: 
    157157 
    158158    # Trunk is a svn checkout of: 
    159159    #   http://code.djangoproject.com/svn/django/trunk/ 
     
    168168    # On windows a path may look like this: 
    169169    # C:/path/to/<branch> 
    170170 
    171 .. _path file: http://docs.python.org/library/site.html 
    172171.. _django-developers: http://groups.google.com/group/django-developers 
  • docs/howto/deployment/modwsgi.txt

     
    99.. _mod_wsgi: http://code.google.com/p/modwsgi/ 
    1010 
    1111mod_wsgi is an Apache module which can be used to host any Python application 
    12 which supports the `Python WSGI interface`_, including Django. Django will work 
    13 with any version of Apache which supports mod_wsgi. 
     12which supports the Python WSGI interface described in :pep:`3333`, including 
     13Django. Django will work with any version of Apache which supports mod_wsgi. 
    1414 
    15 .. _python wsgi interface: http://www.python.org/dev/peps/pep-0333/ 
    16  
    1715The `official mod_wsgi documentation`_ is fantastic; it's your source for all 
    1816the details about how to use mod_wsgi. You'll probably want to start with the 
    1917`installation and configuration documentation`_. 
  • docs/howto/outputting-csv.txt

     
    33========================== 
    44 
    55This document explains how to output CSV (Comma Separated Values) dynamically 
    6 using Django views. To do this, you can either use the `Python CSV library`_ or 
    7 the Django template system. 
     6using Django views. To do this, you can either use the Python CSV library or the 
     7Django template system. 
    88 
    9 .. _Python CSV library: http://docs.python.org/library/csv.html 
    10  
    119Using the Python CSV library 
    1210============================ 
    1311 
    14 Python comes with a CSV library, ``csv``. The key to using it with Django is 
    15 that the ``csv`` module's CSV-creation capability acts on file-like objects, and 
    16 Django's :class:`~django.http.HttpResponse` objects are file-like objects. 
     12Python comes with a CSV library, :mod:`csv`. The key to using it with Django is 
     13that the :mod:`csv` module's CSV-creation capability acts on file-like objects, 
     14and Django's :class:`~django.http.HttpResponse` objects are file-like objects. 
    1715 
    1816Here's an example:: 
    1917 
     
    3432The code and comments should be self-explanatory, but a few things deserve a 
    3533mention: 
    3634 
    37     * The response gets a special MIME type, ``text/csv``. This tells 
     35    * The response gets a special MIME type, :mimetype:`text/csv`. This tells 
    3836      browsers that the document is a CSV file, rather than an HTML file. If 
    3937      you leave this off, browsers will probably interpret the output as HTML, 
    4038      which will result in ugly, scary gobbledygook in the browser window. 
     
    5957Handling Unicode 
    6058~~~~~~~~~~~~~~~~ 
    6159 
    62 Python's ``csv`` module does not support Unicode input. Since Django uses 
     60Python's :mod:`csv` module does not support Unicode input. Since Django uses 
    6361Unicode internally this means strings read from sources such as 
    6462:class:`~django.http.HttpRequest` are potentially problematic. There are a few 
    6563options for handling this: 
     
    7068      section`_. 
    7169 
    7270    * Use the `python-unicodecsv module`_, which aims to be a drop-in 
    73       replacement for ``csv`` that gracefully handles Unicode. 
     71      replacement for :mod:`csv` that gracefully handles Unicode. 
    7472 
    75 For more information, see the Python `CSV File Reading and Writing`_ 
    76 documentation. 
     73For more information, see the Python documentation of the :mod:`csv` module. 
    7774 
    7875.. _`csv module's examples section`: http://docs.python.org/library/csv.html#examples 
    7976.. _`python-unicodecsv module`: https://github.com/jdunck/python-unicodecsv 
    80 .. _`CSV File Reading and Writing`: http://docs.python.org/library/csv.html 
    8177 
    8278Using the template system 
    8379========================= 
    8480 
    8581Alternatively, you can use the :doc:`Django template system </topics/templates>` 
    86 to generate CSV. This is lower-level than using the convenient Python ``csv`` 
     82to generate CSV. This is lower-level than using the convenient Python :mod:`csv` 
    8783module, but the solution is presented here for completeness. 
    8884 
    8985The idea here is to pass a list of items to your template, and have the 
  • docs/howto/custom-template-tags.txt

     
    335335 
    336336For example, let's write a template tag, ``{% current_time %}``, that displays 
    337337the current date/time, formatted according to a parameter given in the tag, in 
    338 `strftime syntax`_. It's a good idea to decide the tag syntax before anything 
    339 else. In our case, let's say the tag should be used like this: 
     338:func:`~time.strftime` syntax. It's a good idea to decide the tag syntax before 
     339anything else. In our case, let's say the tag should be used like this: 
    340340 
    341341.. code-block:: html+django 
    342342 
    343343    <p>The time is {% current_time "%Y-%m-%d %I:%M %p" %}.</p> 
    344344 
    345 .. _`strftime syntax`: http://docs.python.org/library/time.html#time.strftime 
    346  
    347345The parser for this function should grab the parameter and create a ``Node`` 
    348346object:: 
    349347 
  • docs/howto/outputting-pdf.txt

     
    6363The code and comments should be self-explanatory, but a few things deserve a 
    6464mention: 
    6565 
    66     * The response gets a special MIME type, ``application/pdf``. This tells 
    67       browsers that the document is a PDF file, rather than an HTML file. If 
    68       you leave this off, browsers will probably interpret the output as HTML, 
    69       which would result in ugly, scary gobbledygook in the browser window. 
     66    * The response gets a special MIME type, :mimetype:`application/pdf`. This 
     67      tells browsers that the document is a PDF file, rather than an HTML file. 
     68      If you leave this off, browsers will probably interpret the output as 
     69      HTML, which would result in ugly, scary gobbledygook in the browser 
     70      window. 
    7071 
    7172    * The response gets an additional ``Content-Disposition`` header, which 
    7273      contains the name of the PDF file. This filename is arbitrary: Call it 
     
    9798============ 
    9899 
    99100If you're creating a complex PDF document with ReportLab, consider using the 
    100 cStringIO_ library as a temporary holding place for your PDF file. The cStringIO 
     101:mod:`cStringIO` library as a temporary holding place for your PDF file. This 
    101102library provides a file-like object interface that is particularly efficient. 
    102 Here's the above "Hello World" example rewritten to use ``cStringIO``:: 
     103Here's the above "Hello World" example rewritten to use :mod:`cStringIO`:: 
    103104 
    104105    # Fall back to StringIO in environments where cStringIO is not available 
    105106    try: 
     
    133134        response.write(pdf) 
    134135        return response 
    135136 
    136 .. _cStringIO: http://docs.python.org/library/stringio.html#module-cStringIO 
    137  
    138137Further resources 
    139138================= 
    140139 
  • docs/topics/http/file-uploads.txt

     
    149149 
    150150    :setting:`FILE_UPLOAD_PERMISSIONS` 
    151151        The numeric mode (i.e. ``0644``) to set newly uploaded files to. For 
    152         more information about what these modes mean, see the `documentation for 
    153         os.chmod`_ 
     152        more information about what these modes mean, see the documentation for 
     153        :func:`os.chmod`. 
    154154 
    155155        If this isn't given or is ``None``, you'll get operating-system 
    156156        dependent behavior. On most platforms, temporary files will have a mode 
     
    179179        Which means "try to upload to memory first, then fall back to temporary 
    180180        files." 
    181181 
    182 .. _documentation for os.chmod: http://docs.python.org/library/os.html#os.chmod 
    183  
    184182``UploadedFile`` objects 
    185183======================== 
    186184 
     
    189187 
    190188.. attribute:: UploadedFile.content_type 
    191189 
    192     The content-type header uploaded with the file (e.g. ``text/plain`` or 
    193     ``application/pdf``). Like any data supplied by the user, you shouldn't 
    194     trust that the uploaded file is actually this type. You'll still need to 
    195     validate that the file contains the content that the content-type header 
    196     claims -- "trust but verify." 
     190    The content-type header uploaded with the file (e.g. :mimetype:`text/plain` 
     191    or :mimetype:`application/pdf`). Like any data supplied by the user, you 
     192    shouldn't trust that the uploaded file is actually this type. You'll still 
     193    need to validate that the file contains the content that the content-type 
     194    header claims -- "trust but verify." 
    197195 
    198196.. attribute:: UploadedFile.charset 
    199197 
    200     For ``text/*`` content-types, the character set (i.e. ``utf8``) supplied 
    201     by the browser. Again, "trust but verify" is the best policy here. 
     198    For :mimetype:`text/*` content-types, the character set (i.e. ``utf8``) 
     199    supplied by the browser. Again, "trust but verify" is the best policy here. 
    202200 
    203201.. attribute:: UploadedFile.temporary_file_path() 
    204202 
  • docs/topics/http/sessions.txt

     
    495495session cookie. 
    496496 
    497497HTTPOnly_ is a flag included in a Set-Cookie HTTP response header. It 
    498 is not part of the RFC2109 standard for cookies, and it isn't honored 
     498is not part of the :rfc:`2109` standard for cookies, and it isn't honored 
    499499consistently by all browsers. However, when it is honored, it can be a 
    500500useful way to mitigate the risk of client side script accessing the 
    501501protected cookie data. 
     
    553553================= 
    554554 
    555555    * The session dictionary should accept any pickleable Python object. See 
    556       `the pickle module`_ for more information. 
     556      the :mod:`pickle` module for more information. 
    557557 
    558558    * Session data is stored in a database table named ``django_session`` . 
    559559 
    560560    * Django only sends a cookie if it needs to. If you don't set any session 
    561561      data, it won't send a session cookie. 
    562562 
    563 .. _`the pickle module`: http://docs.python.org/library/pickle.html 
    564  
    565563Session IDs in URLs 
    566564=================== 
    567565 
  • docs/topics/http/views.txt

     
    211211 
    212212This view loads and renders the template ``403.html`` in your root template 
    213213directory, or if this file does not exist, instead serves the text 
    214 "403 Forbidden", as per RFC 2616 (the HTTP 1.1 Specification). 
     214"403 Forbidden", as per :rfc:`2616` (the HTTP 1.1 Specification). 
    215215 
    216216It is possible to override ``django.views.defaults.permission_denied`` in the 
    217217same way you can for the 404 and 500 views by specifying a ``handler403`` in 
  • docs/topics/http/shortcuts.txt

     
    6464------- 
    6565 
    6666The following example renders the template ``myapp/index.html`` with the 
    67 MIME type ``application/xhtml+xml``:: 
     67MIME type :mimetype:`application/xhtml+xml`:: 
    6868 
    6969    from django.shortcuts import render 
    7070 
     
    131131------- 
    132132 
    133133The following example renders the template ``myapp/index.html`` with the 
    134 MIME type ``application/xhtml+xml``:: 
     134MIME type :mimetype:`application/xhtml+xml`:: 
    135135 
    136136    from django.shortcuts import render_to_response 
    137137 
  • docs/topics/install.txt

     
    5252for information on how to configure mod_wsgi once you have it 
    5353installed. 
    5454 
    55 If you can't use mod_wsgi for some reason, fear not: Django supports 
    56 many other deployment options. One is :doc:`uWSGI </howto/deployment/fastcgi>`; 
    57 it works very well with `nginx`_. Another is :doc:`FastCGI 
    58 </howto/deployment/fastcgi>`, perfect for using Django with servers 
    59 other than Apache. Additionally, Django follows the WSGI_ spec, which 
    60 allows it to run on a variety of server platforms. See the 
    61 `server-arrangements wiki page`_ for specific installation 
    62 instructions for each platform. 
     55If you can't use mod_wsgi for some reason, fear not: Django supports many other 
     56deployment options. One is :doc:`uWSGI </howto/deployment/fastcgi>`; it works 
     57very well with `nginx`_. Another is :doc:`FastCGI </howto/deployment/fastcgi>`, 
     58perfect for using Django with servers other than Apache. Additionally, Django 
     59follows the WSGI spec (:pep:`3333`), which allows it to run on a variety of 
     60server platforms. See the `server-arrangements wiki page`_ for specific 
     61installation instructions for each platform. 
    6362 
    6463.. _Apache: http://httpd.apache.org/ 
    6564.. _nginx: http://nginx.net/ 
    6665.. _mod_wsgi: http://code.google.com/p/modwsgi/ 
    67 .. _WSGI: http://www.python.org/dev/peps/pep-0333/ 
    6866.. _server-arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements 
    6967 
    7068.. _database-installation: 
  • docs/topics/db/models.txt

     
    676676            return '%s %s' % (self.first_name, self.last_name) 
    677677        full_name = property(_get_full_name) 
    678678 
    679 The last method in this example is a :term:`property`. `Read more about 
    680 properties`_. 
     679The last method in this example is a :term:`property`. 
    681680 
    682 .. _Read more about properties: http://www.python.org/download/releases/2.2/descrintro/#property 
    683  
    684681The :doc:`model instance reference </ref/models/instances>` has a complete list 
    685682of :ref:`methods automatically given to each model <model-instance-methods>`. 
    686683You can override most of these -- see `overriding predefined model methods`_, 
  • docs/topics/db/sql.txt

     
    259259Connections and cursors 
    260260----------------------- 
    261261 
    262 ``connection`` and ``cursor`` mostly implement the standard `Python DB-API`_ 
    263 (except when it comes to :doc:`transaction handling </topics/db/transactions>`). 
    264 If you're not familiar with the Python DB-API, note that the SQL statement in 
    265 ``cursor.execute()`` uses placeholders, ``"%s"``, rather than adding parameters 
    266 directly within the SQL. If you use this technique, the underlying database 
    267 library will automatically add quotes and escaping to your parameter(s) as 
    268 necessary. (Also note that Django expects the ``"%s"`` placeholder, *not* the 
    269 ``"?"`` placeholder, which is used by the SQLite Python bindings. This is for 
    270 the sake of consistency and sanity.) 
    271  
    272 .. _Python DB-API: http://www.python.org/dev/peps/pep-0249/ 
     262``connection`` and ``cursor`` mostly implement the standard Python DB-API 
     263described in :pep:`249` (except when it comes to :doc:`transaction handling 
     264</topics/db/transactions>`). If you're not familiar with the Python DB-API, note 
     265that the SQL statement in ``cursor.execute()`` uses placeholders, ``"%s"``, 
     266rather than adding parameters directly within the SQL. If you use this 
     267technique, the underlying database library will automatically add quotes and 
     268escaping to your parameter(s) as necessary. (Also note that Django expects the 
     269``"%s"`` placeholder, *not* the ``"?"`` placeholder, which is used by the SQLite 
     270Python bindings. This is for the sake of consistency and sanity.) 
  • docs/topics/testing.txt

     
    3636frameworks are: 
    3737 
    3838    * **Unit tests** -- tests that are expressed as methods on a Python class 
    39       that subclasses ``unittest.TestCase`` or Django's customized 
     39      that subclasses :class:`unittest.TestCase` or Django's customized 
    4040      :class:`TestCase`. For example:: 
    4141 
    4242          import unittest 
     
    6868Writing unit tests 
    6969------------------ 
    7070 
    71 Django's unit tests use a Python standard library module: unittest_. This 
     71Django's unit tests use a Python standard library module: :mod:`unittest`. This 
    7272module defines tests in class-based approach. 
    7373 
    7474.. admonition:: unittest2 
     
    8282    backported for Python 2.5 compatibility. 
    8383 
    8484    To access this library, Django provides the 
    85     ``django.utils.unittest`` module alias. If you are using Python 
     85    :mod:`django.utils.unittest` module alias. If you are using Python 
    8686    2.7, or you have installed unittest2 locally, Django will map the 
    8787    alias to the installed version of the unittest library. Otherwise, 
    8888    Django will use it's own bundled version of unittest2. 
     
    104104places: 
    105105 
    106106    * The ``models.py`` file. The test runner looks for any subclass of 
    107       ``unittest.TestCase`` in this module. 
     107      :class:`unittest.TestCase` in this module. 
    108108 
    109109    * A file called ``tests.py`` in the application directory -- i.e., the 
    110110      directory that holds ``models.py``. Again, the test runner looks for any 
    111       subclass of ``unittest.TestCase`` in this module. 
     111      subclass of :class:`unittest.TestCase` in this module. 
    112112 
    113 Here is an example ``unittest.TestCase`` subclass:: 
     113Here is an example :class:`unittest.TestCase` subclass:: 
    114114 
    115115    from django.utils import unittest 
    116116    from myapp.models import Animal 
     
    124124            self.assertEqual(self.lion.speak(), 'The lion says "roar"') 
    125125            self.assertEqual(self.cat.speak(), 'The cat says "meow"') 
    126126 
    127 When you :ref:`run your tests <running-tests>`, the default behavior of the 
    128 test utility is to find all the test cases (that is, subclasses of 
    129 ``unittest.TestCase``) in ``models.py`` and ``tests.py``, automatically build a 
    130 test suite out of those test cases, and run that suite. 
     127When you :ref:`run your tests <running-tests>`, the default behavior of the test 
     128utility is to find all the test cases (that is, subclasses of 
     129:class:`unittest.TestCase`) in ``models.py`` and ``tests.py``, automatically 
     130build a test suite out of those test cases, and run that suite. 
    131131 
    132132There is a second way to define the test suite for a module: if you define a 
    133133function called ``suite()`` in either ``models.py`` or ``tests.py``, the 
     
    136136Python documentation for more details on how to construct a complex test 
    137137suite. 
    138138 
    139 For more details about ``unittest``, see the `standard library unittest 
    140 documentation`_. 
     139For more details about :mod:`unittest`, see the Python documentation. 
    141140 
    142 .. _unittest: http://docs.python.org/library/unittest.html 
    143 .. _standard library unittest documentation: unittest_ 
    144141.. _suggested organization: http://docs.python.org/library/unittest.html#organizing-tests 
    145142 
    146143Writing doctests 
    147144---------------- 
    148145 
    149 Doctests use Python's standard doctest_ module, which searches your docstrings 
    150 for statements that resemble a session of the Python interactive interpreter. 
    151 A full explanation of how doctest works is out of the scope of this document; 
    152 read Python's official documentation for the details. 
     146Doctests use Python's standard :mod:`doctest` module, which searches your 
     147docstrings for statements that resemble a session of the Python interactive 
     148interpreter. A full explanation of how :mod:`doctest` works is out of the scope 
     149of this document; read Python's official documentation for the details. 
    153150 
    154151.. admonition:: What's a **docstring**? 
    155152 
     
    221218on this.) Note that to use this feature, the database user Django is connecting 
    222219as must have ``CREATE DATABASE`` rights. 
    223220 
    224 For more details about how doctest works, see the `standard library 
    225 documentation for doctest`_. 
     221For more details about :mod:`doctest`, see the Python documentation. 
    226222 
    227 .. _doctest: http://docs.python.org/library/doctest.html 
    228 .. _standard library documentation for doctest: doctest_ 
    229  
    230  
    231223Which should I use? 
    232224------------------- 
    233225 
     
    239231then, are a few key differences to help you decide which approach is right for 
    240232you: 
    241233 
    242     * If you've been using Python for a while, ``doctest`` will probably feel 
     234    * If you've been using Python for a while, :mod:`doctest` will probably feel 
    243235      more "pythonic". It's designed to make writing tests as easy as possible, 
    244236      so it requires no overhead of writing classes or methods. You simply put 
    245237      tests in docstrings. This has the added advantage of serving as 
     
    250242      as it can be unclear exactly why the test failed. Thus, doctests should 
    251243      generally be avoided and used primarily for documentation examples only. 
    252244 
    253     * The ``unittest`` framework will probably feel very familiar to developers 
    254       coming from Java. ``unittest`` is inspired by Java's JUnit, so you'll 
    255       feel at home with this method if you've used JUnit or any test framework 
    256       inspired by JUnit. 
     245    * The :mod:`unittest` framework will probably feel very familiar to 
     246      developers coming from Java. :mod:`unittest` is inspired by Java's JUnit, 
     247      so you'll feel at home with this method if you've used JUnit or any test 
     248      framework inspired by JUnit. 
    257249 
    258250    * If you need to write a bunch of tests that share similar code, then 
    259       you'll appreciate the ``unittest`` framework's organization around 
     251      you'll appreciate the :mod:`unittest` framework's organization around 
    260252      classes and methods. This makes it easy to abstract common tasks into 
    261253      common methods. The framework also supports explicit setup and/or cleanup 
    262254      routines, which give you a high level of control over the environment 
    263255      in which your test cases are run. 
    264256 
    265     * If you're writing tests for Django itself, you should use ``unittest``. 
     257    * If you're writing tests for Django itself, you should use :mod:`unittest`. 
    266258 
    267259.. _running-tests: 
    268260 
     
    553545 
    554546A full explanation of this error output is beyond the scope of this document, 
    555547but it's pretty intuitive. You can consult the documentation of Python's 
    556 ``unittest`` library for details. 
     548:mod:`unittest` library for details. 
    557549 
    558550Note that the return code for the test-runner script is 1 for any number of 
    559551failed and erroneous tests. If all the tests pass, the return code is 0. This 
     
    639631 
    640632      The test client is not capable of retrieving Web pages that are not 
    641633      powered by your Django project. If you need to retrieve other Web pages, 
    642       use a Python standard library module such as urllib_ or urllib2_. 
     634      use a Python standard library module such as :mod:`urllib` or 
     635      :mod:`urllib2`. 
    643636 
    644637    * To resolve URLs, the test client uses whatever URLconf is pointed-to by 
    645638      your :setting:`ROOT_URLCONF` setting. 
     
    668661          >>> from django.test import Client 
    669662          >>> csrf_client = Client(enforce_csrf_checks=True) 
    670663 
    671  
    672 .. _urllib: http://docs.python.org/library/urllib.html 
    673 .. _urllib2: http://docs.python.org/library/urllib2.html 
    674  
    675664Making requests 
    676665~~~~~~~~~~~~~~~ 
    677666 
     
    759748 
    760749            name=fred&passwd=secret 
    761750 
    762         If you provide ``content_type`` (e.g., ``text/xml`` for an XML 
     751        If you provide ``content_type`` (e.g. :mimetype:`text/xml` for an XML 
    763752        payload), the contents of ``data`` will be sent as-is in the POST 
    764753        request, using ``content_type`` in the HTTP ``Content-Type`` header. 
    765754 
    766755        If you don't provide a value for ``content_type``, the values in 
    767756        ``data`` will be transmitted with a content type of 
    768         ``multipart/form-data``. In this case, the key-value pairs in ``data`` 
    769         will be encoded as a multipart message and used to create the POST data 
    770         payload. 
     757        :mimetype:`multipart/form-data`. In this case, the key-value pairs in 
     758        ``data`` will be encoded as a multipart message and used to create the 
     759        POST data payload. 
    771760 
    772761        To submit multiple values for a given key -- for example, to specify 
    773762        the selections for a ``<select multiple>`` -- provide the values as a 
     
    955944 
    956945    .. attribute:: status_code 
    957946 
    958         The HTTP status of the response, as an integer. See RFC2616_ for a full 
    959         list of HTTP status codes. 
     947        The HTTP status of the response, as an integer. See 
     948        :rfc:`2616#section-10` for a full list of HTTP status codes. 
    960949 
    961950    .. versionadded:: 1.3 
    962951 
     
    972961of any settings in the HTTP headers. For example, you could determine the 
    973962content type of a response using ``response['Content-Type']``. 
    974963 
    975 .. _RFC2616: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html 
    976  
    977964Exceptions 
    978965~~~~~~~~~~ 
    979966 
    980967If you point the test client at a view that raises an exception, that exception 
    981 will be visible in the test case. You can then use a standard ``try...except`` 
    982 block or ``unittest.TestCase.assertRaises()`` to test for exceptions. 
     968will be visible in the test case. You can then use a standard ``try ... except`` 
     969block or :meth:`~unittest.TestCase.assertRaises` to test for exceptions. 
    983970 
    984971The only exceptions that are not visible to the test client are ``Http404``, 
    985972``PermissionDenied`` and ``SystemExit``. Django catches these exceptions 
     
    1002989 
    1003990.. attribute:: Client.cookies 
    1004991 
    1005     A Python ``SimpleCookie`` object, containing the current values of all the 
    1006     client cookies. See the `Cookie module documentation`_ for more. 
     992    A Python :class:`~Cookie.SimpleCookie` object, containing the current values 
     993    of all the client cookies. See the documentation of the :mod:`Cookie` module 
     994    for more. 
    1007995 
    1008996.. attribute:: Client.session 
    1009997 
     
    10191007            session['somekey'] = 'test' 
    10201008            session.save() 
    10211009 
    1022 .. _Cookie module documentation: http://docs.python.org/library/cookie.html 
    1023  
    10241010Example 
    10251011~~~~~~~ 
    10261012 
     
    11001086 
    11011087.. currentmodule:: django.test 
    11021088 
    1103 Normal Python unit test classes extend a base class of ``unittest.TestCase``. 
    1104 Django provides a few extensions of this base class: 
     1089Normal Python unit test classes extend a base class of 
     1090:class:`unittest.TestCase`. Django provides a few extensions of this base class: 
    11051091 
    11061092.. class:: TestCase() 
    11071093 
    11081094This class provides some additional capabilities that can be useful for testing 
    11091095Web sites. 
    11101096 
    1111 Converting a normal ``unittest.TestCase`` to a Django ``TestCase`` is easy: 
    1112 just change the base class of your test from ``unittest.TestCase`` to 
    1113 ``django.test.TestCase``. All of the standard Python unit test functionality 
    1114 will continue to be available, but it will be augmented with some useful 
    1115 additions, including: 
     1097Converting a normal :class:`unittest.TestCase` to a Django :class:`TestCase` is 
     1098easy: just change the base class of your test from :class:`unittest.TestCase` to 
     1099:class:`django.test.TestCase`. All of the standard Python unit test 
     1100functionality will continue to be available, but it will be augmented with some 
     1101useful additions, including: 
    11161102 
    11171103    * Automatic loading of fixtures. 
    11181104 
     
    14091395 
    14101396.. versionadded:: 1.4 
    14111397 
    1412 For testing purposes it's often useful to change a setting temporarily 
    1413 and revert to the original value after running the testing code. For 
    1414 this use case Django provides a standard `Python context manager`_ 
     1398For testing purposes it's often useful to change a setting temporarily and 
     1399revert to the original value after running the testing code. For this use case 
     1400Django provides a standard Python context manager (see :pep:`343`) 
    14151401:meth:`~django.test.TestCase.settings`, which can be used like this:: 
    14161402 
    14171403    from django.test import TestCase 
     
    14371423.. function:: override_settings 
    14381424 
    14391425In case you want to override a setting for just one test method or even the 
    1440 whole TestCase class, Django provides the 
    1441 :func:`django.test.utils.override_settings` decorator_. It's used like this:: 
     1426whole :class:`TestCase` class, Django provides the 
     1427:func:`~django.test.utils.override_settings` decorator (see :pep:`318`). It's 
     1428used like this:: 
    14421429 
    14431430    from django.test import TestCase 
    14441431    from django.test.utils import override_settings 
     
    14841471    :data:`django.test.signals.setting_changed` signal to connect cleanup 
    14851472    and other state-resetting callbacks to. 
    14861473 
    1487 .. _`Python context manager`: http://www.python.org/dev/peps/pep-0343/ 
    1488 .. _`decorator`: http://www.python.org/dev/peps/pep-0318/ 
    1489  
    14901474Emptying the test outbox 
    14911475~~~~~~~~~~~~~~~~~~~~~~~~ 
    14921476 
     
    15051489.. versionchanged:: 1.2 
    15061490    Addded ``msg_prefix`` argument. 
    15071491 
    1508 As Python's normal ``unittest.TestCase`` class implements assertion methods 
    1509 such as ``assertTrue`` and ``assertEqual``, Django's custom ``TestCase`` class 
     1492As Python's normal :class:`unittest.TestCase` class implements assertion methods 
     1493such as :meth:`~unittest.TestCase.assertTrue` and 
     1494:meth:`~unittest.TestCase.assertEqual`, Django's custom :class:`TestCase` class 
    15101495provides a number of custom assertion methods that are useful for testing Web 
    15111496applications: 
    15121497 
     
    15211506    Asserts that execution of callable ``callable_obj`` raised the 
    15221507    ``expected_exception`` exception and that such exception has an 
    15231508    ``expected_message`` representation. Any other outcome is reported as a 
    1524     failure. Similar to unittest's ``assertRaisesRegexp`` with the difference 
    1525     that ``expected_message`` isn't a regular expression. 
     1509    failure. Similar to unittest's :meth:`~unittest.TestCase.assertRaisesRegexp` 
     1510    with the difference that ``expected_message`` isn't a regular expression. 
    15261511 
    15271512.. method:: assertFieldOutput(self, fieldclass, valid, invalid, field_args=None, field_kwargs=None, empty_value=u'') 
    15281513 
     
    17061691 
    17071692.. versionadded:: 1.3 
    17081693 
    1709 The unittest library provides the ``@skipIf`` and ``@skipUnless`` 
    1710 decorators to allow you to skip tests if you know ahead of time that 
    1711 those tests are going to fail under certain conditions. 
     1694The unittest library provides the :func:`@skipIf <unittest.skipIf>` and 
     1695:func:`@skipUnless <unittest.skipUnless>` decorators to allow you to skip tests 
     1696if you know ahead of time that those tests are going to fail under certain 
     1697conditions. 
    17121698 
    1713 For example, if your test requires a particular optional library in 
    1714 order to succeed, you could decorate the test case with ``@skipIf``. 
    1715 Then, the test runner will report that the test wasn't executed and 
    1716 why, instead of failing the test or omitting the test altogether. 
     1699For example, if your test requires a particular optional library in order to 
     1700succeed, you could decorate the test case with :func:`@skipIf 
     1701<unittest.skipIf>`. Then, the test runner will report that the test wasn't 
     1702executed and why, instead of failing the test or omitting the test altogether. 
    17171703 
    17181704To supplement these test skipping behaviors, Django provides two 
    17191705additional skip decorators. Instead of testing a generic boolean, 
     
    17571743Using different testing frameworks 
    17581744================================== 
    17591745 
    1760 Clearly, ``doctest`` and ``unittest`` are not the only Python testing 
     1746Clearly, :mod:`doctest` and :mod:`unittest` are not the only Python testing 
    17611747frameworks. While Django doesn't provide explicit support for alternative 
    17621748frameworks, it does provide a way to invoke tests constructed for an 
    17631749alternative framework as if they were normal Django tests. 
  • docs/topics/logging.txt

     
    1010A quick logging primer 
    1111====================== 
    1212 
    13 Django uses Python's builtin logging module to perform system logging. 
    14 The usage of the logging module is discussed in detail in `Python's 
    15 own documentation`_. However, if you've never used Python's logging 
    16 framework (or even if you have), here's a quick primer. 
     13Django uses Python's builtin :mod:`logging` module to perform system logging. 
     14The usage of this module is discussed in detail in Python's own documentation. 
     15However, if you've never used Python's logging framework (or even if you have), 
     16here's a quick primer. 
    1717 
    18 .. _Python's own documentation: http://docs.python.org/library/logging.html 
    19  
    2018The cast of players 
    2119------------------- 
    2220 
  • docs/topics/email.txt

     
    55.. module:: django.core.mail 
    66   :synopsis: Helpers to easily send email. 
    77 
    8 Although Python makes sending email relatively easy via the `smtplib 
    9 library`_, Django provides a couple of light wrappers over it. These wrappers 
    10 are provided to make sending email extra quick, to make it easy to test 
    11 email sending during development, and to provide support for platforms that 
    12 can't use SMTP. 
     8Although Python makes sending email relatively easy via the :mod:`smtplib` 
     9module, Django provides a couple of light wrappers over it. These wrappers are 
     10provided to make sending email extra quick, to make it easy to test email 
     11sending during development, and to provide support for platforms that can't use 
     12SMTP. 
    1313 
    1414The code lives in the ``django.core.mail`` module. 
    1515 
    16 .. _smtplib library: http://docs.python.org/library/smtplib.html 
    17  
    1816Quick example 
    1917============= 
    2018 
     
    5452      member of ``recipient_list`` will see the other recipients in the "To:" 
    5553      field of the email message. 
    5654    * ``fail_silently``: A boolean. If it's ``False``, ``send_mail`` will raise 
    57       an ``smtplib.SMTPException``. See the `smtplib docs`_ for a list of 
    58       possible exceptions, all of which are subclasses of ``SMTPException``. 
     55      an :exc:`smtplib.SMTPException`. See the :mod:`smtplib` docs for a list of 
     56      possible exceptions, all of which are subclasses of 
     57      :exc:`~smtplib.SMTPException`. 
    5958    * ``auth_user``: The optional username to use to authenticate to the SMTP 
    6059      server. If this isn't provided, Django will use the value of the 
    6160      :setting:`EMAIL_HOST_USER` setting. 
     
    6766      See the documentation on :ref:`Email backends <topic-email-backends>` 
    6867      for more details. 
    6968 
    70 .. _smtplib docs: http://docs.python.org/library/smtplib.html 
    71  
    7269send_mass_mail() 
    7370================ 
    7471 
     
    125122.. versionchanged:: 1.3 
    126123 
    127124If ``html_message`` is provided, the resulting email will be a 
    128 multipart/alternative email with ``message`` as the "text/plain" 
    129 content type and ``html_message`` as the "text/html" content type. 
     125:mimetype:`multipart/alternative` email with ``message`` as the 
     126:mimetype:`text/plain` content type and ``html_message`` as the 
     127:mimetype:`text/html` content type. 
    130128 
    131129mail_managers() 
    132130=============== 
     
    608606:setting:`EMAIL_PORT` accordingly, and you are set. 
    609607 
    610608For a more detailed discussion of testing and processing of emails locally, 
    611 see the Python documentation on the `SMTP Server`_. 
     609see the Python documentation for the :mod:`smtpd` module. 
    612610 
    613 .. _SMTP Server: http://docs.python.org/library/smtpd.html 
    614  
    615611SMTPConnection 
    616612============== 
    617613 
  • docs/releases/1.2.txt

     
    764764 
    765765Code taking advantage of any of the features below will raise a 
    766766``PendingDeprecationWarning`` in Django 1.2. This warning will be 
    767 silent by default, but may be turned on using Python's `warnings 
    768 module`_, or by running Python with a ``-Wd`` or `-Wall` flag. 
     767silent by default, but may be turned on using Python's :mod:`warnings` 
     768module, or by running Python with a ``-Wd`` or `-Wall` flag. 
    769769 
    770 .. _warnings module: http://docs.python.org/library/warnings.html 
    771  
    772770In Django 1.3, these warnings will become a ``DeprecationWarning``, 
    773771which is *not* silent. In Django 1.4 support for these features will 
    774772be removed entirely. 
  • docs/releases/1.3.txt

     
    664664 
    665665Code taking advantage of any of the features below will raise a 
    666666``PendingDeprecationWarning`` in Django 1.3. This warning will be 
    667 silent by default, but may be turned on using Python's `warnings 
    668 module`_, or by running Python with a ``-Wd`` or `-Wall` flag. 
     667silent by default, but may be turned on using Python's :mod:`warnings` 
     668module, or by running Python with a ``-Wd`` or `-Wall` flag. 
    669669 
    670 .. _warnings module: http://docs.python.org/library/warnings.html 
    671  
    672670In Django 1.4, these warnings will become a ``DeprecationWarning``, 
    673671which is *not* silent. In Django 1.5 support for these features will 
    674672be removed entirely. 
  • docs/releases/1.4.txt

     
    462462Previously, Django's :doc:`CSRF protection </ref/contrib/csrf/>` provided 
    463463protection against only POST requests. Since use of PUT and DELETE methods in 
    464464AJAX applications is becoming more common, we now protect all methods not 
    465 defined as safe by RFC 2616 i.e. we exempt GET, HEAD, OPTIONS and TRACE, and 
     465defined as safe by :rfc:`2616` i.e. we exempt GET, HEAD, OPTIONS and TRACE, and 
    466466enforce protection on everything else. 
    467467 
    468468If you using PUT or DELETE methods in AJAX applications, please see the 
  • docs/releases/1.3-alpha-1.txt

     
    279279 
    280280Code taking advantage of any of the features below will raise a 
    281281``PendingDeprecationWarning`` in Django 1.3. This warning will be 
    282 silent by default, but may be turned on using Python's `warnings 
    283 module`_, or by running Python with a ``-Wd`` or `-Wall` flag. 
     282silent by default, but may be turned on using Python's :mod:`warnings` 
     283module, or by running Python with a ``-Wd`` or `-Wall` flag. 
    284284 
    285 .. _warnings module: http://docs.python.org/library/warnings.html 
    286  
    287285In Django 1.4, these warnings will become a ``DeprecationWarning``, 
    288286which is *not* silent. In Django 1.5 support for these features will 
    289287be removed entirely. 
  • docs/releases/0.96.txt

     
    216216------------------ 
    217217 
    218218Django now includes a test framework so you can start transmuting fear into 
    219 boredom (with apologies to Kent Beck). You can write tests based on doctest_ 
    220 or unittest_ and test your views with a simple test client. 
     219boredom (with apologies to Kent Beck). You can write tests based on 
     220:mod:`doctest` or :mod:`unittest` and test your views with a simple test client. 
    221221 
    222222There is also new support for "fixtures" -- initial data, stored in any of the 
    223223supported `serialization formats`_, that will be loaded into your database at the 
     
    225225 
    226226See `the testing documentation`_ for the full details. 
    227227 
    228 .. _doctest: http://docs.python.org/library/doctest.html 
    229 .. _unittest: http://docs.python.org/library/unittest.html 
    230228.. _the testing documentation: http://www.djangoproject.com/documentation/0.96/testing/ 
    231229.. _serialization formats: http://www.djangoproject.com/documentation/0.96/serialization/ 
    232230 
  • docs/faq/install.txt

     
    2222 
    2323For a development environment -- if you just want to experiment with Django -- 
    2424you don't need to have a separate Web server installed; Django comes with its 
    25 own lightweight development server. For a production environment, Django 
    26 follows the WSGI_ spec, which means it can run on a variety of server 
    27 platforms.  See :doc:`Deploying Django </howto/deployment/index>` for some 
    28 popular alternatives.  Also, the `server arrangements wiki page`_ contains 
     25own lightweight development server. For a production environment, Django follows 
     26the WSGI spec, :pep:`3333`, which means it can run on a variety of server 
     27platforms. See :doc:`Deploying Django </howto/deployment/index>` for some 
     28popular alternatives. Also, the `server arrangements wiki page`_ contains 
    2929details for several deployment strategies. 
    3030 
    3131If you want to use Django with a database, which is probably the case, you'll 
     
    3333PostgreSQL fans, and MySQL_, `SQLite 3`_, and Oracle_ are also supported. 
    3434 
    3535.. _Python: http://www.python.org/ 
    36 .. _WSGI: http://www.python.org/dev/peps/pep-0333/ 
    3736.. _server arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements 
    3837.. _PostgreSQL: http://www.postgresql.org/ 
    3938.. _MySQL: http://www.mysql.com/ 
     
    4847Python are often faster, have more features, and are better supported. If you 
    4948use a newer version of Python you will also have access to some APIs that 
    5049aren't available under older versions of Python. For example, since Python 2.6, 
    51 you can use the advanced string formatting described in `PEP 3101`_. 
     50you can use the advanced string formatting described in :pep:`3101`. 
    5251 
    5352Third-party applications for use with Django are, of course, free to set their 
    5453own version requirements. 
     
    6362will help ease the process of dropping support for older Python versions on 
    6463the road to Python 3. 
    6564 
    66 .. _PEP 3101: http://www.python.org/dev/peps/pep-3101/ 
    67  
    6865Can I use Django with Python 2.4? 
    6966--------------------------------- 
    7067 
  • docs/ref/models/querysets.txt

     
    8181Pickling QuerySets 
    8282------------------ 
    8383 
    84 If you pickle_ a ``QuerySet``, this will force all the results to be loaded 
     84If you :mod:`pickle` a ``QuerySet``, this will force all the results to be loaded 
    8585into memory prior to pickling. Pickling is usually used as a precursor to 
    8686caching and when the cached queryset is reloaded, you want the results to 
    8787already be present and ready for use (reading from the database can take some 
     
    112112        Django version N+1. Pickles should not be used as part of a long-term 
    113113        archival strategy. 
    114114 
    115 .. _pickle: http://docs.python.org/library/pickle.html 
    116  
    117115.. _queryset-api: 
    118116 
    119117QuerySet API 
     
    12061204.. method:: iterator() 
    12071205 
    12081206Evaluates the ``QuerySet`` (by performing the query) and returns an 
    1209 `iterator`_ over the results. A ``QuerySet`` typically caches its 
     1207iterator (see :pep:`234`) over the results. A ``QuerySet`` typically caches its 
    12101208results internally so that repeated evaluations do not result in 
    12111209additional queries; ``iterator()`` will instead read results directly, 
    12121210without doing any caching at the ``QuerySet`` level. For a 
     
    12161214Note that using ``iterator()`` on a ``QuerySet`` which has already 
    12171215been evaluated will force it to evaluate again, repeating the query. 
    12181216 
    1219 .. _iterator: http://www.python.org/dev/peps/pep-0234/ 
    1220  
    12211217latest 
    12221218~~~~~~ 
    12231219 
  • docs/ref/models/fields.txt

     
    500500    setting to determine the value of the :attr:`~django.core.files.File.url` 
    501501    attribute. 
    502502 
    503     This path may contain `strftime formatting`_, which will be replaced by the 
    504     date/time of the file upload (so that uploaded files don't fill up the given 
    505     directory). 
     503    This path may contain :func:`~time.strftime` formatting, which will be 
     504    replaced by the date/time of the file upload (so that uploaded files don't 
     505    fill up the given directory). 
    506506 
    507507    This may also be a callable, such as a function, which will be called to 
    508508    obtain the upload path, including the filename. This callable must be able 
     
    560560 
    561561For example, say your :setting:`MEDIA_ROOT` is set to ``'/home/media'``, and 
    562562:attr:`~FileField.upload_to` is set to ``'photos/%Y/%m/%d'``. The ``'%Y/%m/%d'`` 
    563 part of :attr:`~FileField.upload_to` is `strftime formatting`_; ``'%Y'`` is the 
    564 four-digit year, ``'%m'`` is the two-digit month and ``'%d'`` is the two-digit 
    565 day. If you upload a file on Jan. 15, 2007, it will be saved in the directory 
    566 ``/home/media/photos/2007/01/15``. 
     563part of :attr:`~FileField.upload_to` is :func:`~time.strftime` formatting; 
     564``'%Y'`` is the four-digit year, ``'%m'`` is the two-digit month and ``'%d'`` is 
     565the two-digit day. If you upload a file on Jan. 15, 2007, it will be saved in 
     566the directory ``/home/media/photos/2007/01/15``. 
    567567 
    568568If you wanted to retrieve the uploaded file's on-disk filename, or the file's 
    569569size, you could use the :attr:`~django.core.files.File.name` and 
     
    595595created as ``varchar(100)`` columns in your database. As with other fields, you 
    596596can change the maximum length using the :attr:`~CharField.max_length` argument. 
    597597 
    598 .. _`strftime formatting`: http://docs.python.org/library/time.html#time.strftime 
    599  
    600598FileField and FieldFile 
    601599~~~~~~~~~~~~~~~~~~~~~~~ 
    602600 
     
    711709    :class:`DecimalField` class. Although they both represent real numbers, they 
    712710    represent those numbers differently. ``FloatField`` uses Python's ``float`` 
    713711    type internally, while ``DecimalField`` uses Python's ``Decimal`` type. For 
    714     information on the difference between the two, see Python's documentation on 
    715     `Decimal fixed point and floating point arithmetic`_. 
     712    information on the difference between the two, see Python's documentation 
     713    for the :mod:`decimal` module. 
    716714 
    717 .. _Decimal fixed point and floating point arithmetic: http://docs.python.org/library/decimal.html 
    718  
    719  
    720715``ImageField`` 
    721716-------------- 
    722717 
     
    777772``2a02:42fe::4``). The admin represents this as an ``<input type="text">`` 
    778773(a single-line input). 
    779774 
    780 The IPv6 address normalization follows `RFC4291 section 2.2`_, including using 
    781 the IPv4 format suggested in paragraph 3 of that section, like 
     775The IPv6 address normalization follows :rfc:`4291#section-2.2` section 2.2, 
     776including using the IPv4 format suggested in paragraph 3 of that section, like 
    782777``::ffff:192.0.2.0``. For example, ``2001:0::0:01`` would be normalized to 
    783 ``2001::1``, and ``::ffff:0a0a:0a0a`` to ``::ffff:10.10.10.10``. All 
    784 characters are converted to lowercase. 
     778``2001::1``, and ``::ffff:0a0a:0a0a`` to ``::ffff:10.10.10.10``. All characters 
     779are converted to lowercase. 
    785780 
    786 .. _RFC4291 section 2.2: http://tools.ietf.org/html/rfc4291#section-2.2 
    787  
    788781.. attribute:: GenericIPAddressField.protocol 
    789782 
    790783    Limits valid inputs to the specified protocol. 
  • docs/ref/models/instances.txt

     
    432432 
    433433.. note:: 
    434434    The string you return from ``get_absolute_url()`` must contain only ASCII 
    435     characters (required by the URI spec, `RFC 2396`_) that have been 
     435    characters (required by the URI spec, :rfc:`2396`) that have been 
    436436    URL-encoded, if necessary. Code and templates using ``get_absolute_url()`` 
    437437    should be able to use the result directly without needing to do any 
    438438    further processing. You may wish to use the 
    439439    ``django.utils.encoding.iri_to_uri()`` function to help with this if you 
    440440    are using unicode strings a lot. 
    441441 
    442 .. _RFC 2396: http://www.ietf.org/rfc/rfc2396.txt 
    443  
    444442The ``permalink`` decorator 
    445443~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
    446444 
  • docs/ref/generic-views.txt

     
    346346 
    347347**Optional arguments:** 
    348348 
    349     * ``month_format``: A format string that regulates what format the 
    350       ``month`` parameter uses. This should be in the syntax accepted by 
    351       Python's ``time.strftime``. (See the `strftime docs`_.) It's set to 
    352       ``"%b"`` by default, which is a three-letter month abbreviation. To 
    353       change it to use numbers, use ``"%m"``. 
     349    * ``month_format``: A format string that regulates what format the ``month`` 
     350      parameter uses. This should be in the syntax accepted by Python's 
     351      :func:`~time.strftime`. It's set to ``"%b"`` by default, which is a 
     352      three-letter month abbreviation. To change it to use numbers, use 
     353      ``"%m"``. 
    354354 
    355355    * ``template_name``: The full name of a template to use in rendering the 
    356356      page. This lets you override the default template name (see below). 
     
    415415      is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, 
    416416      this variable's name will be ``foo_list``. 
    417417 
    418 .. _strftime docs: http://docs.python.org/library/time.html#time.strftime 
    419  
    420418``django.views.generic.date_based.archive_week`` 
    421419------------------------------------------------ 
    422420 
     
    516514 
    517515**Optional arguments:** 
    518516 
    519     * ``month_format``: A format string that regulates what format the 
    520       ``month`` parameter uses. This should be in the syntax accepted by 
    521       Python's ``time.strftime``. (See the `strftime docs`_.) It's set to 
    522       ``"%b"`` by default, which is a three-letter month abbreviation. To 
    523       change it to use numbers, use ``"%m"``. 
     517    * ``month_format``: A format string that regulates what format the ``month`` 
     518      parameter uses. This should be in the syntax accepted by Python's 
     519      :func:`~time.strftime`. It's set to ``"%b"`` by default, which is a 
     520      three-letter month abbreviation. To change it to use numbers, use 
     521      ``"%m"``. 
    524522 
    525523    * ``day_format``: Like ``month_format``, but for the ``day`` parameter. 
    526524      It defaults to ``"%d"`` (day of the month as a decimal number, 01-31). 
     
    624622 
    625623**Optional arguments:** 
    626624 
    627     * ``month_format``: A format string that regulates what format the 
    628       ``month`` parameter uses. This should be in the syntax accepted by 
    629       Python's ``time.strftime``. (See the `strftime docs`_.) It's set to 
    630       ``"%b"`` by default, which is a three-letter month abbreviation. To 
    631       change it to use numbers, use ``"%m"``. 
     625    * ``month_format``: A format string that regulates what format the ``month`` 
     626      parameter uses. This should be in the syntax accepted by Python's 
     627      :func:`~time.strftime`. It's set to ``"%b"`` by default, which is a 
     628      three-letter month abbreviation. To change it to use numbers, use 
     629      ``"%m"``. 
    632630 
    633631    * ``day_format``: Like ``month_format``, but for the ``day`` parameter. 
    634632      It defaults to ``"%d"`` (day of the month as a decimal number, 01-31). 
  • docs/ref/forms/fields.txt

     
    639639    * Validates that the given value is a valid IP address. 
    640640    * Error message keys: ``required``, ``invalid`` 
    641641 
    642 The IPv6 address normalization follows `RFC4291 section 2.2`_, including using 
    643 the IPv4 format suggested in paragraph 3 of that section, like 
     642The IPv6 address normalization follows :rfc:`4291#section-2.2` section 2.2, 
     643including using the IPv4 format suggested in paragraph 3 of that section, like 
    644644``::ffff:192.0.2.0``. For example, ``2001:0::0:01`` would be normalized to 
    645 ``2001::1``, and ``::ffff:0a0a:0a0a`` to ``::ffff:10.10.10.10``. All 
    646 characters are converted to lowercase. 
     645``2001::1``, and ``::ffff:0a0a:0a0a`` to ``::ffff:10.10.10.10``. All characters 
     646are converted to lowercase. 
    647647 
    648 .. _RFC4291 section 2.2: http://tools.ietf.org/html/rfc4291#section-2.2 
    649  
    650648Takes two optional arguments: 
    651649 
    652650.. attribute:: GenericIPAddressField.protocol 
  • docs/ref/class-based-views.txt

     
    586586 
    587587    .. attribute:: year_format 
    588588 
    589         The strftime_ format to use when parsing the year. By default, this is 
    590         ``'%Y'``. 
     589        The :func:`~time.strftime` format to use when parsing the year. 
     590        By default, this is ``'%Y'``. 
    591591 
    592     .. _strftime: http://docs.python.org/library/time.html#time.strftime 
    593  
    594592    .. attribute:: year 
    595593 
    596594        **Optional** The value for the year (as a string). By default, set to 
     
    598596 
    599597    .. method:: get_year_format() 
    600598 
    601         Returns the strftime_ format to use when parsing the year. Returns 
     599        Returns the :func:`~time.strftime` format to use when parsing the year. Returns 
    602600        :attr:`YearMixin.year_format` by default. 
    603601 
    604602    .. method:: get_year() 
     
    621619 
    622620    .. attribute:: month_format 
    623621 
    624         The strftime_ format to use when parsing the month. By default, this is 
     622        The :func:`~time.strftime` format to use when parsing the month. By default, this is 
    625623        ``'%b'``. 
    626624 
    627625    .. attribute:: month 
     
    631629 
    632630    .. method:: get_month_format() 
    633631 
    634         Returns the strftime_ format to use when parsing the month. Returns 
     632        Returns the :func:`~time.strftime` format to use when parsing the month. Returns 
    635633        :attr:`MonthMixin.month_format` by default. 
    636634 
    637635    .. method:: get_month() 
     
    667665 
    668666    .. attribute:: day_format 
    669667 
    670         The strftime_ format to use when parsing the day. By default, this is 
     668        The :func:`~time.strftime` format to use when parsing the day. By default, this is 
    671669        ``'%d'``. 
    672670 
    673671    .. attribute:: day 
     
    677675 
    678676    .. method:: get_day_format() 
    679677 
    680         Returns the strftime_ format to use when parsing the day. Returns 
     678        Returns the :func:`~time.strftime` format to use when parsing the day. Returns 
    681679        :attr:`DayMixin.day_format` by default. 
    682680 
    683681    .. method:: get_day() 
     
    712710 
    713711    .. attribute:: week_format 
    714712 
    715         The strftime_ format to use when parsing the week. By default, this is 
     713        The :func:`~time.strftime` format to use when parsing the week. By default, this is 
    716714        ``'%U'``. 
    717715 
    718716    .. attribute:: week 
     
    722720 
    723721    .. method:: get_week_format() 
    724722 
    725         Returns the strftime_ format to use when parsing the week. Returns 
     723        Returns the :func:`~time.strftime` format to use when parsing the week. Returns 
    726724        :attr:`WeekMixin.week_format` by default. 
    727725 
    728726    .. method:: get_week() 
  • docs/ref/templates/builtins.txt

     
    12541254    c                 ISO 8601 format. (Note: unlike others     ``2008-01-02T10:30:00.000123+02:00``, 
    12551255                      formatters, such as "Z", "O" or "r",      or ``2008-01-02T10:30:00.000123`` if the datetime is naive 
    12561256                      the "c" formatter will not add timezone 
    1257                       offset if value is a `naive datetime`_.) 
     1257                      offset if value is a naive datetime 
     1258                      (see :class:`datetime.tzinfo`). 
    12581259    d                 Day of the month, 2 digits with           ``'01'`` to ``'31'`` 
    12591260                      leading zeros. 
    12601261    D                 Day of the week, textual, 3 letters.      ``'Fri'`` 
     
    12881289                      if they're zero and the special-case 
    12891290                      strings 'midnight' and 'noon' if 
    12901291                      appropriate. Proprietary extension. 
    1291     r                 RFC 2822 formatted date.                  ``'Thu, 21 Dec 2000 16:01:07 +0200'`` 
     1292    r                 :rfc:`2822` formatted date.               ``'Thu, 21 Dec 2000 16:01:07 +0200'`` 
    12921293    s                 Seconds, 2 digits with leading zeros.     ``'00'`` to ``'59'`` 
    12931294    S                 English ordinal suffix for day of the     ``'st'``, ``'nd'``, ``'rd'`` or ``'th'`` 
    12941295                      month, 2 characters. 
     
    13461347.. versionchanged:: 1.2 
    13471348    Predefined formats can now be influenced by the current locale. 
    13481349 
    1349 .. _naive datetime: http://docs.python.org/library/datetime.html#datetime.tzinfo 
    1350  
    13511350.. templatefilter:: default 
    13521351 
    13531352default 
     
    18151814pprint 
    18161815^^^^^^ 
    18171816 
    1818 A wrapper around `pprint.pprint`__ -- for debugging, really. 
     1817A wrapper around :func:`pprint.pprint` -- for debugging, really. 
    18191818 
    1820 __ http://docs.python.org/library/pprint.html 
    1821  
    18221819.. templatefilter:: random 
    18231820 
    18241821random 
  • docs/ref/exceptions.txt

     
    128128.. exception:: IntegrityError 
    129129 
    130130The Django wrappers for database exceptions behave exactly the same as 
    131 the underlying database exceptions. See `PEP 249 - Python Database API 
    132 Specification v2.0`_ for further information. 
     131the underlying database exceptions. See :pep:`249`, the Python Database API 
     132Specification v2.0, for further information. 
    133133 
    134 .. _`PEP 249 - Python Database API Specification v2.0`: http://www.python.org/dev/peps/pep-0249/ 
    135  
    136134.. currentmodule:: django.db.transaction 
    137135 
    138136Transaction Exceptions 
     
    147145Python Exceptions 
    148146================= 
    149147 
    150 Django raises built-in Python exceptions when appropriate as well. See 
    151 the Python `documentation`_ for further information on the built-in 
    152 exceptions. 
    153  
    154 .. _`documentation`: http://docs.python.org/lib/module-exceptions.html 
     148Django raises built-in Python exceptions when appropriate as well. See the 
     149Python documentation for further information on the 
     150built-in :mod:`exceptions`. 
  • docs/ref/contrib/gis/install.txt

     
    12351235    postgres# CREATE DATABASE geodjango OWNER geodjango TEMPLATE template_postgis ENCODING 'utf8'; 
    12361236 
    12371237.. rubric:: Footnotes 
    1238 .. [#] The datum shifting files are needed for converting data to and from certain projections. 
    1239        For example, the PROJ.4 string for the `Google projection (900913) <http://spatialreference.org/ref/epsg/900913/proj4>`_ 
    1240        requires the ``null`` grid file only included in the extra datum shifting files. 
    1241        It is easier to install the shifting files now, then to have debug a problem caused by their absence later. 
    1242 .. [#] Specifically, GeoDjango provides support for the `OGR <http://gdal.org/ogr>`_ library, a component of GDAL. 
     1238.. [#] The datum shifting files are needed for converting data to and from 
     1239       certain projections. 
     1240       For example, the PROJ.4 string for the `Google projection (900913) 
     1241       <http://spatialreference.org/ref/epsg/900913/proj4>`_ requires the 
     1242       ``null`` grid file only included in the extra datum shifting files. 
     1243       It is easier to install the shifting files now, then to have debug a 
     1244       problem caused by their absence later. 
     1245.. [#] Specifically, GeoDjango provides support for the `OGR 
     1246       <http://gdal.org/ogr>`_ library, a component of GDAL. 
    12431247.. [#] See `GDAL ticket #2382 <http://trac.osgeo.org/gdal/ticket/2382>`_. 
    1244 .. [#] GeoDjango uses the `find_library <http://docs.python.org/library/ctypes.html#finding-shared-libraries>`_ 
    1245        routine from ``ctypes.util`` to locate shared libraries. 
     1248.. [#] GeoDjango uses the :func:`~ctypes.util.find_library` routine from 
     1249       :mod:`ctypes.util` to locate shared libraries. 
    12461250.. [#] The ``psycopg2`` Windows installers are packaged and maintained by 
    12471251       `Jason Erickson <http://www.stickpeople.com/projects/python/win-psycopg/>`_. 
  • docs/ref/contrib/syndication.txt

     
    852852 
    853853    All parameters, if given, should be Unicode objects, except: 
    854854 
    855         * ``pubdate`` should be a `Python datetime object`_. 
    856         * ``enclosure`` should be an instance of ``feedgenerator.Enclosure``. 
     855        * ``pubdate`` should be a Python  :class:`~datetime.datetime` object. 
     856        * ``enclosure`` should be an instance of 
     857          :class:`django.utils.feedgenerator.Enclosure`. 
    857858        * ``categories`` should be a sequence of Unicode objects. 
    858859 
    859860:meth:`.SyndicationFeed.write` 
     
    884885    </feed> 
    885886 
    886887.. _django/utils/feedgenerator.py: http://code.djangoproject.com/browser/django/trunk/django/utils/feedgenerator.py 
    887 .. _Python datetime object: http://docs.python.org/library/datetime.html#datetime-objects 
    888888 
    889889.. currentmodule:: django.contrib.syndication 
    890890 
     
    913913 
    914914``SyndicationFeed.add_root_elements(self, handler)`` 
    915915    Callback to add elements inside the root feed element 
    916     (``feed``/``channel``). ``handler`` is an `XMLGenerator`_ from Python's 
    917     built-in SAX library; you'll call methods on it to add to the XML 
    918     document in process. 
     916    (``feed``/``channel``). ``handler`` is an 
     917    :class:`~xml.sax.saxutils.XMLGenerator` from Python's built-in SAX library; 
     918    you'll call methods on it to add to the XML document in process. 
    919919 
    920920``SyndicationFeed.item_attributes(self, item)`` 
    921921    Return a ``dict`` of attributes to add to each item (``item``/``entry``) 
     
    945945 
    946946Obviously there's a lot more work to be done for a complete custom feed class, 
    947947but the above example should demonstrate the basic idea. 
    948  
    949 .. _XMLGenerator: http://docs.python.org/dev/library/xml.sax.utils.html#xml.sax.saxutils.XMLGenerator 
  • docs/ref/contrib/csrf.txt

     
    1414a site with someone else's credentials, is also covered. 
    1515 
    1616The first defense against CSRF attacks is to ensure that GET requests (and other 
    17 'safe' methods, as defined by `9.1.1 Safe Methods, HTTP 1.1, RFC 2616`_) are 
    18 side-effect free.  Requests via 'unsafe' methods, such as POST, PUT and DELETE, 
    19 can then be protected by following the steps below. 
     17'safe' methods, as defined by 9.1.1 Safe Methods, HTTP 1.1, 
     18:rfc:`2616#section-9.1.1`) are side-effect free. Requests via 'unsafe' methods, 
     19such as POST, PUT and DELETE, can then be protected by following the steps 
     20below. 
    2021 
    2122.. _Cross Site Request Forgeries: http://www.squarefree.com/securitytips/web-developers.html#CSRF 
    22 .. _9.1.1 Safe Methods, HTTP 1.1, RFC 2616: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html 
    2323 
    2424.. _using-csrf: 
    2525 
     
    228228to POST data back. 
    229229 
    230230It deliberately ignores GET requests (and other requests that are defined as 
    231 'safe' by RFC 2616). These requests ought never to have any potentially 
     231'safe' by :rfc:`2616`). These requests ought never to have any potentially 
    232232dangerous side effects , and so a CSRF attack with a GET request ought to be 
    233 harmless. RFC 2616 defines POST, PUT and DELETE as 'unsafe', and all other 
     233harmless. :rfc:`2616` defines POST, PUT and DELETE as 'unsafe', and all other 
    234234methods are assumed to be unsafe, for maximum protection. 
    235235 
    236236Caching 
  • docs/ref/request-response.txt

     
    196196    Returns the originating host of the request using information from the 
    197197    ``HTTP_X_FORWARDED_HOST`` and ``HTTP_HOST`` headers (in that order). If 
    198198    they don't provide a value, the method uses a combination of 
    199     ``SERVER_NAME`` and ``SERVER_PORT`` as detailed in `PEP 333`_. 
     199    ``SERVER_NAME`` and ``SERVER_PORT`` as detailed in :pep:`3333`. 
    200200 
    201     .. _PEP 333: http://www.python.org/dev/peps/pep-0333/ 
    202  
    203201    Example: ``"127.0.0.1:8000"`` 
    204202 
    205203    .. note:: The :meth:`~HttpRequest.get_host()` method fails when the host is 
     
    645643    ``expires``, and the auto-calculation of ``max_age`` in such case 
    646644    was added. The ``httponly`` argument was also added. 
    647645 
    648     Sets a cookie. The parameters are the same as in the `cookie Morsel`_ 
     646    Sets a cookie. The parameters are the same as in the :class:`Cookie.Morsel` 
    649647    object in the Python standard library. 
    650648 
    651649        * ``max_age`` should be a number of seconds, or ``None`` (default) if 
     
    664662          JavaScript from having access to the cookie. 
    665663 
    666664          HTTPOnly_ is a flag included in a Set-Cookie HTTP response 
    667           header. It is not part of the RFC2109 standard for cookies, 
     665          header. It is not part of the :rfc:`2109` standard for cookies, 
    668666          and it isn't honored consistently by all browsers. However, 
    669667          when it is honored, it can be a useful way to mitigate the 
    670668          risk of client side script accessing the protected cookie 
    671669          data. 
    672670 
    673     .. _`cookie Morsel`: http://docs.python.org/library/cookie.html#Cookie.Morsel 
    674671    .. _HTTPOnly: http://www.owasp.org/index.php/HTTPOnly 
    675672 
    676673.. method:: HttpResponse.set_signed_cookie(key, value='', salt='', max_age=None, expires=None, path='/', domain=None, secure=None, httponly=False) 
  • docs/ref/unicode.txt

     
    148148Web frameworks have to deal with URLs (which are a type of IRI_). One 
    149149requirement of URLs is that they are encoded using only ASCII characters. 
    150150However, in an international environment, you might need to construct a 
    151 URL from an IRI_ -- very loosely speaking, a URI that can contain Unicode 
     151URL from an IRI_ -- very loosely speaking, a URI_ that can contain Unicode 
    152152characters. Quoting and converting an IRI to URI can be a little tricky, so 
    153153Django provides some assistance. 
    154154 
    155155    * The function ``django.utils.encoding.iri_to_uri()`` implements the 
    156       conversion from IRI to URI as required by the specification (`RFC 
    157       3987`_). 
     156      conversion from IRI to URI as required by the specification (:rfc:`3987`). 
    158157 
    159158    * The functions ``django.utils.http.urlquote()`` and 
    160159      ``django.utils.http.urlquote_plus()`` are versions of Python's standard 
     
    203202 
    204203.. _URI: http://www.ietf.org/rfc/rfc2396.txt 
    205204.. _IRI: http://www.ietf.org/rfc/rfc3987.txt 
    206 .. _RFC 3987: IRI_ 
    207205 
    208206Models 
    209207====== 
  • docs/ref/django-admin.txt

     
    455455.. django-admin-option:: --ignore 
    456456 
    457457Use the ``--ignore`` or ``-i`` option to ignore files or directories matching 
    458 the given `glob-style pattern`_. Use multiple times to ignore more. 
     458the given :mod:`glob`-style pattern. Use multiple times to ignore more. 
    459459 
    460460These patterns are used by default: ``'CVS'``, ``'.*'``, ``'*~'`` 
    461461 
     
    463463 
    464464    django-admin.py makemessages --locale=en_US --ignore=apps/* --ignore=secret/*.html 
    465465 
    466 .. _`glob-style pattern`: http://docs.python.org/library/glob.html 
    467  
    468466.. django-admin-option:: --no-default-ignore 
    469467 
    470468Use the ``--no-default-ignore`` option to disable the default values of 
  • docs/ref/settings.txt

     
    10101010Default: ``None`` 
    10111011 
    10121012The numeric mode (i.e. ``0644``) to set newly uploaded files to. For 
    1013 more information about what these modes mean, see the `documentation for 
    1014 os.chmod`_ 
     1013more information about what these modes mean, see the documentation for 
     1014:func:`os.chmod`. 
    10151015 
    10161016If this isn't given or is ``None``, you'll get operating-system 
    10171017dependent behavior. On most platforms, temporary files will have a mode 
     
    10281028    get totally incorrect behavior. 
    10291029 
    10301030 
    1031 .. _documentation for os.chmod: http://docs.python.org/library/os.html#os.chmod 
    1032  
    10331031.. setting:: FILE_UPLOAD_TEMP_DIR 
    10341032 
    10351033FILE_UPLOAD_TEMP_DIR 
     
    15861584session cookie. 
    15871585 
    15881586HTTPOnly_ is a flag included in a Set-Cookie HTTP response header. It 
    1589 is not part of the RFC2109 standard for cookies, and it isn't honored 
     1587is not part of the :rfc:`2109` standard for cookies, and it isn't honored 
    15901588consistently by all browsers. However, when it is honored, it can be a 
    15911589useful way to mitigate the risk of client side script accessing the 
    15921590protected cookie data. 
  • docs/ref/utils.txt

     
    2121header of response objects directly and decorators that change functions to do 
    2222that header-patching themselves. 
    2323 
    24 For information on the ``Vary`` header, see `RFC 2616 section 14.44`_. 
     24For information on the ``Vary`` header, see :rfc:`2616#section-14.44` section 
     2514.44. 
    2526 
    26 .. _RFC 2616 section 14.44: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.44 
    27  
    2827Essentially, the ``Vary`` HTTP header defines which headers a cache should take 
    2928into account when building its cache key. Requests with the same path but 
    3029different header content for headers named in ``Vary`` need to get different 
     
    179178    Convert an Internationalized Resource Identifier (IRI) portion to a URI 
    180179    portion that is suitable for inclusion in a URL. 
    181180 
    182     This is the algorithm from section 3.1 of `RFC 3987`_.  However, since we 
    183     are assuming input is either UTF-8 or unicode already, we can simplify 
    184     things a little from the full method. 
     181    This is the algorithm from section 3.1 of :rfc:`3987#section-3.1`. However, 
     182    since we are assuming input is either UTF-8 or unicode already, we can 
     183    simplify things a little from the full method. 
    185184 
    186     .. _RFC 3987: http://www.ietf.org/rfc/rfc3987.txt 
    187  
    188185    Returns an ASCII string containing the encoded result. 
    189186 
    190187``django.utils.feedgenerator`` 
     
    397394 
    398395.. function:: http_date(epoch_seconds=None) 
    399396 
    400     Formats the time to match the RFC 1123 date format as specified by HTTP 
    401     `RFC 2616`_ section 3.3.1. 
     397    Formats the time to match the :rfc:`1123` date format as specified by HTTP 
     398    :rfc:`2616#section-3.3.1` section 3.3.1. 
    402399 
    403     .. _RFC 2616: http://www.w3.org/Protocols/rfc2616/rfc2616.txt 
    404  
    405400    Accepts a floating point number expressed in seconds since the epoch in 
    406401    UTC--such as that outputted by ``time.time()``. If set to ``None``, 
    407402    defaults to the current time. 
  • docs/conf.py

     
    2626 
    2727# Add any Sphinx extension module names here, as strings. They can be extensions 
    2828# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. 
    29 extensions = ["djangodocs"] 
     29extensions = ["djangodocs", "sphinx.ext.intersphinx"] 
    3030 
    3131# Add any paths that contain templates here, relative to this directory. 
    3232# templates_path = [] 
     
    9292# Note: exclude_dirnames is new in Sphinx 0.5 
    9393exclude_dirnames = ['.svn'] 
    9494 
     95# Links to Python's docs should reference the most recent version of the 2.x 
     96# branch, which is located at this URL. 
     97intersphinx_mapping = { 
     98    'python': ('http://docs.python.org/2.7', None), 
     99    'sphinx': ('http://sphinx.pocoo.org/', None), 
     100} 
     101 
     102# Python's docs don't change every week. 
     103intersphinx_cache_limit = 90 # days 
     104 
    95105# -- Options for HTML output --------------------------------------------------- 
    96106 
    97107# The theme to use for HTML and HTML Help pages.  See the documentation for