/docs/internals/documentation.txt

Relevant Search: With Applications for Solr and Elasticsearch

For more in depth reading about search, ranking and generally everything you could ever want to know about how lucene, elasticsearch or solr work under the hood I highly suggest this book. Easily one of the most interesting technical books I have read in a long time. If you are tasked with solving search relevance problems even if not in Solr or Elasticsearch it should be your first reference. Amazon Affiliate Link

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