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
|
====================================
A Guide to NumPy/SciPy Documentation
====================================
.. Contents::
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>`__
Common import standards::
import numpy as np
import scipy as sp
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.
It is highly desireable that both NumPy and SciPy_ and scikits to
follow a common
convention for docstrings that provide for consistency while also
allowing epydoc_ to produce nicely-formatted reference guides. This
document describes the current community consensus for this standard.
If you have suggestions for improvements, post them on the
`numpy-discussion list`_, together with the epydoc output.
Our docstring standard uses `reST
<http://docutils.sourceforge.net/rst.html>`__ syntax and is rendered
using epydoc_. The markup in this proposal is as basic as possible
and, in particular, avoids the use of epydoc consolidated fields. This
is both because there are a limited number of such fields, inadequate
to our current needs, and because epydoc moves the fields to the end
of the documentation, messing up the ordering. Standard definition
lists are used instead. Likewise, epydoc moves headings and have an
unwelcome size in the default style sheet, therefore they are also
avoided.
Status
------
We are currently trying to:
1. Agree on docstring standards.
2. Work with Ed loper to ensure that epydoc_ provides the functionality
we need.
3. Convert existing docstrings to the new format and write them for
those that currently lack docstrings.
Sections
--------
The proposed sections of the docstring are:
1. **Short summary:**
A one-line summary not using variable names or the function name
(unless a C-function).
2. **Extended summary:**
A few sentences giving an extended description.
3. **Parameters:**
Description of the function arguments, keywords and their
respective types.
4. **Returns:**
Explanation of the returned values and their types.
5. **Other parameters:**
An optional section used to describe little used parameters so that
functions with a large number of keyword argument can still be well
documented without cluttering the main parameters' list.
6. **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.
7. **Notes:**
An optional section that provides additional information about the
code, possibly including a discussion of the algorithm. This
section may include mathematical equations, possibly written in
`LaTeX <http://www.latex-project.org/>`__.
8. **Examples:**
An optional section for examples, using the `doctest
<http://www.python.org/doc/lib/module-doctest.html>`__ format. It
can provide an inline mini-tutorial as well as additional
regression testing. While optional, this section is strongly
encouraged. You can run the tests by doing::
>>> import doctest
>>> doctest.testfile('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>`_), e.g.
::
>>> print "a\n\nb"
a
<BLANKLINE>
b
Common reST concepts
--------------------
A reST-documented module should define::
__docformat__ = 'restructuredtext en'
at the top level in accordance with `PEP 258
<http://www.python.org/dev/peps/pep-0258>`__. Note that the
``__docformat__`` variable in a package's ``__init__.py`` file does
not apply to objects defined in subpackages and submodules.
For paragraphs, indentation is significant and indicates indentation in the
output. New paragraphs are marked with blank line.
Use *italics*, **bold**, and ``courier`` if needed in any explanations (but
not for variable names and doctest code or multi-line code)
Use ``:lm:`eqn``` for in-line math in latex format (remember to use the
raw-format for your text string or escape any '\' symbols). Use ``:m:`eqn```
for non-latex math.
A more extensive example of reST markup can be found here:
http://docutils.sourceforge.net/docs/user/rst/demo.txt
Line spacing and indentation are significant and should
be carefully followed.
Using Epydoc_
-------------
Currently, we recommend that you build epydoc from the trunk::
svn co https://epydoc.svn.sourceforge.net/svnroot/epydoc/trunk/epydoc epydoc
cd epydoc/src
sudo python setup.py install
The appearance of some elements can be changed in the epydoc.css
style sheet. The list headings, i.e. *Parameters*:, are emphasized text, so
their appearance is controlled by the definition of the <em>
tag. For instance, to make them bold, insert::
em {font-weight: bold;}
The variables' types are in a span of class rst-classifier, hence can be
changed by inserting something like::
span.rst-classifier {font-weight: normal;}
The first line of the signature should **not** copy the signature unless
the function is written in C, in which case it is mandatory. If the function
signature is generic (uses ``*args`` or ``**kwds``), then a function signature
may be included.
Use optional in the "type" field for parameters that are non-keyword
optional for C-functions.
Epydoc depends on Docutils for reStructuredText parsing. You can download
Docutils from the
`Docutils sourceforge page. <http://docutils.sourceforge.net/>`__
You may also be able to use a package manager like yum to install a
current version::
$ sudo yum install python-docutils
Example
-------
Here is a short example module,
`plain text <http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py>`__
or
`rendered <http://www.scipy.org/doc/example>`__ in HTML.
To try this yourself, simply download the example.py::
svn co http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py .
Then, run epydoc::
$ epydoc example.py
The output is placed in ``./html``, and may be viewed by loading the
``index.html`` file into your browser.
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/
|
