Django-1.2.1/docs/internals/documentation.txt

   1 .. _internals-documentation:
   2
   3 How the Django documentation works
   4 ==================================
   5
   6 \... and how to contribute.
   7
   8 Django's documentation uses the Sphinx__ documentation system, which in turn is
   9 based on docutils__. The basic idea is that lightly-formatted plain-text
  10 documentation is transformed into HTML, PDF, and any other output format.
  11
  12 __ http://sphinx.pocoo.org/
  13 __ http://docutils.sourceforge.net/
  14
  15 To actually build the documentation locally, you'll currently need to install
  16 Sphinx -- ``easy_install Sphinx`` should do the trick.
  17
  18 Then, building the html is easy; just ``make html`` from the ``docs`` directory.
  19
  20 To get started contributing, you'll want to read the `ReStructuredText
  21 Primer`__. After that, you'll want to read about the `Sphinx-specific markup`__
  22 that's used to manage metadata, indexing, and cross-references.
  23
  24 __ http://sphinx.pocoo.org/rest.html
  25 __ http://sphinx.pocoo.org/markup/
  26
  27 The main thing to keep in mind as you write and edit docs is that the more
  28 semantic markup you can add the better. So::
  29
  30     Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...
  31
  32 Isn't nearly as helpful as::
  33
  34     Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...
  35
  36 This is because Sphinx will generate proper links for the latter, which greatly
  37 helps readers. There's basically no limit to the amount of useful markup you can
  38 add.
  39
  40 Django-specific markup
  41 ----------------------
  42
  43 Besides the `Sphinx built-in markup`__, Django's docs defines some extra description units:
  44
  45 __ http://sphinx.pocoo.org/markup/desc.html
  46
  47     * Settings::
  48
  49             .. setting:: INSTALLED_APPS
  50
  51       To link to a setting, use ``:setting:`INSTALLED_APPS```.
  52
  53     * Template tags::
  54
  55             .. templatetag:: regroup
  56
  57       To link, use ``:ttag:`regroup```.
  58
  59     * Template filters::
  60
  61             .. templatefilter:: linebreaksbr
  62
  63       To link, use ``:tfilter:`linebreaksbr```.
  64
  65     * Field lookups (i.e. ``Foo.objects.filter(bar__exact=whatever)``)::
  66
  67             .. fieldlookup:: exact
  68
  69       To link, use ``:lookup:`exact```.
  70
  71     * ``django-admin`` commands::
  72
  73             .. django-admin:: syncdb
  74
  75       To link, use ``:djadmin:`syncdb```.
  76
  77     * ``django-admin`` command-line options::
  78
  79             .. django-admin-option:: --traceback
  80
  81       To link, use ``:djadminopt:`--traceback```.
  82
  83 An example
  84 ----------
  85
  86 For a quick example of how it all fits together, check this out:
  87
  88     * First, the ``ref/settings.txt`` document starts out like this::
  89
  90         .. _ref-settings:
  91
  92         Available settings
  93         ==================
  94
  95         ...
  96
  97     * Next, if you look at the ``topics/settings.txt`` document, you can see how
  98       a link to ``ref/settings`` works::
  99
 100         Available settings
 101         ==================
 102
 103         For a full list of available settings, see the :ref:`settings reference
 104         <ref-settings>`.
 105
 106     * Next, notice how the settings (right now just the top few) are annotated::
 107
 108         .. setting:: ADMIN_FOR
 109
 110         ADMIN_FOR
 111         ---------
 112
 113         Default: ``()`` (Empty tuple)
 114
 115         Used for admin-site settings modules, this should be a tuple of settings
 116         modules (in the format ``'foo.bar.baz'``) for which this site is an
 117         admin.
 118
 119         The admin site uses this in its automatically-introspected
 120         documentation of models, views and template tags.
 121
 122       This marks up the following header as the "canonical" target for the
 123       setting ``ADMIN_FOR`` This means any time I talk about ``ADMIN_FOR``, I
 124       can reference it using ``:setting:`ADMIN_FOR```.
 125
 126 That's basically how everything fits together.
 127
 128 TODO
 129 ----
 130
 131 The work is mostly done, but here's what's left, in rough order of priority.
 132
 133     * Most of the various ``index.txt`` documents have *very* short or even
 134       non-existent intro text. Each of those documents needs a good short intro
 135       the content below that point.
 136
 137     * The glossary is very perfunctory. It needs to be filled out.
 138
 139     * Add more metadata targets: there's lots of places that look like::
 140
 141             ``File.close()``
 142             ~~~~~~~~~~~~~~~~
 143
 144       \... these should be::
 145
 146             .. method:: File.close()
 147
 148       That is, use metadata instead of titles.
 149
 150     * Add more links -- nearly everything that's an inline code literal
 151       right now can probably be turned into a xref.
 152
 153       See the ``literals_to_xrefs.py`` file in ``_ext`` -- it's a shell script
 154       to help do this work.
 155
 156       This will probably be a continuing, never-ending project.
 157
 158     * Add `info field lists`__ where appropriate.
 159
 160       __ http://sphinx.pocoo.org/markup/desc.html#info-field-lists
 161
 162     * Add ``.. code-block:: <lang>`` to literal blocks so that they get
 163       highlighted.
 164
 165 Hints
 166 -----
 167
 168 Some hints for making things look/read better:
 169
 170     * Whenever possible, use links. So, use ``:setting:`ADMIN_FOR``` instead of
 171       ````ADMIN_FOR````.
 172
 173     * Some directives (``.. setting::``, for one) are prefix-style directives;
 174       they go *before* the unit they're describing. These are known as
 175       "crossref" directives. Others (``.. class::``, e.g.) generate their own
 176       markup; these should go inside the section they're describing. These are
 177       called "description units".
 178
 179       You can tell which are which by looking at in :file:`_ext/djangodocs.py`;
 180       it registers roles as one of the other.
 181
 182     * When referring to classes/functions/modules, etc., you'll want to use the
 183       fully-qualified name of the target
 184       (``:class:`django.contrib.contenttypes.models.ContentType```).
 185
 186       Since this doesn't look all that awesome in the output -- it shows the
 187       entire path to the object -- you can prefix the target with a ``~``
 188       (that's a tilde) to get just the "last bit" of that path. So
 189       ``:class:`~django.contrib.contenttypes.models.ContentType``` will just
 190       display a link with the title "ContentType".