← Back to branch summary

~drizzle-trunk/drizzle/development

« back to all changes in this revision

Viewing changes to docs/contributing/documentation.rst

  • Committer: pcrews
  • Date: 2011-05-24 17:36:24 UTC
  • mfrom: (1099.4.232 drizzle)
  • Revision ID: pcrews@lucid32-20110524173624-mwr1bvq6fa1r01ao
Updated translations + 2011.05.18 tarball tag

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/contributing/documentation.rst
 
1
.. _documentation-label:
 
2
 
 
3
Contributing Documentation
 
4
==========================
 
5
 
 
6
Our documentation is written using
 
7
`Sphinx Documentation Generator <http://sphinx.pocoo.org/>`_
 
8
which uses the `reStructuredText <http://docutils.sf.net/rst.html>`_ format.
 
9
 
 
10
All our documentation is stored in the main source reposatory in the docs/
 
11
directory, and every merge into trunk triggers a rebuild of our
 
12
`documentation site <http://docs.drizzle.org/>`_.
 
13
 
 
14
Requirements
 
15
------------
 
16
 
 
17
We require a minimum of python-sphinx 0.6 to compile the documentation but not
 
18
all of it will build correctly in that version.  For correct documentation
 
19
version 1.0 is required.
 
20
 
 
21
When building the documentation warnings are treated as errors, so the documentation
 
22
needs to be warning free in 1.0.
 
23
 
 
24
Documentation Files
 
25
-------------------
 
26
 
 
27
The documentation files have the .rst extension and are stored in the ``docs/``
 
28
directory.
 
29
 
 
30
Contents
 
31
^^^^^^^^
 
32
 
 
33
To add a new document to the contents you will need to add it to a relevent
 
34
section in the ``docs/index.rst`` file.
 
35
 
 
36
Plugins
 
37
^^^^^^^
 
38
 
 
39
To document plugins you need to create a ``docs/`` subdirectory in your plugin
 
40
directory containing an index.rst file.  This will be automatically added during
 
41
the ``config/autorun.sh`` phase.
 
42
 
 
43
Documentation Format
 
44
--------------------
 
45
 
 
46
The documentation is in the reStructured text format which is a wiki-like markup
 
47
language ideal for documentation.
 
48
 
 
49
Headings
 
50
^^^^^^^^
 
51
 
 
52
Headings take the form of just the text with a diffent style of underline to
 
53
signify the level, for example:
 
54
 
 
55
.. code-block:: rest
 
56
   
 
57
   Heading Level 1
 
58
   ===============
 
59
 
 
60
   Heading Level 2
 
61
   ---------------
 
62
 
 
63
   Heading Level 3
 
64
   ^^^^^^^^^^^^^^^
 
65
 
 
66
Tables
 
67
^^^^^^
 
68
 
 
69
There are two ways of generating a table, the first is basically drawing the
 
70
entire table in ascii art as follows:
 
71
 
 
72
.. code-block:: rest
 
73
 
 
74
   +----+--------+-----+
 
75
   | ID | name   | age |
 
76
   +====+========+=====+
 
77
   | 1  | Fred   | 23  |
 
78
   +----+--------+-----+
 
79
   | 2  | Joe    | 48  |
 
80
   +----+--------+-----+
 
81
   | 3  | Sophie | 32  |
 
82
   +----+--------+-----+
 
83
 
 
84
Which generates:
 
85
 
 
86
+----+--------+-----+
 
87
| ID | name   | age |
 
88
+====+========+=====+
 
89
| 1  | Fred   | 23  |
 
90
+----+--------+-----+
 
91
| 2  | Joe    | 48  |
 
92
+----+--------+-----+
 
93
| 3  | Sophie | 32  |
 
94
+----+--------+-----+
 
95
 
 
96
As an alternative there is a simplified form as follows:
 
97
 
 
98
.. code-block:: rest
 
99
 
 
100
   ----- ----- ------
 
101
     A     B   Result
 
102
   ===== ===== ======
 
103
   False False False
 
104
   False True  True
 
105
   True  False True
 
106
   True  True  False
 
