diff --git a/docs/internals/documentation.txt b/docs/internals/documentation.txt index ebd62b9a6c4..b89b296540d 100644 --- a/docs/internals/documentation.txt +++ b/docs/internals/documentation.txt @@ -28,12 +28,12 @@ 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 later, which greatly + +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. @@ -45,39 +45,39 @@ Besides the `Sphinx built-in markup`__, Django's docs defines some extra descrip __ 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 @@ -86,25 +86,25 @@ An example For a quick example of how it all fits together, check this out: * First, the ``ref/settings.txt`` document starts out like this:: - + .. _ref-settings: Available settings ================== - + ... - + * Next, if you look at the ``topics/settings.txt`` document, you can see how a link to ``ref/settings`` works:: - + Available settings ================== For a full list of available settings, see the :ref:`settings reference `. - + * Next, notice how the settings (right now just the top few) are annotated:: - + .. setting:: ADMIN_FOR ADMIN_FOR @@ -115,14 +115,14 @@ For a quick example of how it all fits together, check this out: 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 @@ -134,45 +134,45 @@ The work is mostly done, but here's what's left, in rough order of priority. this TODO item my permission and license) into ``topics/generic-views.txt``; remove the intro material from ``ref/generic-views.txt`` and just leave the function reference. - + * Change the "Added/changed in development version" callouts to proper Sphinx ``.. versionadded::`` or ``.. versionchanged::`` directives. - + * Check for and fix malformed links. Do this by running ``make linkcheck`` and fix all of the 300+ errors/warnings. - - In particular, look at all the relative links; these need to be + + In particular, look at all the relative links; these need to be changed to proper references. - + * 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. - + 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. @@ -189,14 +189,14 @@ Some hints for making things look/read better: "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```). - + (``: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