How the Django documentation works

==================================

\... and how to contribute.

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

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

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

__ http://sphinx.pocoo.org/

__ http://docutils.sourceforge.net/

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

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

.. note::

    The Django documentation can be generated with Sphinx version 0.6 or

    newer, but we recommend using Sphinx 1.0.2 or newer.

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

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

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

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

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

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

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

semantic markup you can add the better. So::

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

Isn't nearly as helpful as::

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

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

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

add.

Django-specific markup

----------------------

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

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

    * Settings::

            .. setting:: INSTALLED_APPS

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

    * Template tags::

            .. templatetag:: regroup

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

    * Template filters::

            .. templatefilter:: linebreaksbr

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

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

            .. fieldlookup:: exact

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

    * ``django-admin`` commands::

            .. django-admin:: syncdb

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

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

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

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

An example

----------

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

example:

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

      like this:

      .. code-block:: rst

        ========

        Settings

        ========

        ...

        .. _available-settings:

        Available settings

        ==================

        ...

        .. _deprecated-settings:

        Deprecated settings

        ===================

        ...

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

      this:

      .. code-block:: rst

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

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

        :ref:`deprecated-settings`.

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

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

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

      an arbitrary location in a document.

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

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

    * Next, notice how the settings are annotated:

      .. code-block:: rst

        .. setting:: ADMIN_FOR

        ADMIN_FOR

        ---------

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

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

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

        admin.

        The admin site uses this in its automatically-introspected

        documentation of models, views and template tags.

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

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

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

That's basically how everything fits together.

TODO

----

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

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

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

      the content below that point.

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

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

            ``File.close()``

            ~~~~~~~~~~~~~~~~

      \... these should be::

            .. method:: File.close()

      That is, use metadata instead of titles.

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

      right now can probably be turned into a xref.

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

      to help do this work.

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

    * Add `info field lists`__ where appropriate.

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

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

      highlighted.

Hints

-----

Some hints for making things look/read better:

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

      ````ADMIN_FOR````.

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

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

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

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

      called "description units".

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

      it registers roles as one of the other.

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

      fully-qualified name of the target

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

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

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

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

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

      display a link with the title "ContentType".