-
-
Notifications
You must be signed in to change notification settings - Fork 9.9k
/
HOWTO_DOCUMENT.txt
430 lines (308 loc) · 13.1 KB
/
HOWTO_DOCUMENT.txt
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
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
====================================
A Guide to NumPy/SciPy Documentation
====================================
.. Contents::
.. Note::
For an accompanying example, see `example.py
<http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py>`_.
Overview
--------
In general, we follow the standard Python style conventions as described here:
* `Style Guide for C Code <http://www.python.org/peps/pep-0007.html>`_
* `Style Guide for Python Code <http://www.python.org/peps/pep-0008.html>`_
* `Docstring Conventions <http://www.python.org/peps/pep-0257.html>`_
Additional PEPs of interest regarding documentation of code:
* `Docstring Processing Framework <http://www.python.org/peps/pep-0256.html>`_
* `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_
Use a code checker:
* `pylint <http://www.logilab.org/857>`_
* `pyflakes` easy_install pyflakes
* `pep8.py <http://svn.browsershots.org/trunk/devtools/pep8/pep8.py>`_
The following import conventions are used throughout the NumPy source
and documentation::
import numpy as np
import scipy as sp
import matplotlib as mpl
import matplotlib.pyplot as plt
It is not necessary to do ``import numpy as np`` at the beginning of
an example. However, some sub-modules, such as ``fft``, are not
imported by default, and you have to include them explicitly::
import numpy.fft
after which you may use it::
np.fft.fft2(...)
Docstring Standard
------------------
A documentation string (docstring) is a string that describes a module,
function, class, or method definition. The docstring is a special attribute
of the object (``object.__doc__``) and, for consistency, is surrounded by
triple double quotes, i.e.::
"""This is the form of a docstring.
It can be spread over several lines.
"""
NumPy, SciPy_, and the scikits follow a common convention for
docstrings that provides for consistency, while also allowing our
toolchain to produce well-formatted reference guides. This document
describes the current community consensus for such a standard. If you
have suggestions for improvements, post them on the `numpy-discussion
list`_, together with the epydoc output.
Our docstring standard uses `re-structured text (reST)
<http://docutils.sourceforge.net/rst.html>`_ syntax and is rendered
using tools like epydoc_ or sphinx_ (pre-processors that understand
the particular documentation style we are using). While a rich set of
markup is available, we limit ourselves to a very basic subset, in
order to provide docstrings that are easy to read on text-only
terminals.
A guiding principle is that human readers of the text are given
precedence over contorting docstrings so our tools produce nice
output. Rather than sacrificing the readability of the docstrings, we
have written pre-processors to assist tools like epydoc_ and sphinx_ in
their task.
Status
------
We are busy converting existing docstrings to the new format,
expanding them where they are lacking, as well as writing new ones for
undocumented functions. Volunteers are welcome to join the effort on
our new documentation system (see the `Developer Zone
<http://www.scipy.org/Developer_Zone/DocMarathon2008>`_).
Sections
--------
The sections of the docstring are:
1. **Short summary**
A one-line summary that does not use variable names or the function
name, e.g.
::
def add(a,b):
"""The sum of two numbers.
"""
The function signature is normally found by introspection and
displayed by the help function. For some functions (notably those
written in C) the signature is not available, so we have to specify
it as the first line of the docstring::
"""
add(a,b)
The sum of two numbers.
"""
2. **Extended summary**
A few sentences giving an extended description. This section
should be used to clarify *functionality*, not to discuss
implementation detail or background theory, which should rather be
explored in the **notes** section below. You may refer to the
parameters and the function name, but parameter descriptions still
belong in the **parameters** section.
3. **Parameters**
Description of the function arguments, keywords and their
respective types.
::
Parameters
----------
x : type
Description of parameter `x`.
Enclose variables in single back-tics. If it is not necessary to
specify a keyword argument, use ``optional``::
x : int, optional
Optional keyword parameters have default values, which are
displayed as part of the function signature. They can also be
detailed in the description::
Description of parameter `x` (the default is -1, which implies summation
over all axes).
When a parameter can only assume one of a fixed set of values,
those values can be listed in braces ::
x : {True, False}
Description of `x`.
4. **Returns**
Explanation of the returned values and their types, of the same
format as **parameters**.
5. **Other parameters**
An optional section used to describe infrequently used parameters.
It should only be used if a function has a large number of keyword
prameters, to prevent cluttering the **parameters** section.
6. **Raises**
An optional section detailing which errors get raised and under
what conditions::
Raises
------
LinAlgException
If the matrix is not numerically invertible.
7. **See Also**
An optional section used to refer to related code. This section
can be very useful, but should be used judiciously. The goal is to
direct users to other functions they may not be aware of, or have
easy means of discovering (by looking at the module docstring, for
example). Routines whose docstrings further explain parameters
used by this function are good candidates.
As an example, for ``numpy.mean`` we would have::
See Also
--------
average : Weighted average
When referring to functions in the same sub-module, no prefix is
needed, and the tree is searched upwards for a match.
Prefix functions from other sub-modules appropriately. E.g.,
whilst documenting the ``random`` module, refer to a function in
``fft`` by
::
fft.fft2 : 2-D fast discrete Fourier transform
When referring to an entirely different module::
scipy.random.norm : Random variates, PDFs, etc.
Functions may be listed without descriptions::
See Also
--------
func_a : Function a with its description.
func_b, func_c_, func_d
func_e
8. **Notes**
An optional section that provides additional information about the
code, possibly including a discussion of the algorithm. This
section may include mathematical equations, written in
`LaTeX <http://www.latex-project.org/>`_ format::
The FFT is a fast implementation of the discrete Fourier transform:
.. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
Equations can also be typeset underneath the math directive::
The discrete-time Fourier time-convolution property states that
.. math::
x(n) * y(n) \Leftrightarrow X(e^{j\omega } )Y(e^{j\omega } )\\
another equation here
Math can furthermore be used inline, i.e.
::
The value of :math:`\omega` is larger than 5.
Variable names are displayed in typewriter font, obtained by using
``\mathtt{var}``::
We square the input parameter `alpha` to obtain
:math:`\mathtt{alpha}^2`.
Note that LaTeX is not particularly easy to read, so use equations
sparingly.
Images are allowed, but should not be central to the explanation;
users viewing the docstring as text must be able to comprehend its
meaning without resorting to an image viewer. These additional
illustrations are included using::
.. image:: filename
where filename is a path relative to the reference guide source
directory.
9. **References**
References cited in the **notes** section may be listed here,
e.g. if you cited the article below using the text ``[1]_``,
include it as in the list as follows::
.. [1] O. McNoleg, "The integration of GIS, remote sensing,
expert systems and adaptive co-kriging for environmental habitat
modelling of the Highland Haggis using object-oriented, fuzzy-logic
and neural-network techniques," Computers & Geosciences, vol. 22,
pp. 585-588, 1996.
which renders as
.. [1] O. McNoleg, "The integration of GIS, remote sensing,
expert systems and adaptive co-kriging for environmental habitat
modelling of the Highland Haggis using object-oriented, fuzzy-logic
and neural-network techniques," Computers & Geosciences, vol. 22,
pp. 585-588, 1996.
Referencing sources of a temporary nature, like web pages, is
discouraged. References are meant to augment the docstring, but
should not be required to understand it. Follow the `citation
format of the IEEE
<http://www.ieee.org/pubs/transactions/auinfo03.pdf>`_, which
states that references are numbered, starting from one, in the
order in which they are cited.
10. **Examples**
An optional section for examples, using the `doctest
<http://www.python.org/doc/lib/module-doctest.html>`_ format.
This section is meant to illustrate usage, not to provide a
testing framework -- for that, use the ``tests/`` directory.
While optional, this section is very strongly encouraged. You can
run these examples by doing::
>>> import doctest
>>> doctest.testfile('example.py')
or, using nose,
::
$ nosetests --with-doctest example.py
Blank lines are used to seperate doctests. When they occur in the
expected output, they should be replaced by ``<BLANKLINE>`` (see
`doctest options
<http://docs.python.org/lib/doctest-options.html>`_ for other such
special strings), e.g.
::
>>> print "a\n\nb"
a
<BLANKLINE>
b
The examples may assume that ``import numpy as np`` is executed before
the example code in *numpy*, and ``import scipy as sp`` in *scipy*.
Additional examples may make use of *matplotlib* for plotting, but should
import it explicitly, e.g., ``import matplotlib.pyplot as plt``.
11. **Indexing tags***
Each function needs to be categorised for indexing purposes. Use
the ``index`` directive::
.. index::
:refguide: ufunc, trigonometry
To index a function as a sub-category of a class, separate index
entries by a colon, e.g.
::
:refguide: ufunc, numpy:reshape, other
A `list of available categories
<http://www.scipy.org/Developer_Zone/ReferenceGuide>`_ is
available.
Documenting classes
-------------------
Class docstring
```````````````
Use the same sections as outlined above (all except ``Returns`` are
applicable). The constructor (``__init__``) should also be documented
here.
An ``Attributes`` section may be used to describe class variables::
Attributes
----------
x : float
The X coordinate.
y : float
The Y coordinate.
In general, it is not necessary to list class methods. Those that are
not part of the public API have names that start with an underscore.
In some cases, however, a class may have a great many methods, of
which only a few are relevant (e.g., subclasses of ndarray). Then, it
becomes useful to have an additional ``Methods`` section::
class Photo(ndarray):
"""
Array with associated photographic information.
...
Attributes
----------
exposure : float
Exposure in seconds.
Methods
-------
colorspace(c='rgb')
Represent the photo in the given colorspace.
gamma(n=1.0)
Change the photo's gamma exposure.
"""
Note that `self` is *not* listed as the first parameter of methods.
Method docstrings
`````````````````
Document these as you would any other function. Do not include
``self`` in the list of parameters.
Common reST concepts
--------------------
For paragraphs, indentation is significant and indicates indentation in the
output. New paragraphs are marked with a blank line.
Use *italics*, **bold**, and ``courier`` if needed in any explanations
(but not for variable names and doctest code or multi-line code).
Variable, module and class names should be written between single
backticks (```numpy```).
A more extensive example of reST markup can be found in `this example
document <http://docutils.sourceforge.net/docs/user/rst/demo.txt>`_;
the `quick reference
<http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_ is
useful while editing.
Line spacing and indentation are significant and should be carefully
followed.
Conclusion
----------
`An example
<http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py>`_ of the
format shown here is available. Refer to `How to Build API/Reference
Documentation
<http://svn.scipy.org/svn/numpy/trunk/numpy/doc/HOWTO_BUILD_DOCS.txt>`_
on how to use epydoc_ or sphinx_ to construct a manual and web page.
This document itself was written in ReStructuredText, and may be converted to
HTML using::
$ rst2html HOWTO_DOCUMENT.txt HOWTO_DOCUMENT.html
.. _SciPy: http://www.scipy.org
.. _numpy-discussion list: http://www.scipy.org/Mailing_Lists
.. _epydoc: http://epydoc.sourceforge.net/
.. _sphinx: http://sphinx.pocoo.org