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
|
=================================
A Guide to NumPy/SciPy Docstrings
=================================
.. Contents::
Overview
--------
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.
Obviously, it is highly desireable that both NumPy and SciPy 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-dev list together with the epydoc
output so they may be discussed.
Our docstring standard uses `reST <http://docutils.sourceforge.net/rst.html>`__
syntax and is rendered using `epydoc <http://epydoc.sourceforge.net/>`__. 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. So
here standard definition lists are used instead. Likewise, epydoc moves
headings and have an unwelcome size in the default style sheet, hence they
have also been 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:**
4. **Returns:**'
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
extremely useful, but needs to be used with caution. It can be difficult
to maintain and if not used judiciously this section can quickly loose its
usefulness. The purpose of this section is to direct users to other
functions they may not be aware of or have easy means to discover (i.e.,
by looking at the docstring of the module). Thus, repeating functions
that are in the same module is not useful and can create a cluttered
document. Routines that provide additional information in their
docstrings for this function may be useful to include here.
7. **Notes:**
An optional section that provides additional information
about the code possibly including a discussion or presentation 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. (Comment by Chuck:
blank lines in the numpy output, for instance in multidimensional arrays,
will break doctest.) You can run the tests by doing::
>>> import doctest
>>> doctest.testfile('example.py')
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 eydoc 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.
Example
-------
Here is a short example module in
`plain text <http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py>`__
and
`rendered <http://svn.scipy.org/svn/numpy/trunk/numpy/doc/html/index.html>`__
To try this yourself, simply download the example.py::
svn co http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py .
You can run epydoc on this file like so::
$ epydoc example.txt
The output will be in a directory named html in the same directory as this
document and may be viewed by loading the index.html file into your browser.
|
