1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
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::
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
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".
|
