/docs/internals/documentation.txt

https://code.google.com/p/mango-py/ · Plain Text · 225 lines · 140 code · 85 blank · 0 comment · 0 complexity · edd7228a908c887c1900473d7f14e11e MD5 · raw file

  1. How the Django documentation works
  2. ==================================
  3. \... and how to contribute.
  4. Django's documentation uses the Sphinx__ documentation system, which in turn is
  5. based on docutils__. The basic idea is that lightly-formatted plain-text
  6. documentation is transformed into HTML, PDF, and any other output format.
  7. __ http://sphinx.pocoo.org/
  8. __ http://docutils.sourceforge.net/
  9. To actually build the documentation locally, you'll currently need to install
  10. Sphinx -- ``easy_install Sphinx`` should do the trick.
  11. .. note::
  12. Building the Django documentation requires Sphinx 1.0.2 or newer. Sphinx
  13. also requires the Pygments__ library for syntax highlighting; building the
  14. Django documentation requires Pygments 1.1 or newer (a new-enough version
  15. should automatically be installed along with Sphinx).
  16. __ http://pygments.org
  17. Then, building the HTML is easy; just ``make html`` from the ``docs`` directory.
  18. To get started contributing, you'll want to read the `reStructuredText
  19. Primer`__. After that, you'll want to read about the `Sphinx-specific markup`__
  20. that's used to manage metadata, indexing, and cross-references.
  21. __ http://sphinx.pocoo.org/rest.html
  22. __ http://sphinx.pocoo.org/markup/
  23. The main thing to keep in mind as you write and edit docs is that the more
  24. semantic markup you can add the better. So::
  25. Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...
  26. Isn't nearly as helpful as::
  27. Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...
  28. This is because Sphinx will generate proper links for the latter, which greatly
  29. helps readers. There's basically no limit to the amount of useful markup you can
  30. add.
  31. Django-specific markup
  32. ----------------------
  33. Besides the `Sphinx built-in markup`__, Django's docs defines some extra description units:
  34. __ http://sphinx.pocoo.org/markup/desc.html
  35. * Settings::
  36. .. setting:: INSTALLED_APPS
  37. To link to a setting, use ``:setting:`INSTALLED_APPS```.
  38. * Template tags::
  39. .. templatetag:: regroup
  40. To link, use ``:ttag:`regroup```.
  41. * Template filters::
  42. .. templatefilter:: linebreaksbr
  43. To link, use ``:tfilter:`linebreaksbr```.
  44. * Field lookups (i.e. ``Foo.objects.filter(bar__exact=whatever)``)::
  45. .. fieldlookup:: exact
  46. To link, use ``:lookup:`exact```.
  47. * ``django-admin`` commands::
  48. .. django-admin:: syncdb
  49. To link, use ``:djadmin:`syncdb```.
  50. * ``django-admin`` command-line options::
  51. .. django-admin-option:: --traceback
  52. To link, use ``:djadminopt:`--traceback```.
  53. An example
  54. ----------
  55. For a quick example of how it all fits together, consider this hypothetical
  56. example:
  57. * First, the ``ref/settings.txt`` document could have an overall layout
  58. like this:
  59. .. code-block:: rst
  60. ========
  61. Settings
  62. ========
  63. ...
  64. .. _available-settings:
  65. Available settings
  66. ==================
  67. ...
  68. .. _deprecated-settings:
  69. Deprecated settings
  70. ===================
  71. ...
  72. * Next, the ``topics/settings.txt`` document could contain something like
  73. this:
  74. .. code-block:: rst
  75. You can access a :ref:`listing of all available settings
  76. <available-settings>`. For a list of deprecated settings see
  77. :ref:`deprecated-settings`.
  78. You can find both in the :doc:`settings reference document </ref/settings>`.
  79. We use the Sphinx doc_ cross reference element when we want to link to
  80. another document as a whole and the ref_ element when we want to link to
  81. an arbitrary location in a document.
  82. .. _doc: http://sphinx.pocoo.org/markup/inline.html#role-doc
  83. .. _ref: http://sphinx.pocoo.org/markup/inline.html#role-ref
  84. * Next, notice how the settings are annotated:
  85. .. code-block:: rst
  86. .. setting:: ADMIN_FOR
  87. ADMIN_FOR
  88. ---------
  89. Default: ``()`` (Empty tuple)
  90. Used for admin-site settings modules, this should be a tuple of settings
  91. modules (in the format ``'foo.bar.baz'``) for which this site is an
  92. admin.
  93. The admin site uses this in its automatically-introspected
  94. documentation of models, views and template tags.
  95. This marks up the following header as the "canonical" target for the
  96. setting ``ADMIN_FOR`` This means any time I talk about ``ADMIN_FOR``, I
  97. can reference it using ``:setting:`ADMIN_FOR```.
  98. That's basically how everything fits together.
  99. TODO
  100. ----
  101. The work is mostly done, but here's what's left, in rough order of priority.
  102. * Most of the various ``index.txt`` documents have *very* short or even
  103. non-existent intro text. Each of those documents needs a good short intro
  104. the content below that point.
  105. * The glossary is very perfunctory. It needs to be filled out.
  106. * Add more metadata targets: there's lots of places that look like::
  107. ``File.close()``
  108. ~~~~~~~~~~~~~~~~
  109. \... these should be::
  110. .. method:: File.close()
  111. That is, use metadata instead of titles.
  112. * Add more links -- nearly everything that's an inline code literal
  113. right now can probably be turned into a xref.
  114. See the ``literals_to_xrefs.py`` file in ``_ext`` -- it's a shell script
  115. to help do this work.
  116. This will probably be a continuing, never-ending project.
  117. * Add `info field lists`__ where appropriate.
  118. __ http://sphinx.pocoo.org/markup/desc.html#info-field-lists
  119. * Add ``.. code-block:: <lang>`` to literal blocks so that they get
  120. highlighted.
  121. Hints
  122. -----
  123. Some hints for making things look/read better:
  124. * Whenever possible, use links. So, use ``:setting:`ADMIN_FOR``` instead of
  125. ````ADMIN_FOR````.
  126. * Some directives (``.. setting::``, for one) are prefix-style directives;
  127. they go *before* the unit they're describing. These are known as
  128. "crossref" directives. Others (``.. class::``, e.g.) generate their own
  129. markup; these should go inside the section they're describing. These are
  130. called "description units".
  131. You can tell which are which by looking at in :file:`_ext/djangodocs.py`;
  132. it registers roles as one of the other.
  133. * When referring to classes/functions/modules, etc., you'll want to use the
  134. fully-qualified name of the target
  135. (``:class:`django.contrib.contenttypes.models.ContentType```).
  136. Since this doesn't look all that awesome in the output -- it shows the
  137. entire path to the object -- you can prefix the target with a ``~``
  138. (that's a tilde) to get just the "last bit" of that path. So
  139. ``:class:`~django.contrib.contenttypes.models.ContentType``` will just
  140. display a link with the title "ContentType".