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