107
   ===== ===== =====
 
108
 
 
109
Gives this table:
 
110
 
 
111
===== ===== ======
 
112
  A     B   Result
 
113
===== ===== ======
 
114
False False False
 
115
False True  True
 
116
True  False True
 
117
True  True  False
 
118
===== ===== ======
 
119
 
 
120
In this form there must be more than one row to the table and the first column
 
121
can only have a single line.
 
122
 
 
123
Syntax Highlighting
 
124
^^^^^^^^^^^^^^^^^^^
 
125
 
 
126
Sphinx supports syntax highlighting using the `Pygments <http://pygments.org/>`_
 
127
engine.  For example, with the *mysql* syntax highlighter you can do the
 
128
following:
 
129
 
 
130
.. code-block:: rest
 
131
 
 
132
   .. code-block:: mysql
 
133
 
 
134
      SELECT * FROM t1 WHERE a=1;
 
135
 
 
136
Which will generate:
 
137
 
 
138
.. code-block:: mysql
 
139
 
 
140
   SELECT * FROM t1 WHERE a=1;
 
141
 
 
142
You can also add line numbers as follows:
 
143
 
 
144
.. code-block:: rest
 
145
 
 
146
   .. code-block:: c
 
147
      :linenos:
 
148
 
 
149
      #include <stdio.h>
 
150
 
 
151
      main()
 
152
      {
 
153
        printf("hello world");
 
154
      }
 
155
 
 
156
Which will generate:
 
157
 
 
158
.. code-block:: c
 
159
   :linenos:
 
160
 
 
161
   #include <stdio.h>
 
162
 
 
163
   main()
 
164
   {
 
165
     printf("hello world");
 
166
   }
 
167
 
 
168
.. seealso::
 
169
 
 
170
   `Pygments Demo <http://pygments.org/demo/>`_ - A demo of the available syntax
 
171
   highlighting types.
 
172
 
 
173
Footnotes
 
174
^^^^^^^^^
 
175
 
 
176
Footnotes in their most simple form can be generated using ``[1]_`` in the text
 
177
and then a section of the bottom of the page as follows [1]_:
 
178
 
 
179
.. code-block:: rest
 
180
 
 
181
   .. rubric:: Footnotes
 
182
 
 
183
   .. [1] Like this
 
184
 
 
185
Which generates:
 
186
 
 
187
.. rubric:: Footnotes
 
188
 
 
189
.. [1] Like this
 
190
 
 
191
Notes, Warnings, Todo and See Also
 
192
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
193
 
 
194
Notes, warnings and todos all take similar forms:
 
195
 
 
196
.. code-block:: rest
 
197
 
 
198
   .. note::
 
199
      This is a note
 
200
 
 
201
   .. warning::
 
202
      This is a warning
 
203
 
 
204
   .. todo::
 
205
      This is a todo
 
206
 
 
207
   .. seealso::
 
208
      This is a See Also
 
209
 
 
210
Which generates:
 
211
 
 
212
.. note::
 
213
   This is a note
 
214
 
 
215
.. warning::
 
216
   This is a warning
 
217
 
 
218
.. todo::
 
219
   This is a todo
 
220
 
 
221
.. seealso::
 
222
   This is a See Also
 
223
 
 
224
Summary
 
225
^^^^^^^
 
226
 
 
227
.. seealso::
 
228
 
 
229
   * `Sphinx documentation <http://sphinx.pocoo.org/contents.html>`_
 
230
   * `Openalea Sphinx Cheatsheet <http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_syntax.html>`_
 
231
 
 
232
Building Documentation
 
233
----------------------
 
234
 
 
235
The documentation is compiled from the ``.rst`` files during ``make``, but to
 
236
create HTML files from this you will need to run ``make html``.
 
237
 
 
238
To see other possible formats run ``make sphinx-help``.
 
239
 
 
240
Committing Documentation
 
241
------------------------
 
242
 
 
243
Documentation needs to be committed and merged in exactly the same way as
 
244
regular development files.  For more information on this please see the
 
245
:ref:`contributing code <code-label>` page.