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:: Building the Django documentation requires Sphinx 1.0.2 or newer. Sphinx also requires the Pygments__ library for syntax highlighting; building the Django documentation requires Pygments 1.1 or newer (a new-enough version should automatically be installed along with Sphinx). __ http://pygments.org 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 `. For a list of deprecated settings see :ref:`deprecated-settings`. You can find both in the :doc:`settings reference document `. 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:: `` 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".