diff options
Diffstat (limited to 'parts/django/docs/internals/documentation.txt')
| -rw-r--r-- | parts/django/docs/internals/documentation.txt | 221 |
1 files changed, 221 insertions, 0 deletions
diff --git a/parts/django/docs/internals/documentation.txt b/parts/django/docs/internals/documentation.txt new file mode 100644 index 0000000..36270ea --- /dev/null +++ b/parts/django/docs/internals/documentation.txt @@ -0,0 +1,221 @@ +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". |