diff options
Diffstat (limited to 'docs/internals/documentation.txt')
| -rw-r--r-- | docs/internals/documentation.txt | 55 |
1 files changed, 43 insertions, 12 deletions
diff --git a/docs/internals/documentation.txt b/docs/internals/documentation.txt index 81480abf9a..63f248d3a9 100644 --- a/docs/internals/documentation.txt +++ b/docs/internals/documentation.txt @@ -1,5 +1,3 @@ -.. _internals-documentation: - How the Django documentation works ================================== @@ -15,6 +13,11 @@ __ 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:: + + Generation of the Django documentation will work with Sphinx version 0.6 + or newer, but we recommend going straigh to 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 @@ -83,27 +86,55 @@ __ http://sphinx.pocoo.org/markup/desc.html An example ---------- -For a quick example of how it all fits together, check this out: +For a quick example of how it all fits together, consider this hypothetical +example: - * First, the ``ref/settings.txt`` document starts out like this:: + * First, the ``ref/settings.txt`` document could have an overall layout + like this: - .. _ref-settings: + .. code-block:: rst - Available settings - ================== + ======== + Settings + ======== ... - * Next, if you look at the ``topics/settings.txt`` document, you can see how - a link to ``ref/settings`` works:: + .. _available-settings: Available settings ================== - For a full list of available settings, see the :ref:`settings reference - <ref-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: - * Next, notice how the settings (right now just the top few) are annotated:: + .. code-block:: rst .. setting:: ADMIN_FOR |