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".