--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/parts/django/docs/internals/documentation.txt Sat Jan 08 11:20:57 2011 +0530
@@ -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".