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