/docs/internals/documentation.txt

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