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