Skip to content
Newer
Older
100644 657 lines (478 sloc) 21.4 KB
2aa8f46 @jarrodmillman more on documentation
jarrodmillman authored Oct 2, 2007
1 ====================================
2 A Guide to NumPy/SciPy Documentation
3 ====================================
216a123 @charris Revise HOWTO_DOCUMENT.txt to make it work.
charris authored Aug 28, 2007
4
007331a @jarrodmillman documentation
jarrodmillman authored Sep 23, 2007
5 .. Contents::
216a123 @charris Revise HOWTO_DOCUMENT.txt to make it work.
charris authored Aug 28, 2007
6
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
7 .. Note::
8
9 For an accompanying example, see `example.py
f4a313e @stefanv DOC: Remove more SVN references.
stefanv authored Sep 16, 2010
10 <http://github.com/numpy/numpy/blob/master/doc/example.py>`_.
70d815d @jarrodmillman explanation of current situation
jarrodmillman authored Jan 22, 2008
11
c6b67ff @stefanv DOC: Remove duplicate unique links in HOWTO_DOCUMENT.
stefanv authored May 30, 2012
12 When using `Sphinx <http://sphinx.pocoo.org/>`__ in combination with the
aded70c @charris STY: Fix spelling and reword text.
charris authored Sep 17, 2011
13 numpy conventions, you should use the ``numpydoc`` extension so that your
14 docstrings will be handled correctly. For example, Sphinx will extract the
15 ``Parameters`` section from your docstring and convert it into a field
ec116c4 @chebee7i DOC: Mention numpydoc 0.6.
chebee7i authored Feb 14, 2015
16 list. Using ``numpydoc`` will also avoid the reStructuredText errors produced
aded70c @charris STY: Fix spelling and reword text.
charris authored Sep 17, 2011
17 by plain Sphinx when it encounters numpy docstring conventions like
18 section headers (e.g. ``-------------``) that sphinx does not expect to
19 find in docstrings.
81bf485 @esc DOC: mention numpydoc in numpy conventions
esc authored Sep 14, 2011
20
ec116c4 @chebee7i DOC: Mention numpydoc 0.6.
chebee7i authored Feb 14, 2015
21 Some features described in this document require a recent version of
22 ``numpydoc``. For example, the **Yields** section was added in
23 ``numpydoc`` 0.6.
24
81bf485 @esc DOC: mention numpydoc in numpy conventions
esc authored Sep 14, 2011
25 It is available from:
26
27 * `numpydoc on PyPI <http://pypi.python.org/pypi/numpydoc>`_
d10c9ff @takluyver MAINT: Update links to numpydoc source code and README
takluyver authored Nov 14, 2013
28 * `numpydoc on GitHub <https://github.com/numpy/numpydoc/>`_
81bf485 @esc DOC: mention numpydoc in numpy conventions
esc authored Sep 14, 2011
29
30 Details of how to use it can be found `here
43dcd32 @takluyver MAINT: Update link to numpydoc README
takluyver authored Jan 7, 2014
31 <https://github.com/numpy/numpydoc/blob/master/README.rst>`__ and
81bf485 @esc DOC: mention numpydoc in numpy conventions
esc authored Sep 14, 2011
32 `here
c6b67ff @stefanv DOC: Remove duplicate unique links in HOWTO_DOCUMENT.
stefanv authored May 30, 2012
33 <https://github.com/numpy/numpy/blob/master/doc/HOWTO_BUILD_DOCS.rst.txt>`__
81bf485 @esc DOC: mention numpydoc in numpy conventions
esc authored Sep 14, 2011
34
007331a @jarrodmillman documentation
jarrodmillman authored Sep 23, 2007
35 Overview
36 --------
e8a4358 @oztalha DOC: fix PEP links in HOWTO_DOCUMENT.rst.txt
oztalha authored Jul 18, 2014
37 We mostly follow the standard Python style conventions as described here:
38 * `Style Guide for C Code <http://python.org/dev/peps/pep-0007/>`_
39 * `Style Guide for Python Code <http://python.org/dev/peps/pep-0008/>`_
40 * `Docstring Conventions <http://python.org/dev/peps/pep-0257/>`_
2aa8f46 @jarrodmillman more on documentation
jarrodmillman authored Oct 2, 2007
41
42 Additional PEPs of interest regarding documentation of code:
e8a4358 @oztalha DOC: fix PEP links in HOWTO_DOCUMENT.rst.txt
oztalha authored Jul 18, 2014
43 * `Docstring Processing Framework <http://python.org/dev/peps/pep-0256/>`_
44 * `Docutils Design Specification <http://python.org/dev/peps/pep-0258/>`_
2aa8f46 @jarrodmillman more on documentation
jarrodmillman authored Oct 2, 2007
45
46 Use a code checker:
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
47 * `pylint <http://www.logilab.org/857>`_
e1e021d @migueldvb DOC: Add an example of casting array type and byte order using astype.
migueldvb authored Nov 11, 2013
48 * `pyflakes <https://pypi.python.org/pypi/pyflakes>`_
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
49 * `pep8.py <http://svn.browsershots.org/trunk/devtools/pep8/pep8.py>`_
e1e021d @migueldvb DOC: Add an example of casting array type and byte order using astype.
migueldvb authored Nov 11, 2013
50 * `flake8 <https://pypi.python.org/pypi/flake8>`_
51 * `vim-flake8 <https://github.com/nvie/vim-flake8>`_ plugin for
52 automatically checking syntax and style with flake8
2aa8f46 @jarrodmillman more on documentation
jarrodmillman authored Oct 2, 2007
53
6cdeb71 @stefanv Update documentation standard.
stefanv authored Jun 3, 2008
54 The following import conventions are used throughout the NumPy source
55 and documentation::
b7808b3 @jarrodmillman formatting
jarrodmillman authored Dec 16, 2007
56
57 import numpy as np
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
58 import matplotlib as mpl
59 import matplotlib.pyplot as plt
60
d44e74d @rkern DOC: Remove the advice to 'import scipy as sp' from the documentation.
rkern authored Apr 1, 2011
61 Do not abbreviate ``scipy``. There is no motivating use case to
62 abbreviate it in the real world, so we avoid it in the documentation
63 to avoid confusion.
64
6cdeb71 @stefanv Update documentation standard.
stefanv authored Jun 3, 2008
65 It is not necessary to do ``import numpy as np`` at the beginning of
66 an example. However, some sub-modules, such as ``fft``, are not
67 imported by default, and you have to include them explicitly::
68
69 import numpy.fft
70
71 after which you may use it::
72
73 np.fft.fft2(...)
74
2aa8f46 @jarrodmillman more on documentation
jarrodmillman authored Oct 2, 2007
75 Docstring Standard
76 ------------------
dfc8625 @jarrodmillman more doc work
jarrodmillman authored Sep 23, 2007
77 A documentation string (docstring) is a string that describes a module,
78 function, class, or method definition. The docstring is a special attribute
79 of the object (``object.__doc__``) and, for consistency, is surrounded by
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
80 triple double quotes, i.e.::
dfc8625 @jarrodmillman more doc work
jarrodmillman authored Sep 23, 2007
81
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
82 """This is the form of a docstring.
83
84 It can be spread over several lines.
85
86 """
dfc8625 @jarrodmillman more doc work
jarrodmillman authored Sep 23, 2007
87
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
88 NumPy, SciPy_, and the scikits follow a common convention for
89 docstrings that provides for consistency, while also allowing our
90 toolchain to produce well-formatted reference guides. This document
91 describes the current community consensus for such a standard. If you
92 have suggestions for improvements, post them on the `numpy-discussion
d35eac6 @pv Address #1146: update docstring standard
pv authored Jul 1, 2009
93 list`_.
216a123 @charris Revise HOWTO_DOCUMENT.txt to make it work.
charris authored Aug 28, 2007
94
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
95 Our docstring standard uses `re-structured text (reST)
96 <http://docutils.sourceforge.net/rst.html>`_ syntax and is rendered
d35eac6 @pv Address #1146: update docstring standard
pv authored Jul 1, 2009
97 using Sphinx_ (a pre-processor that understands the particular
98 documentation style we are using). While a rich set of
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
99 markup is available, we limit ourselves to a very basic subset, in
100 order to provide docstrings that are easy to read on text-only
101 terminals.
102
103 A guiding principle is that human readers of the text are given
104 precedence over contorting docstrings so our tools produce nice
105 output. Rather than sacrificing the readability of the docstrings, we
d35eac6 @pv Address #1146: update docstring standard
pv authored Jul 1, 2009
106 have written pre-processors to assist Sphinx_ in its task.
107
108 The length of docstring lines should be kept to 75 characters to
109 facilitate reading the docstrings in text terminals.
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
110
88e1fad @jarrodmillman more documentation work
jarrodmillman authored Sep 23, 2007
111 Sections
112 --------
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
113 The sections of the docstring are:
114
115 1. **Short summary**
116
117 A one-line summary that does not use variable names or the function
118 name, e.g.
007331a @jarrodmillman documentation
jarrodmillman authored Sep 23, 2007
119
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
120 ::
121
47b4791 @stefanv Updates to the documentation standard [patch by Ralf Gommers].
stefanv authored Jun 22, 2009
122 def add(a, b):
4ee16c3 @stefanv Update documentation format and example.
stefanv authored May 16, 2008
123 """The sum of two numbers.
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
124
125 """
126
127 The function signature is normally found by introspection and
128 displayed by the help function. For some functions (notably those
129 written in C) the signature is not available, so we have to specify
130 it as the first line of the docstring::
131
132 """
47b4791 @stefanv Updates to the documentation standard [patch by Ralf Gommers].
stefanv authored Jun 22, 2009
133 add(a, b)
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
134
4ee16c3 @stefanv Update documentation format and example.
stefanv authored May 16, 2008
135 The sum of two numbers.
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
136
137 """
dcac742 @jarrodmillman more documentation
jarrodmillman authored Sep 23, 2007
138
c2081ae @rgommers DOC: add deprecation section to docstandard. Closes #1501.
rgommers authored Mar 25, 2011
139 2. **Deprecation warning**
140
141 A section (use if applicable) to warn users that the object is deprecated.
8ddb0ce @charris STY: Giant whitespace cleanup.
charris authored Aug 18, 2013
142 Section contents should include:
c2081ae @rgommers DOC: add deprecation section to docstandard. Closes #1501.
rgommers authored Mar 25, 2011
143
144 * In what Numpy version the object was deprecated, and when it will be
145 removed.
146
9c02535 @endolith Add note about definition list classifier format
endolith authored Nov 30, 2012
147 * Reason for deprecation if this is useful information (e.g., object
c2081ae @rgommers DOC: add deprecation section to docstandard. Closes #1501.
rgommers authored Mar 25, 2011
148 is superseded, duplicates functionality found elsewhere, etc.).
149
8ddb0ce @charris STY: Giant whitespace cleanup.
charris authored Aug 18, 2013
150 * New recommended way of obtaining the same functionality.
c2081ae @rgommers DOC: add deprecation section to docstandard. Closes #1501.
rgommers authored Mar 25, 2011
151
152 This section should use the note Sphinx directive instead of an
153 underlined section header.
154
155 ::
156
157 .. note:: Deprecated in Numpy 1.6
158 `ndobj_old` will be removed in Numpy 2.0, it is replaced by
159 `ndobj_new` because the latter works also with array subclasses.
160
3d182f0 @chebee7i DOC: Add documentation for Yields section in docstrings.
chebee7i authored Jan 11, 2015
161 3. **Extended Summary**
dcac742 @jarrodmillman more documentation
jarrodmillman authored Sep 23, 2007
162
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
163 A few sentences giving an extended description. This section
164 should be used to clarify *functionality*, not to discuss
165 implementation detail or background theory, which should rather be
3d182f0 @chebee7i DOC: Add documentation for Yields section in docstrings.
chebee7i authored Jan 11, 2015
166 explored in the **Notes** section below. You may refer to the
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
167 parameters and the function name, but parameter descriptions still
3d182f0 @chebee7i DOC: Add documentation for Yields section in docstrings.
chebee7i authored Jan 11, 2015
168 belong in the **Parameters** section.
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
169
c2081ae @rgommers DOC: add deprecation section to docstandard. Closes #1501.
rgommers authored Mar 25, 2011
170 4. **Parameters**
dcac742 @jarrodmillman more documentation
jarrodmillman authored Sep 23, 2007
171
518e9b2 @stefanv Update formatting. Mention how to handle blank lines in doctests.
stefanv authored Sep 25, 2007
172 Description of the function arguments, keywords and their
173 respective types.
dcac742 @jarrodmillman more documentation
jarrodmillman authored Sep 23, 2007
174
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
175 ::
176
177 Parameters
178 ----------
179 x : type
9c02535 @endolith Add note about definition list classifier format
endolith authored Nov 30, 2012
180 Description of parameter `x`.
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
181
8ddb0ce @charris STY: Giant whitespace cleanup.
charris authored Aug 18, 2013
182 Enclose variables in single backticks. The colon must be preceded
9c02535 @endolith Add note about definition list classifier format
endolith authored Nov 30, 2012
183 by a space, or omitted if the type is absent.
8dc4d76 Add a few examples for parameter types in HOWTO_DOCUMENT.
chris.burns authored Oct 24, 2009
184
9c02535 @endolith Add note about definition list classifier format
endolith authored Nov 30, 2012
185 For the parameter types, be as precise as possible. Below are a
8dc4d76 Add a few examples for parameter types in HOWTO_DOCUMENT.
chris.burns authored Oct 24, 2009
186 few examples of parameters and their types.
187
188 ::
189
190 Parameters
191 ----------
192 filename : str
193 copy : bool
194 dtype : data-type
8ddb0ce @charris STY: Giant whitespace cleanup.
charris authored Aug 18, 2013
195 iterable : iterable object
8dc4d76 Add a few examples for parameter types in HOWTO_DOCUMENT.
chris.burns authored Oct 24, 2009
196 shape : int or tuple of int
197 files : list of str
198
199 If it is not necessary to specify a keyword argument, use
200 ``optional``::
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
201
202 x : int, optional
203
204 Optional keyword parameters have default values, which are
205 displayed as part of the function signature. They can also be
206 detailed in the description::
dcac742 @jarrodmillman more documentation
jarrodmillman authored Sep 23, 2007
207
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
208 Description of parameter `x` (the default is -1, which implies summation
209 over all axes).
dcac742 @jarrodmillman more documentation
jarrodmillman authored Sep 23, 2007
210
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
211 When a parameter can only assume one of a fixed set of values,
9c02535 @endolith Add note about definition list classifier format
endolith authored Nov 30, 2012
212 those values can be listed in braces, with the default appearing first::
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
213
8dc4d76 Add a few examples for parameter types in HOWTO_DOCUMENT.
chris.burns authored Oct 24, 2009
214 order : {'C', 'F', 'A'}
215 Description of `order`.
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
216
47b4791 @stefanv Updates to the documentation standard [patch by Ralf Gommers].
stefanv authored Jun 22, 2009
217 When two or more input parameters have exactly the same type, shape and
218 description, they can be combined::
219
220 x1, x2 : array_like
221 Input arrays, description of `x1`, `x2`.
222
c2081ae @rgommers DOC: add deprecation section to docstandard. Closes #1501.
rgommers authored Mar 25, 2011
223 5. **Returns**
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
224
2241e6c @RelentlessIdiot ENH: Allow unnamed return values in Returns section of doc string
RelentlessIdiot authored Jun 25, 2013
225 Explanation of the returned values and their types. Similar to the
3d182f0 @chebee7i DOC: Add documentation for Yields section in docstrings.
chebee7i authored Jan 11, 2015
226 **Parameters** section, except the name of each return value is optional.
2241e6c @RelentlessIdiot ENH: Allow unnamed return values in Returns section of doc string
RelentlessIdiot authored Jun 25, 2013
227 The type of each return value is always required::
228
229 Returns
230 -------
231 int
232 Description of anonymous integer return value.
233
3d182f0 @chebee7i DOC: Add documentation for Yields section in docstrings.
chebee7i authored Jan 11, 2015
234 If both the name and type are specified, the **Returns** section takes the
235 same form as the **Parameters** section::
2241e6c @RelentlessIdiot ENH: Allow unnamed return values in Returns section of doc string
RelentlessIdiot authored Jun 25, 2013
236
237 Returns
238 -------
239 err_code : int
240 Non-zero value indicates error code, or zero on success.
241 err_msg : str or None
242 Human readable error message, or None on success.
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
243
3d182f0 @chebee7i DOC: Add documentation for Yields section in docstrings.
chebee7i authored Jan 11, 2015
244 6. **Yields**
245
246 Explanation of the yielded values and their types. This is relevant to
4eac56a @chebee7i DOC: Clarify documentation for Yields.
chebee7i authored Jan 11, 2015
247 generators only. Similar to the **Returns** section in that the name of
248 each value is optional, but the type of each value is always required::
3d182f0 @chebee7i DOC: Add documentation for Yields section in docstrings.
chebee7i authored Jan 11, 2015
249
250 Yields
251 ------
252 int
253 Description of the anonymous integer return value.
254
4eac56a @chebee7i DOC: Clarify documentation for Yields.
chebee7i authored Jan 11, 2015
255 If both the name and type are specified, the **Yields** section takes the
d64d4a5 @chebee7i DOC: Replace "Parameters" with "Returns".
chebee7i authored Feb 14, 2015
256 same form as the **Returns** section::
3d182f0 @chebee7i DOC: Add documentation for Yields section in docstrings.
chebee7i authored Jan 11, 2015
257
258 Yields
259 ------
260 err_code : int
261 Non-zero value indicates error code, or zero on success.
262 err_msg : str or None
263 Human readable error message, or None on success.
264
ec116c4 @chebee7i DOC: Mention numpydoc 0.6.
chebee7i authored Feb 14, 2015
265 Support for the **Yields** section was added in `numpydoc
266 <https://github.com/numpy/numpydoc>`_ version 0.6.
267
3d182f0 @chebee7i DOC: Add documentation for Yields section in docstrings.
chebee7i authored Jan 11, 2015
268 7. **Other Parameters**
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
269
270 An optional section used to describe infrequently used parameters.
271 It should only be used if a function has a large number of keyword
3d182f0 @chebee7i DOC: Add documentation for Yields section in docstrings.
chebee7i authored Jan 11, 2015
272 parameters, to prevent cluttering the **Parameters** section.
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
273
3d182f0 @chebee7i DOC: Add documentation for Yields section in docstrings.
chebee7i authored Jan 11, 2015
274 8. **Raises**
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
275
276 An optional section detailing which errors get raised and under
277 what conditions::
278
279 Raises
280 ------
281 LinAlgException
282 If the matrix is not numerically invertible.
283
e1e021d @migueldvb DOC: Add an example of casting array type and byte order using astype.
migueldvb authored Nov 11, 2013
284 This section should be used judiciously, i.e., only for errors
d35eac6 @pv Address #1146: update docstring standard
pv authored Jul 1, 2009
285 that are non-obvious or have a large chance of getting raised.
286
3d182f0 @chebee7i DOC: Add documentation for Yields section in docstrings.
chebee7i authored Jan 11, 2015
287 9. **See Also**
5896cb8 Add a Raises section to the docstring suggestions.
Travis Oliphant authored Dec 30, 2007
288
518e9b2 @stefanv Update formatting. Mention how to handle blank lines in doctests.
stefanv authored Sep 25, 2007
289 An optional section used to refer to related code. This section
290 can be very useful, but should be used judiciously. The goal is to
291 direct users to other functions they may not be aware of, or have
292 easy means of discovering (by looking at the module docstring, for
293 example). Routines whose docstrings further explain parameters
294 used by this function are good candidates.
007331a @jarrodmillman documentation
jarrodmillman authored Sep 23, 2007
295
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
296 As an example, for ``numpy.mean`` we would have::
297
298 See Also
299 --------
6cdeb71 @stefanv Update documentation standard.
stefanv authored Jun 3, 2008
300 average : Weighted average
301
302 When referring to functions in the same sub-module, no prefix is
303 needed, and the tree is searched upwards for a match.
304
305 Prefix functions from other sub-modules appropriately. E.g.,
306 whilst documenting the ``random`` module, refer to a function in
307 ``fft`` by
308
309 ::
310
311 fft.fft2 : 2-D fast discrete Fourier transform
312
313 When referring to an entirely different module::
314
315 scipy.random.norm : Random variates, PDFs, etc.
316
47b4791 @stefanv Updates to the documentation standard [patch by Ralf Gommers].
stefanv authored Jun 22, 2009
317 Functions may be listed without descriptions, and this is
318 preferable if the functionality is clear from the function name::
6cdeb71 @stefanv Update documentation standard.
stefanv authored Jun 3, 2008
319
320 See Also
321 --------
322 func_a : Function a with its description.
323 func_b, func_c_, func_d
324 func_e
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
325
3d182f0 @chebee7i DOC: Add documentation for Yields section in docstrings.
chebee7i authored Jan 11, 2015
326 10. **Notes**
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
327
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
328 An optional section that provides additional information about the
329 code, possibly including a discussion of the algorithm. This
330 section may include mathematical equations, written in
331 `LaTeX <http://www.latex-project.org/>`_ format::
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
332
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
333 The FFT is a fast implementation of the discrete Fourier transform:
dfc8625 @jarrodmillman more doc work
jarrodmillman authored Sep 23, 2007
334
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
335 .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
007331a @jarrodmillman documentation
jarrodmillman authored Sep 23, 2007
336
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
337 Equations can also be typeset underneath the math directive::
007331a @jarrodmillman documentation
jarrodmillman authored Sep 23, 2007
338
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
339 The discrete-time Fourier time-convolution property states that
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
340
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
341 .. math::
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
342
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
343 x(n) * y(n) \Leftrightarrow X(e^{j\omega } )Y(e^{j\omega } )\\
344 another equation here
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
345
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
346 Math can furthermore be used inline, i.e.
518e9b2 @stefanv Update formatting. Mention how to handle blank lines in doctests.
stefanv authored Sep 25, 2007
347
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
348 ::
518e9b2 @stefanv Update formatting. Mention how to handle blank lines in doctests.
stefanv authored Sep 25, 2007
349
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
350 The value of :math:`\omega` is larger than 5.
007331a @jarrodmillman documentation
jarrodmillman authored Sep 23, 2007
351
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
352 Variable names are displayed in typewriter font, obtained by using
353 ``\mathtt{var}``::
327a4d2 @stefanv How to use variables in math markup.
stefanv authored Jun 11, 2008
354
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
355 We square the input parameter `alpha` to obtain
356 :math:`\mathtt{alpha}^2`.
327a4d2 @stefanv How to use variables in math markup.
stefanv authored Jun 11, 2008
357
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
358 Note that LaTeX is not particularly easy to read, so use equations
359 sparingly.
007331a @jarrodmillman documentation
jarrodmillman authored Sep 23, 2007
360
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
361 Images are allowed, but should not be central to the explanation;
362 users viewing the docstring as text must be able to comprehend its
363 meaning without resorting to an image viewer. These additional
364 illustrations are included using::
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
365
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
366 .. image:: filename
007331a @jarrodmillman documentation
jarrodmillman authored Sep 23, 2007
367
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
368 where filename is a path relative to the reference guide source
369 directory.
007331a @jarrodmillman documentation
jarrodmillman authored Sep 23, 2007
370
3d182f0 @chebee7i DOC: Add documentation for Yields section in docstrings.
chebee7i authored Jan 11, 2015
371 11. **References**
007331a @jarrodmillman documentation
jarrodmillman authored Sep 23, 2007
372
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
373 References cited in the **notes** section may be listed here,
374 e.g. if you cited the article below using the text ``[1]_``,
375 include it as in the list as follows::
216a123 @charris Revise HOWTO_DOCUMENT.txt to make it work.
charris authored Aug 28, 2007
376
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
377 .. [1] O. McNoleg, "The integration of GIS, remote sensing,
378 expert systems and adaptive co-kriging for environmental habitat
379 modelling of the Highland Haggis using object-oriented, fuzzy-logic
380 and neural-network techniques," Computers & Geosciences, vol. 22,
381 pp. 585-588, 1996.
76ab788 @jarrodmillman more documentation
jarrodmillman authored Sep 23, 2007
382
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
383 which renders as
76ab788 @jarrodmillman more documentation
jarrodmillman authored Sep 23, 2007
384
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
385 .. [1] O. McNoleg, "The integration of GIS, remote sensing,
386 expert systems and adaptive co-kriging for environmental habitat
387 modelling of the Highland Haggis using object-oriented, fuzzy-logic
388 and neural-network techniques," Computers & Geosciences, vol. 22,
389 pp. 585-588, 1996.
88e1fad @jarrodmillman more documentation work
jarrodmillman authored Sep 23, 2007
390
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
391 Referencing sources of a temporary nature, like web pages, is
392 discouraged. References are meant to augment the docstring, but
393 should not be required to understand it. References are numbered, starting
394 from one, in the order in which they are cited.
88e1fad @jarrodmillman more documentation work
jarrodmillman authored Sep 23, 2007
395
3d182f0 @chebee7i DOC: Add documentation for Yields section in docstrings.
chebee7i authored Jan 11, 2015
396 12. **Examples**
88e1fad @jarrodmillman more documentation work
jarrodmillman authored Sep 23, 2007
397
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
398 An optional section for examples, using the `doctest
399 <http://docs.python.org/library/doctest.html>`_ format.
400 This section is meant to illustrate usage, not to provide a
401 testing framework -- for that, use the ``tests/`` directory.
402 While optional, this section is very strongly encouraged.
47b4791 @stefanv Updates to the documentation standard [patch by Ralf Gommers].
stefanv authored Jun 22, 2009
403
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
404 When multiple examples are provided, they should be separated by
405 blank lines. Comments explaining the examples should have blank
406 lines both above and below them::
47b4791 @stefanv Updates to the documentation standard [patch by Ralf Gommers].
stefanv authored Jun 22, 2009
407
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
408 >>> np.add(1, 2)
409 3
d1c740c @rkern Set __docformat__ such that epydoc knows it's looking at reST instead…
rkern authored Jan 22, 2008
410
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
411 Comment explaining the second example
d1c740c @rkern Set __docformat__ such that epydoc knows it's looking at reST instead…
rkern authored Jan 22, 2008
412
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
413 >>> np.add([1, 2], [3, 4])
414 array([4, 6])
efbe398 Improve the documentation style for human-readability in plain-text
Travis Oliphant authored Dec 28, 2007
415
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
416 For tests with a result that is random or platform-dependent, mark the
417 output as such::
ac7bdc5 @rgommers DOC: Update the testing guidelines.
rgommers authored Oct 10, 2010
418
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
419 >>> import numpy.random
420 >>> np.random.rand(2)
421 array([ 0.35773152, 0.38568979]) #random
ac7bdc5 @rgommers DOC: Update the testing guidelines.
rgommers authored Oct 10, 2010
422
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
423 You can run examples as doctests using::
88e1fad @jarrodmillman more documentation work
jarrodmillman authored Sep 23, 2007
424
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
425 >>> np.test(doctests=True)
426 >>> np.linalg.test(doctests=True) # for a single module
416e1ab @rgommers DOC: fix link and add explanation on how to run examples.
rgommers authored Apr 17, 2012
427
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
428 In IPython it is also possible to run individual examples simply by
429 copy-pasting them in doctest mode::
416e1ab @rgommers DOC: fix link and add explanation on how to run examples.
rgommers authored Apr 17, 2012
430
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
431 In [1]: %doctest_mode
432 Exception reporting mode: Plain
433 Doctest mode is: ON
434 >>> %paste
435 import numpy.random
436 np.random.rand(2)
437 ## -- End pasted text --
438 array([ 0.8519522 , 0.15492887])
416e1ab @rgommers DOC: fix link and add explanation on how to run examples.
rgommers authored Apr 17, 2012
439
88e1fad @jarrodmillman more documentation work
jarrodmillman authored Sep 23, 2007
440
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
441 It is not necessary to use the doctest markup ``<BLANKLINE>`` to
442 indicate empty lines in the output. Note that the option to run
443 the examples through ``numpy.test`` is provided for checking if the
444 examples work, not for making the examples part of the testing framework.
88e1fad @jarrodmillman more documentation work
jarrodmillman authored Sep 23, 2007
445
b176572 @JDWarner STY: Fix GitHub rendering of ordered lists >9
JDWarner authored Feb 22, 2016
446 The examples may assume that ``import numpy as np`` is executed before
447 the example code in *numpy*. Additional examples may make use of
448 *matplotlib* for plotting, but should import it explicitly, e.g.,
449 ``import matplotlib.pyplot as plt``. All other imports, including the
450 demonstrated function, must be explicit.
e66e9ca @pv Spell out namespace convention in Examples and See Also sections in d…
pv authored Jun 1, 2008
451
8ddb0ce @charris STY: Giant whitespace cleanup.
charris authored Aug 18, 2013
452
3a917b8 @stefanv Update documentation standard.
stefanv authored Jun 17, 2008
453 Documenting classes
454 -------------------
455
456 Class docstring
457 ```````````````
458 Use the same sections as outlined above (all except ``Returns`` are
459 applicable). The constructor (``__init__``) should also be documented
3d182f0 @chebee7i DOC: Add documentation for Yields section in docstrings.
chebee7i authored Jan 11, 2015
460 here, the **Parameters** section of the docstring details the constructors
d35eac6 @pv Address #1146: update docstring standard
pv authored Jul 1, 2009
461 parameters.
3a917b8 @stefanv Update documentation standard.
stefanv authored Jun 17, 2008
462
3d182f0 @chebee7i DOC: Add documentation for Yields section in docstrings.
chebee7i authored Jan 11, 2015
463 An **Attributes** section, located below the **Parameters** section,
4be3c23 @nevimov DOC: clarify purpose of Attributes section
nevimov authored Apr 28, 2016
464 may be used to describe non-method attributes of the class::
3a917b8 @stefanv Update documentation standard.
stefanv authored Jun 17, 2008
465
466 Attributes
467 ----------
468 x : float
469 The X coordinate.
470 y : float
471 The Y coordinate.
472
d35eac6 @pv Address #1146: update docstring standard
pv authored Jul 1, 2009
473 Attributes that are properties and have their own docstrings can be
474 simply listed by name::
475
476 Attributes
477 ----------
478 real
479 imag
480 x : float
481 The X coordinate
482 y : float
483 The Y coordinate
484
1a4abae @stefanv Add `Methods` section to documentation standard.
stefanv authored Jun 18, 2008
485 In general, it is not necessary to list class methods. Those that are
486 not part of the public API have names that start with an underscore.
487 In some cases, however, a class may have a great many methods, of
488 which only a few are relevant (e.g., subclasses of ndarray). Then, it
3d182f0 @chebee7i DOC: Add documentation for Yields section in docstrings.
chebee7i authored Jan 11, 2015
489 becomes useful to have an additional **Methods** section::
1a4abae @stefanv Add `Methods` section to documentation standard.
stefanv authored Jun 18, 2008
490
491 class Photo(ndarray):
492 """
493 Array with associated photographic information.
494
495 ...
496
497 Attributes
498 ----------
499 exposure : float
500 Exposure in seconds.
501
502 Methods
503 -------
504 colorspace(c='rgb')
505 Represent the photo in the given colorspace.
506 gamma(n=1.0)
507 Change the photo's gamma exposure.
508
509 """
510
d35eac6 @pv Address #1146: update docstring standard
pv authored Jul 1, 2009
511 If it is necessary to explain a private method (use with care!), it can
3d182f0 @chebee7i DOC: Add documentation for Yields section in docstrings.
chebee7i authored Jan 11, 2015
512 be referred to in the **Extended Summary** or the **Notes** section.
513 Do not list private methods in the **methods** section.
d35eac6 @pv Address #1146: update docstring standard
pv authored Jul 1, 2009
514
1a4abae @stefanv Add `Methods` section to documentation standard.
stefanv authored Jun 18, 2008
515 Note that `self` is *not* listed as the first parameter of methods.
516
3a917b8 @stefanv Update documentation standard.
stefanv authored Jun 17, 2008
517 Method docstrings
518 `````````````````
519 Document these as you would any other function. Do not include
c343611 @rgommers DOC: update class method docstring section of docstandard. Closes #1165.
rgommers authored Mar 25, 2011
520 ``self`` in the list of parameters. If a method has an equivalent function
521 (which is the case for many ndarray methods for example), the function
522 docstring should contain the detailed documentation, and the method docstring
8ddb0ce @charris STY: Giant whitespace cleanup.
charris authored Aug 18, 2013
523 should refer to it. Only put brief summary and **See Also** sections in the
3d182f0 @chebee7i DOC: Add documentation for Yields section in docstrings.
chebee7i authored Jan 11, 2015
524 method docstring. The method should use a **Returns** or **Yields** section,
525 as appropriate.
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
526
b11ae17 @rgommers DOC: add description of how to document modules to the doc standard.
rgommers authored Mar 25, 2011
527
d35eac6 @pv Address #1146: update docstring standard
pv authored Jul 1, 2009
528 Documenting class instances
529 ---------------------------
530 Instances of classes that are part of the Numpy API (for example `np.r_`
531 `np,c_`, `np.index_exp`, etc.) may require some care. To give these
532 instances a useful docstring, we do the following:
533
534 * Single instance: If only a single instance of a class is exposed,
535 document the class. Examples can use the instance name.
536
537 * Multiple instances: If multiple instances are exposed, docstrings
538 for each instance are written and assigned to the instances'
539 ``__doc__`` attributes at run time. The class is documented as usual, and
8ddb0ce @charris STY: Giant whitespace cleanup.
charris authored Aug 18, 2013
540 the exposed instances can be mentioned in the **Notes** and **See Also**
d0c0f14 @endolith DOC: use bold for section names, monospace for variables in HOWTO_DOC…
endolith authored Dec 2, 2012
541 sections.
d35eac6 @pv Address #1146: update docstring standard
pv authored Jul 1, 2009
542
b11ae17 @rgommers DOC: add description of how to document modules to the doc standard.
rgommers authored Mar 25, 2011
543
3d182f0 @chebee7i DOC: Add documentation for Yields section in docstrings.
chebee7i authored Jan 11, 2015
544 Documenting generators
545 ----------------------
546 Generators should be documented just as functions are documented. The
547 only difference is that one should use the **Yields** section instead
ec116c4 @chebee7i DOC: Mention numpydoc 0.6.
chebee7i authored Feb 14, 2015
548 of the **Returns** section. Support for the **Yields** section was added in
549 `numpydoc <https://github.com/numpy/numpydoc>`_ version 0.6.
3d182f0 @chebee7i DOC: Add documentation for Yields section in docstrings.
chebee7i authored Jan 11, 2015
550
551
d35eac6 @pv Address #1146: update docstring standard
pv authored Jul 1, 2009
552 Documenting constants
553 ---------------------
554 Use the same sections as outlined for functions where applicable::
555
556 1. summary
557 2. extended summary (optional)
558 3. see also (optional)
559 4. references (optional)
560 5. examples (optional)
561
562 Docstrings for constants will not be visible in text terminals
563 (constants are of immutable type, so docstrings can not be assigned
564 to them like for for class instances), but will appear in the
565 documentation built with Sphinx.
566
b11ae17 @rgommers DOC: add description of how to document modules to the doc standard.
rgommers authored Mar 25, 2011
567
568 Documenting modules
569 -------------------
570 Each module should have a docstring with at least a summary line. Other
571 sections are optional, and should be used in the same order as for documenting
572 functions when they are appropriate::
573
574 1. summary
575 2. extended summary
576 3. routine listings
577 4. see also
578 5. notes
579 6. references
580 7. examples
581
582 Routine listings are encouraged, especially for large modules, for which it is
583 hard to get a good overview of all functionality provided by looking at the
d0c0f14 @endolith DOC: use bold for section names, monospace for variables in HOWTO_DOC…
endolith authored Dec 2, 2012
584 source file(s) or the ``__all__`` dict.
b11ae17 @rgommers DOC: add description of how to document modules to the doc standard.
rgommers authored Mar 25, 2011
585
586 Note that license and author info, while often included in source files, do not
8ddb0ce @charris STY: Giant whitespace cleanup.
charris authored Aug 18, 2013
587 belong in docstrings.
b11ae17 @rgommers DOC: add description of how to document modules to the doc standard.
rgommers authored Mar 25, 2011
588
589
d35eac6 @pv Address #1146: update docstring standard
pv authored Jul 1, 2009
590 Other points to keep in mind
591 ----------------------------
8ddb0ce @charris STY: Giant whitespace cleanup.
charris authored Aug 18, 2013
592 * Equations : as discussed in the **Notes** section above, LaTeX formatting
593 should be kept to a minimum. Often it's possible to show equations as
594 Python code or pseudo-code instead, which is much more readable in a
595 terminal. For inline display use double backticks (like ``y = np.sin(x)``).
596 For display with blank lines above and below, use a double colon and indent
d0c0f14 @endolith DOC: use bold for section names, monospace for variables in HOWTO_DOC…
endolith authored Dec 2, 2012
597 the code, like::
fac8674 @rgommers DOC: add note on formatting math to HOWTO_DOCUMENT.
rgommers authored Sep 27, 2011
598
599 end of previous sentence::
600
7af95b0 @joonro A minor cleanup
joonro authored Jun 8, 2013
601 y = np.sin(x)
fac8674 @rgommers DOC: add note on formatting math to HOWTO_DOCUMENT.
rgommers authored Sep 27, 2011
602
d35eac6 @pv Address #1146: update docstring standard
pv authored Jul 1, 2009
603 * Notes and Warnings : If there are points in the docstring that deserve
604 special emphasis, the reST directives for a note or warning can be used
7af95b0 @joonro A minor cleanup
joonro authored Jun 8, 2013
605 in the vicinity of the context of the warning (inside a section). Syntax::
d35eac6 @pv Address #1146: update docstring standard
pv authored Jul 1, 2009
606
607 .. warning:: Warning text.
608
609 .. note:: Note text.
610
611 Use these sparingly, as they do not look very good in text terminals
612 and are not often necessary. One situation in which a warning can
613 be useful is for marking a known bug that is not yet fixed.
614
615 * array_like : For functions that take arguments which can have not only
616 a type `ndarray`, but also types that can be converted to an ndarray
617 (i.e. scalar types, sequence types), those arguments can be documented
618 with type `array_like`.
619
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
620 Common reST concepts
621 --------------------
622 For paragraphs, indentation is significant and indicates indentation in the
623 output. New paragraphs are marked with a blank line.
1794d8a @jarrodmillman get the example working
jarrodmillman authored Sep 23, 2007
624
f702698 @endolith escape the italics bold and monospace examples
endolith authored Aug 26, 2014
625 Use ``*italics*``, ``**bold**`` and ````monospace```` if needed in any
626 explanations
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
627 (but not for variable names and doctest code or multi-line code).
8ddb0ce @charris STY: Giant whitespace cleanup.
charris authored Aug 18, 2013
628 Variable, module, function, and class names should be written between
9c02535 @endolith Add note about definition list classifier format
endolith authored Nov 30, 2012
629 single back-ticks (```numpy```).
1794d8a @jarrodmillman get the example working
jarrodmillman authored Sep 23, 2007
630
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
631 A more extensive example of reST markup can be found in `this example
632 document <http://docutils.sourceforge.net/docs/user/rst/demo.txt>`_;
633 the `quick reference
634 <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_ is
635 useful while editing.
1794d8a @jarrodmillman get the example working
jarrodmillman authored Sep 23, 2007
636
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
637 Line spacing and indentation are significant and should be carefully
638 followed.
1794d8a @jarrodmillman get the example working
jarrodmillman authored Sep 23, 2007
639
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
640 Conclusion
641 ----------
1794d8a @jarrodmillman get the example working
jarrodmillman authored Sep 23, 2007
642
f4a313e @stefanv DOC: Remove more SVN references.
stefanv authored Sep 16, 2010
643 `An example <http://github.com/numpy/numpy/blob/master/doc/example.py>`_ of the
a715ab0 @stefanv Update documentation standard.
stefanv authored May 16, 2008
644 format shown here is available. Refer to `How to Build API/Reference
6cdeb71 @stefanv Update documentation standard.
stefanv authored Jun 3, 2008
645 Documentation
4209975 @dnmiller DOC: Fix URL for "How to Build API/Reference Documentation"
dnmiller authored May 24, 2013
646 <http://github.com/numpy/numpy/blob/master/doc/HOWTO_BUILD_DOCS.rst.txt>`_
d35eac6 @pv Address #1146: update docstring standard
pv authored Jul 1, 2009
647 on how to use Sphinx_ to build the manual.
518e9b2 @stefanv Update formatting. Mention how to handle blank lines in doctests.
stefanv authored Sep 25, 2007
648
649 This document itself was written in ReStructuredText, and may be converted to
650 HTML using::
651
652 $ rst2html HOWTO_DOCUMENT.txt HOWTO_DOCUMENT.html
653
654 .. _SciPy: http://www.scipy.org
655 .. _numpy-discussion list: http://www.scipy.org/Mailing_Lists
d35eac6 @pv Address #1146: update docstring standard
pv authored Jul 1, 2009
656 .. _Sphinx: http://sphinx.pocoo.org
Something went wrong with that request. Please try again.