1 How the Django documentation works

     2 ==================================

     3 

     4 \... and how to contribute.

     5 

     6 Django's documentation uses the Sphinx__ documentation system, which in turn is

     7 based on docutils__. The basic idea is that lightly-formatted plain-text

     8 documentation is transformed into HTML, PDF, and any other output format.

     9 

    10 __ http://sphinx.pocoo.org/

    11 __ http://docutils.sourceforge.net/

    12 

    13 To actually build the documentation locally, you'll currently need to install

    14 Sphinx -- ``easy_install Sphinx`` should do the trick.

    15 

    16 .. note::

    17 

    18     The Django documentation can be generated with Sphinx version 0.6 or

    19     newer, but we recommend using Sphinx 1.0.2 or newer.

    20 

    21 Then, building the HTML is easy; just ``make html`` from the ``docs`` directory.

    22 

    23 To get started contributing, you'll want to read the `reStructuredText

    24 Primer`__. After that, you'll want to read about the `Sphinx-specific markup`__

    25 that's used to manage metadata, indexing, and cross-references.

    26 

    27 __ http://sphinx.pocoo.org/rest.html

    28 __ http://sphinx.pocoo.org/markup/

    29 

    30 The main thing to keep in mind as you write and edit docs is that the more

    31 semantic markup you can add the better. So::

    32 

    33     Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...

    34 

    35 Isn't nearly as helpful as::

    36 

    37     Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...

    38 

    39 This is because Sphinx will generate proper links for the latter, which greatly

    40 helps readers. There's basically no limit to the amount of useful markup you can

    41 add.

    42 

    43 Django-specific markup

    44 ----------------------

    45 

    46 Besides the `Sphinx built-in markup`__, Django's docs defines some extra description units:

    47 

    48 __ http://sphinx.pocoo.org/markup/desc.html

    49 

    50     * Settings::

    51 

    52             .. setting:: INSTALLED_APPS

    53 

    54       To link to a setting, use ``:setting:`INSTALLED_APPS```.

    55 

    56     * Template tags::

    57 

    58             .. templatetag:: regroup

    59 

    60       To link, use ``:ttag:`regroup```.

    61 

    62     * Template filters::

    63 

    64             .. templatefilter:: linebreaksbr

    65 

    66       To link, use ``:tfilter:`linebreaksbr```.

    67 

    68     * Field lookups (i.e. ``Foo.objects.filter(bar__exact=whatever)``)::

    69 

    70             .. fieldlookup:: exact

    71 

    72       To link, use ``:lookup:`exact```.

    73 

    74     * ``django-admin`` commands::

    75 

    76             .. django-admin:: syncdb

    77 

    78       To link, use ``:djadmin:`syncdb```.

    79 

    80     * ``django-admin`` command-line options::

    81 

    82             .. django-admin-option:: --traceback

    83 

    84       To link, use ``:djadminopt:`--traceback```.

    85 

    86 An example

    87 ----------

    88 

    89 For a quick example of how it all fits together, consider this hypothetical

    90 example:

    91 

    92     * First, the ``ref/settings.txt`` document could have an overall layout

    93       like this:

    94 

    95       .. code-block:: rst

    96 

    97         ========

    98         Settings

    99         ========

   100 

   101         ...

   102 

   103         .. _available-settings:

   104 

   105         Available settings

   106         ==================

   107 

   108         ...

   109 

   110         .. _deprecated-settings:

   111 

   112         Deprecated settings

   113         ===================

   114 

   115         ...

   116 

   117     * Next, the ``topics/settings.txt`` document could contain something like

   118       this:

   119 

   120       .. code-block:: rst

   121 

   122         You can access a :ref:`listing of all available settings

   123         <available-settings>`. For a list of deprecated settings see

   124         :ref:`deprecated-settings`.

   125 

   126         You can find both in the :doc:`settings reference document </ref/settings>`.

   127 

   128       We use the Sphinx doc_ cross reference element when we want to link to

   129       another document as a whole and the ref_ element when we want to link to

   130       an arbitrary location in a document.

   131 

   132 .. _doc: http://sphinx.pocoo.org/markup/inline.html#role-doc

   133 .. _ref: http://sphinx.pocoo.org/markup/inline.html#role-ref

   134 

   135     * Next, notice how the settings are annotated:

   136 

   137       .. code-block:: rst

   138 

   139         .. setting:: ADMIN_FOR

   140 

   141         ADMIN_FOR

   142         ---------

   143 

   144         Default: ``()`` (Empty tuple)

   145 

   146         Used for admin-site settings modules, this should be a tuple of settings

   147         modules (in the format ``'foo.bar.baz'``) for which this site is an

   148         admin.

   149 

   150         The admin site uses this in its automatically-introspected

   151         documentation of models, views and template tags.

   152 

   153       This marks up the following header as the "canonical" target for the

   154       setting ``ADMIN_FOR`` This means any time I talk about ``ADMIN_FOR``, I

   155       can reference it using ``:setting:`ADMIN_FOR```.

   156 

   157 That's basically how everything fits together.

   158 

   159 TODO

   160 ----

   161 

   162 The work is mostly done, but here's what's left, in rough order of priority.

   163 

   164     * Most of the various ``index.txt`` documents have *very* short or even

   165       non-existent intro text. Each of those documents needs a good short intro

   166       the content below that point.

   167 

   168     * The glossary is very perfunctory. It needs to be filled out.

   169 

   170     * Add more metadata targets: there's lots of places that look like::

   171 

   172             ``File.close()``

   173             ~~~~~~~~~~~~~~~~

   174 

   175       \... these should be::

   176 

   177             .. method:: File.close()

   178 

   179       That is, use metadata instead of titles.

   180 

   181     * Add more links -- nearly everything that's an inline code literal

   182       right now can probably be turned into a xref.

   183 

   184       See the ``literals_to_xrefs.py`` file in ``_ext`` -- it's a shell script

   185       to help do this work.

   186 

   187       This will probably be a continuing, never-ending project.

   188 

   189     * Add `info field lists`__ where appropriate.

   190 

   191       __ http://sphinx.pocoo.org/markup/desc.html#info-field-lists

   192 

   193     * Add ``.. code-block:: <lang>`` to literal blocks so that they get

   194       highlighted.

   195 

   196 Hints

   197 -----

   198 

   199 Some hints for making things look/read better:

   200 

   201     * Whenever possible, use links. So, use ``:setting:`ADMIN_FOR``` instead of

   202       ````ADMIN_FOR````.

   203 

   204     * Some directives (``.. setting::``, for one) are prefix-style directives;

   205       they go *before* the unit they're describing. These are known as

   206       "crossref" directives. Others (``.. class::``, e.g.) generate their own

   207       markup; these should go inside the section they're describing. These are

   208       called "description units".

   209 

   210       You can tell which are which by looking at in :file:`_ext/djangodocs.py`;

   211       it registers roles as one of the other.

   212 

   213     * When referring to classes/functions/modules, etc., you'll want to use the

   214       fully-qualified name of the target

   215       (``:class:`django.contrib.contenttypes.models.ContentType```).

   216 

   217       Since this doesn't look all that awesome in the output -- it shows the

   218       entire path to the object -- you can prefix the target with a ``~``

   219       (that's a tilde) to get just the "last bit" of that path. So

   220       ``:class:`~django.contrib.contenttypes.models.ContentType``` will just

   221       display a link with the title "ContentType".