← Back to branch summary

~drizzle-trunk/drizzle/development

« back to all changes in this revision

Viewing changes to docs/contributing/documentation.rst

  • Committer: Monty Taylor
  • Date: 2011-02-13 17:26:39 UTC
  • mfrom: (2157.2.2 give-in-to-pkg-config)
  • mto: This revision was merged to the branch mainline in revision 2166.
  • Revision ID: mordred@inaugust.com-20110213172639-nhy7i72sfhoq13ms
Merged in pkg-config fixes.

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.