numpydoc – Numpy’s Sphinx extensions¶
Numpy’s documentation uses several custom extensions to Sphinx. These
are shipped in this numpydoc
package, in case you want to make use
of them in third-party projects.
The numpydoc
extension provides support for the Numpy docstring format in
Sphinx, and adds the code description directives np:function
,
np-c:function
, etc. that support the Numpy docstring syntax.
Development: https://github.com/numpy/numpydoc/
Documentation: https://numpydoc.readthedocs.io/
Getting started¶
Installation¶
This extension requires Python 3.7+, sphinx 1.8+ and is available from:
‘numpydoc’ should be added to the extensions
option in your Sphinx
conf.py
. 'sphinx.ext.autosummary'
will automatically be loaded
as well.
Configuration¶
The following options can be set in your Sphinx conf.py
:
- numpydoc_use_plotsbool
Whether to produce
plot::
directives for Examples sections that containimport matplotlib
orfrom matplotlib import
.- numpydoc_show_class_membersbool
Whether to show all members of a class in the Methods and Attributes sections automatically.
True
by default.- numpydoc_show_inherited_class_membersbool
Whether to show all inherited members of a class in the Methods and Attributes sections automatically. If it’s false, inherited members won’t shown.
True
by default.- numpydoc_class_members_toctreebool
Whether to create a Sphinx table of contents for the lists of class methods and attributes. If a table of contents is made, Sphinx expects each entry to have a separate page.
True
by default.- numpydoc_citation_restr
A regular expression matching citations which should be mangled to avoid conflicts due to duplication across the documentation. Defaults to
[\w-]+
.- numpydoc_use_blockquotesbool
Until version 0.8, parameter definitions were shown as blockquotes, rather than in a definition list. If your styling requires blockquotes, switch this config option to True. This option will be removed in version 0.10.
- numpydoc_attributes_as_param_listbool
Whether to format the Attributes section of a class page in the same way as the Parameter section. If it’s False, the Attributes section will be formatted as the Methods section using an autosummary table.
True
by default.- numpydoc_xref_param_typebool
Whether to create cross-references for the parameter types in the
Parameters
,Other Parameters
,Returns
andYields
sections of the docstring.False
by default.Note
Depending on the link types, the CSS styles might be different. consider overriding e.g.
span.classifier a span.xref
andspan.classifier a code.docutils.literal.notranslate
CSS classes to achieve a uniform appearance.- numpydoc_xref_aliasesdict
Mappings to fully qualified paths (or correct ReST references) for the aliases/shortcuts used when specifying the types of parameters. The keys should not have any spaces. Together with the
intersphinx
extension, you can map to links in any documentation.The default
numpydoc_xref_aliases
will supply some commonPython
standard library andNumPy
names for you. Then for your module, a usefuldict
may look like the following (e.g., if you were documentingsklearn.model_selection
):numpydoc_xref_aliases = { 'LeaveOneOut': 'sklearn.model_selection.LeaveOneOut', ... }
This option depends on the
numpydoc_xref_param_type
option beingTrue
.- numpydoc_xref_ignoreset or
"all"
How to handle terms not in
numpydoc_xref_aliases
whennumpydoc_xref_aliases=True
. The value can either be aset
containing terms to ignore, or"all"
. In the former case, the set contains words not to cross-reference. Most likely, these are common words used in parameter type descriptions that may be confused for classes of the same name. For example:numpydoc_xref_ignore = {'type', 'optional', 'default'}
The default is an empty set.
If the
numpydoc_xref_ignore="all"
, then all unrecognized terms are ignored, i.e. terms not innumpydoc_xref_aliases
are not wrapped in:obj:
roles. This configuration parameter may be useful if you only want to create cross references for a small number of terms. In this case, including the desired cross reference mappings innumpydoc_xref_aliases
and settingnumpydoc_xref_ignore="all"
is more convenient than explicitly listing terms to ignore in a set.- numpydoc_validation_checksset
The set of validation checks to report during the sphinx build process. The default is an empty set, so docstring validation is not run by default. If
"all"
is in the set, then the results of all of the built-in validation checks are reported. If the set includes"all"
and additional error codes, then all validation checks except the listed error codes will be run. If the set contains only individual error codes, then only those checks will be run. For example:# Report warnings for all validation checks numpydoc_validation_checks = {"all"} # Report warnings for all checks *except* for GL01, GL02, and GL05 numpydoc_validation_checks = {"all", "GL01", "GL02", "GL05"} # Only report warnings for the SA01 and EX01 checks numpydoc_validation_checks = {"SA01", "EX01"}
- numpydoc_validation_excludeset
A container of strings using
re
syntax specifying patterns to ignore for docstring validation. For example, to skip docstring validation for all objects inmypkg.mymodule
:numpydoc_validation_exclude = {"mypkg.mymodule."}
If you wanted to also skip getter methods of
MyClass
:numpydoc_validation_exclude = {r"mypkg\.mymodule\.", r"MyClass\.get$"}
The default is an empty set meaning no objects are excluded from docstring validation. Only has an effect when docstring validation is activated, i.e.
numpydoc_validation_checks
is not an empty set.- numpydoc_edit_linkbool
Deprecated since version 0.7.0.
edit your HTML template instead
Whether to insert an edit link after docstrings.
Style guide¶
This document describes the syntax and best practices for docstrings used with the numpydoc extension for Sphinx.
Note
For an accompanying example, see example.py.
Some features described in this document require a recent version of
numpydoc
. For example, the Yields section was added in
numpydoc
0.6.
Overview¶
- We mostly follow the standard Python style conventions as described here:
- Additional PEPs of interest regarding documentation of code:
- Use a code checker:
pylint: a Python static code analysis tool.
pyflakes: a tool to check Python code for errors by parsing the source file instead of importing it.
pycodestyle: (formerly
pep8
) a tool to check Python code against some of the style conventions in PEP 8.flake8: a tool that glues together
pycodestyle
,pyflakes
,mccabe
to check the style and quality of Python code.vim-flake8: a
flake8
plugin for Vim.
Import conventions¶
The following import conventions are used throughout the NumPy source and documentation:
import numpy as np
import matplotlib as mpl
import matplotlib.pyplot as plt
Do not abbreviate scipy
. There is no motivating use case to
abbreviate it in the real world, so we avoid it in the documentation
to avoid confusion.
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.
Our docstring standard uses re-structured text (reST) syntax and is rendered using Sphinx (a pre-processor that understands 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 Sphinx in its task.
The length of docstring lines should be kept to 75 characters to facilitate reading the docstrings in text terminals.
Sections¶
The docstring consists of a number of sections separated by headings (except for the deprecation warning). Each heading should be underlined in hyphens, and the section ordering should be consistent with the description below.
The sections of a function’s 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. Deprecation warning¶
A section (use if applicable) to warn users that the object is deprecated. Section contents should include:
In what NumPy version the object was deprecated, and when it will be removed.
Reason for deprecation if this is useful information (e.g., object is superseded, duplicates functionality found elsewhere, etc.).
New recommended way of obtaining the same functionality.
This section should use the deprecated
Sphinx directive instead of an
underlined section header.
.. deprecated:: 1.6.0
`ndobj_old` will be removed in NumPy 2.0.0, it is replaced by
`ndobj_new` because the latter works also with array subclasses.
3. 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.
4. Parameters¶
Description of the function arguments, keywords and their respective types.
Parameters
----------
x : type
Description of parameter `x`.
y
Description of parameter `y` (with type not specified).
Enclose variables in single backticks. The colon must be preceded by a space, or omitted if the type is absent.
For the parameter types, be as precise as possible. Below are a few examples of parameters and their types.
Parameters
----------
filename : str
copy : bool
dtype : data-type
iterable : iterable object
shape : int or tuple of int
files : list of str
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).
or as part of the type, instead of optional
. If the default value would not be
used as a value, optional
is preferred. These are all equivalent:
copy : bool, default True
copy : bool, default=True
copy : bool, default: True
When a parameter can only assume one of a fixed set of values, those values can be listed in braces, with the default appearing first:
order : {'C', 'F', 'A'}
Description of `order`.
When two or more input parameters have exactly the same type, shape and description, they can be combined:
x1, x2 : array_like
Input arrays, description of `x1`, `x2`.
When documenting variable length positional, or keyword arguments, leave the leading star(s) in front of the name:
*args : tuple
Additional arguments should be passed as keyword arguments
**kwargs : dict, optional
Extra arguments to `metric`: refer to each metric documentation for a
list of all possible arguments.
5. Returns¶
Explanation of the returned values and their types. Similar to the Parameters section, except the name of each return value is optional. The type of each return value is always required:
Returns
-------
int
Description of anonymous integer return value.
If both the name and type are specified, the Returns section takes the same form as the Parameters section:
Returns
-------
err_code : int
Non-zero value indicates error code, or zero on success.
err_msg : str or None
Human readable error message, or None on success.
6. Yields¶
Explanation of the yielded values and their types. This is relevant to generators only. Similar to the Returns section in that the name of each value is optional, but the type of each value is always required:
Yields
------
int
Description of the anonymous integer return value.
If both the name and type are specified, the Yields section takes the same form as the Returns section:
Yields
------
err_code : int
Non-zero value indicates error code, or zero on success.
err_msg : str or None
Human readable error message, or None on success.
Support for the Yields section was added in numpydoc version 0.6.
7. Receives¶
Explanation of parameters passed to a generator’s .send()
method,
formatted as for Parameters, above. Since, like for Yields and Returns, a
single object is always passed to the method, this may describe either the
single parameter, or positional arguments passed as a tuple. If a docstring
includes Receives it must also include Yields.
8. 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 parameters, to prevent cluttering the Parameters section.
9. Raises¶
An optional section detailing which errors get raised and under what conditions:
Raises
------
LinAlgException
If the matrix is not numerically invertible.
This section should be used judiciously, i.e., only for errors that are non-obvious or have a large chance of getting raised.
10. Warns¶
An optional section detailing which warnings get raised and under what conditions, formatted similarly to Raises.
11. Warnings¶
An optional section with cautions to the user in free text/reST.
12. 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, and this is preferable if the functionality is clear from the function name:
See Also
--------
func_a : Function a with its description.
func_b, func_c_, func_d
func_e
If the combination of the function name and the description creates a line that is too long, the entry may be written as two lines, with the function name and colon on the first line, and the description on the next line, indented four spaces:
See Also
--------
package.module.submodule.func_a :
A somewhat long description of the function.
13. 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 format:
Notes
-----
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.
14. 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:
- 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. References are numbered, starting from one, in the order in which they are cited.
Warning
References will break tables
Where references like [1] appear in a tables within a numpydoc docstring, the table markup will be broken by numpydoc processing. See numpydoc issue #130
15. Examples¶
An optional section for examples, using the doctest 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.
When multiple examples are provided, they should be separated by blank lines. Comments explaining the examples should have blank lines both above and below them:
Examples
--------
>>> np.add(1, 2)
3
Comment explaining the second example.
>>> np.add([1, 2], [3, 4])
array([4, 6])
The example code may be split across multiple lines, with each line after the first starting with ‘… ‘:
>>> np.add([[1, 2], [3, 4]],
... [[5, 6], [7, 8]])
array([[ 6, 8],
[10, 12]])
For tests with a result that is random or platform-dependent, mark the output as such:
>>> import numpy.random
>>> np.random.rand(2)
array([ 0.35773152, 0.38568979]) #random
You can run examples as doctests using:
>>> np.test(doctests=True)
>>> np.linalg.test(doctests=True) # for a single module
In IPython it is also possible to run individual examples simply by copy-pasting them in doctest mode:
In [1]: %doctest_mode
Exception reporting mode: Plain
Doctest mode is: ON
>>> %paste
import numpy.random
np.random.rand(2)
## -- End pasted text --
array([ 0.8519522 , 0.15492887])
It is not necessary to use the doctest markup <BLANKLINE>
to
indicate empty lines in the output. Note that the option to run
the examples through numpy.test
is provided for checking if the
examples work, not for making the examples part of the testing framework.
The examples may assume that import numpy as np
is executed before
the example code in numpy. Additional examples may make use of
matplotlib for plotting, but should import it explicitly, e.g.,
import matplotlib.pyplot as plt
. All other imports, including the
demonstrated function, must be explicit.
When matplotlib is imported in the example, the Example code will be
wrapped in matplotlib’s Sphinx `plot` directive. When matplotlib is
not explicitly imported, .. plot:: can be used directly if
matplotlib.sphinxext.plot_directive is loaded as a Sphinx extension in
conf.py
.
Documenting classes¶
Class docstring¶
Use the same sections as outlined above (all except Returns
are
applicable). The constructor (__init__
) should also be documented
here, the Parameters section of the docstring details the
constructor’s parameters.
An Attributes section, located below the Parameters section, may be used to describe non-method attributes of the class:
Attributes
----------
x : float
The X coordinate.
y : float
The Y coordinate.
Attributes that are properties and have their own docstrings can be simply listed by name:
Attributes
----------
real
imag
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.
"""
If it is necessary to explain a private method (use with care!), it can be referred to in the Extended Summary or the Notes section. Do not list private methods in the Methods section.
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. If a method has an equivalent function
(which is the case for many ndarray methods for example), the function
docstring should contain the detailed documentation, and the method docstring
should refer to it. Only put brief summary and See Also
sections in the method docstring. The method should use a
Returns or Yields section, as appropriate.
Documenting class instances¶
Instances of classes that are part of the NumPy API (for example np.r_ np.c_, np.index_exp, etc.) may require some care. To give these instances a useful docstring, we do the following:
Single instance: If only a single instance of a class is exposed, document the class. Examples can use the instance name.
Multiple instances: If multiple instances are exposed, docstrings for each instance are written and assigned to the instances’
__doc__
attributes at run time. The class is documented as usual, and the exposed instances can be mentioned in the Notes and See Also sections.
Documenting generators¶
Generators should be documented just as functions are documented. The only difference is that one should use the Yields section instead of the Returns section. Support for the Yields section was added in numpydoc version 0.6.
Documenting constants¶
Use the same sections as outlined for functions where applicable:
1. summary
2. extended summary (optional)
3. see also (optional)
4. references (optional)
5. examples (optional)
Docstrings for constants will not be visible in text terminals (constants are of immutable type, so docstrings can not be assigned to them like for for class instances), but will appear in the documentation built with Sphinx.
Documenting modules¶
Each module should have a docstring with at least a summary line. Other sections are optional, and should be used in the same order as for documenting functions when they are appropriate:
1. summary
2. extended summary
3. routine listings
4. see also
5. notes
6. references
7. examples
Routine listings are encouraged, especially for large modules, for which it is
hard to get a good overview of all functionality provided by looking at the
source file(s) or the __all__
dict.
Note that license and author info, while often included in source files, do not belong in docstrings.
Other points to keep in mind¶
Equations : as discussed in the Notes section above, LaTeX formatting should be kept to a minimum. Often it’s possible to show equations as Python code or pseudo-code instead, which is much more readable in a terminal. For inline display use double backticks (like
y = np.sin(x)
). For display with blank lines above and below, use a double colon and indent the code, like:end of previous sentence:: y = np.sin(x)
Notes and Warnings : If there are points in the docstring that deserve special emphasis, the reST directives for a note or warning can be used in the vicinity of the context of the warning (inside a section). Syntax:
.. warning:: Warning text. .. note:: Note text.
Use these sparingly, as they do not look very good in text terminals and are not often necessary. One situation in which a warning can be useful is for marking a known bug that is not yet fixed.
array_like : For functions that take arguments which can have not only a type ndarray, but also types that can be converted to an ndarray (i.e. scalar types, sequence types), those arguments can be documented with type array_like.
Links : If you need to include hyperlinks in your docstring, note that some docstring sections are not parsed as standard reST, and in these sections, numpydoc may become confused by hyperlink targets such as:
.. _Example: http://www.example.com
If the Sphinx build issues a warning of the form
WARNING: Unknown target name: "example"
, then that is what is happening. To avoid this problem, use the inline hyperlink form:`Example <http://www.example.com>`_
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 ``monospace``
if needed in any
explanations
(but not for variable names and doctest code or multi-line code).
Variable, module, function, and class names should be written between
single back-ticks (`numpy`
).
A more extensive example of reST markup can be found in this example document; the quick reference is useful while editing.
Line spacing and indentation are significant and should be carefully followed.
Conclusion¶
This document itself was written in ReStructuredText. An example of the format shown here is available.
Validation¶
Docstring Validation using Python¶
To see the Restructured Text generated for an object, the numpydoc
module
can be called. For example, to do it for numpy.ndarray
, use:
$ python -m numpydoc numpy.ndarray
This will validate that the docstring can be built.
For an exhaustive validation of the formatting of the docstring, use the
--validate
parameter. This will report the errors detected, such as
incorrect capitalization, wrong order of the sections, and many other
issues.
Docstring Validation during Sphinx Build¶
It is also possible to run docstring validation as part of the sphinx build
process.
This behavior is controlled by the numpydoc_validation_checks
configuration
parameter in conf.py
.
For example, to verify that all of the parameters in the function signature
are accounted for in the Parameters
section of the docstring, add the
following line to conf.py
:
numpydoc_validation_checks = {"PR01"}
This will cause a sphinx warning to be raised for any (non-module) docstring that has undocumented parameters in the signature. The full set of validation checks can be activated by:
numpydoc_validation_checks = {"all"}
The complete validation suite contains many checks
including some for style, capitalization, and grammar.
It is unlikely that reporting all validation warnings is desirable for
most use-cases.
Individual checks can be excluded by including them in the set with the
special keyword "all"
:
# Report warnings for all validation checks except GL01, GL02, and GL05
numpydoc_validation_checks = {"all", "GL01", "GL02", "GL05"}
Built-in Validation Checks¶
The numpydoc.validation
module provides a mapping with all of the checks
that are run as part of the validation procedure.
The mapping is of the form: error_code : <explanation>
where error_code
provides a shorthand for the check being run, and <explanation>
provides
a more detailed message. For example:
"EX01" : "No examples section found"
The full mapping of validation checks is given below.
ERROR_MSGS = {
"GL01": "Docstring text (summary) should start in the line immediately "
"after the opening quotes (not in the same line, or leaving a "
"blank line in between)",
"GL02": "Closing quotes should be placed in the line after the last text "
"in the docstring (do not close the quotes in the same line as "
"the text, or leave a blank line between the last text and the "
"quotes)",
"GL03": "Double line break found; please use only one blank line to "
"separate sections or paragraphs, and do not leave blank lines "
"at the end of docstrings",
"GL05": 'Tabs found at the start of line "{line_with_tabs}", please use '
"whitespace only",
"GL06": 'Found unknown section "{section}". Allowed sections are: '
"{allowed_sections}",
"GL07": "Sections are in the wrong order. Correct order is: {correct_sections}",
"GL08": "The object does not have a docstring",
"GL09": "Deprecation warning should precede extended summary",
"GL10": "reST directives {directives} must be followed by two colons",
"SS01": "No summary found (a short summary in a single line should be "
"present at the beginning of the docstring)",
"SS02": "Summary does not start with a capital letter",
"SS03": "Summary does not end with a period",
"SS04": "Summary contains heading whitespaces",
"SS05": "Summary must start with infinitive verb, not third person "
'(e.g. use "Generate" instead of "Generates")',
"SS06": "Summary should fit in a single line",
"ES01": "No extended summary found",
"PR01": "Parameters {missing_params} not documented",
"PR02": "Unknown parameters {unknown_params}",
"PR03": "Wrong parameters order. Actual: {actual_params}. "
"Documented: {documented_params}",
"PR04": 'Parameter "{param_name}" has no type',
"PR05": 'Parameter "{param_name}" type should not finish with "."',
"PR06": 'Parameter "{param_name}" type should use "{right_type}" instead '
'of "{wrong_type}"',
"PR07": 'Parameter "{param_name}" has no description',
"PR08": 'Parameter "{param_name}" description should start with a '
"capital letter",
"PR09": 'Parameter "{param_name}" description should finish with "."',
"PR10": 'Parameter "{param_name}" requires a space before the colon '
"separating the parameter name and type",
"RT01": "No Returns section found",
"RT02": "The first line of the Returns section should contain only the "
"type, unless multiple values are being returned",
"RT03": "Return value has no description",
"RT04": "Return value description should start with a capital letter",
"RT05": 'Return value description should finish with "."',
"YD01": "No Yields section found",
"SA01": "See Also section not found",
"SA02": "Missing period at end of description for See Also "
'"{reference_name}" reference',
"SA03": "Description should be capitalized for See Also "
'"{reference_name}" reference',
"SA04": 'Missing description for See Also "{reference_name}" reference',
Release notes¶
Page contents
Note
For release notes (sparsely) kept prior to 1.0.0, look at the releases page on GitHub.
1.1.0¶
Implemented enhancements¶
Fixed bugs¶
Closed issues¶
Additional notes¶
Due to merging of #221, self and cls no longer will appear in method signatures.
1.0.0¶
Implemented enhancements¶
MAINT,STY: Upgrade to bionic, and change style similar to NumPy #253 (mwtoews)
Adding –validate option __main__ and run new validation #240 (datapythonista)
Add docstring validation script (from pandas) #238 (datapythonista)
DOC: Add description for blank lines after the docstring. #229 (bingyao)
Fixed bugs¶
Removed¶
Closed issues¶
Additional notes¶
CSS styling changed from NumpyDoc < 0.8 and Sphinx < 2.0 to more properly make use of definition lists. This can cause issues with rendering that can be fixed via CSS, especially when using
sphinx-rtd-theme
. For more information, see:
Example¶
Source¶
"""Docstring for the example.py module.
Modules names should have short, all-lowercase names. The module name may
have underscores if this improves readability.
Every module should have a docstring at the very top of the file. The
module's docstring may extend over multiple lines. If your docstring does
extend over multiple lines, the closing three quotation marks must be on
a line by itself, preferably preceded by a blank line.
"""
from __future__ import division, absolute_import, print_function
import os # standard library imports first
# Do NOT import using *, e.g. from numpy import *
#
# Import the module using
#
# import numpy
#
# instead or import individual functions as needed, e.g
#
# from numpy import array, zeros
#
# If you prefer the use of abbreviated module names, we suggest the
# convention used by NumPy itself::
import numpy as np
import matplotlib as mpl
import matplotlib.pyplot as plt
# These abbreviated names are not to be used in docstrings; users must
# be able to paste and execute docstrings after importing only the
# numpy module itself, unabbreviated.
def foo(var1, var2, *args, long_var_name='hi', only_seldom_used_keyword=0, **kwargs):
r"""Summarize the function in one line.
Several sentences providing an extended description. Refer to
variables using back-ticks, e.g. `var`.
Parameters
----------
var1 : array_like
Array_like means all those objects -- lists, nested lists, etc. --
that can be converted to an array. We can also refer to
variables like `var1`.
var2 : int
The type above can either refer to an actual Python type
(e.g. ``int``), or describe the type of the variable in more
detail, e.g. ``(N,) ndarray`` or ``array_like``.
*args : iterable
Other arguments.
long_var_name : {'hi', 'ho'}, optional
Choices in brackets, default first when optional.
Returns
-------
type
Explanation of anonymous return value of type ``type``.
describe : type
Explanation of return value named `describe`.
out : type
Explanation of `out`.
type_without_description
Other Parameters
----------------
only_seldom_used_keyword : int, optional
Infrequently used parameters can be described under this optional
section to prevent cluttering the Parameters section.
**kwargs : dict
Other infrequently used keyword arguments. Note that all keyword
arguments appearing after the first parameter specified under the
Other Parameters section, should also be described under this
section.
Raises
------
BadException
Because you shouldn't have done that.
See Also
--------
numpy.array : Relationship (optional).
numpy.ndarray : Relationship (optional), which could be fairly long, in
which case the line wraps here.
numpy.dot, numpy.linalg.norm, numpy.eye
Notes
-----
Notes about the implementation algorithm (if needed).
This can have multiple paragraphs.
You may include some math:
.. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
And even use a Greek symbol like :math:`\omega` inline.
References
----------
Cite the relevant literature, e.g. [1]_. You may also cite these
references in the notes section above.
.. [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.
Examples
--------
These are written in doctest format, and should illustrate how to
use the function.
>>> a = [1, 2, 3]
>>> print([x + 3 for x in a])
[4, 5, 6]
>>> print("a\nb")
a
b
"""
# After closing class docstring, there should be one blank line to
# separate following codes (according to PEP257).
# But for function, method and module, there should be no blank lines
# after closing the docstring.
pass
Rendered¶
Docstring for the example.py module.
Modules names should have short, all-lowercase names. The module name may have underscores if this improves readability.
Every module should have a docstring at the very top of the file. The module’s docstring may extend over multiple lines. If your docstring does extend over multiple lines, the closing three quotation marks must be on a line by itself, preferably preceded by a blank line.
- example.foo(var1, var2, *args, long_var_name='hi', only_seldom_used_keyword=0, **kwargs)[source]¶
Summarize the function in one line.
Several sentences providing an extended description. Refer to variables using back-ticks, e.g. var.
- Parameters
- var1array_like
Array_like means all those objects – lists, nested lists, etc. – that can be converted to an array. We can also refer to variables like var1.
- var2
int
The type above can either refer to an actual Python type (e.g.
int
), or describe the type of the variable in more detail, e.g.(N,) ndarray
orarray_like
.- *argsiterable
Other arguments.
- long_var_name{‘hi’, ‘ho’}, optional
Choices in brackets, default first when optional.
- Returns
- Other Parameters
- only_seldom_used_keyword
int
, optional Infrequently used parameters can be described under this optional section to prevent cluttering the Parameters section.
- **kwargs
dict
Other infrequently used keyword arguments. Note that all keyword arguments appearing after the first parameter specified under the Other Parameters section, should also be described under this section.
- only_seldom_used_keyword
- Raises
- BadException
Because you shouldn’t have done that.
See also
numpy.array
Relationship (optional).
numpy.ndarray
Relationship (optional), which could be fairly long, in which case the line wraps here.
numpy.dot
,numpy.linalg.norm
,numpy.eye
Notes
Notes about the implementation algorithm (if needed).
This can have multiple paragraphs.
You may include some math:
And even use a Greek symbol like inline.
References
Cite the relevant literature, e.g. [1]. You may also cite these references in the notes section above.
- 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.
Examples
These are written in doctest format, and should illustrate how to use the function.
>>> a = [1, 2, 3] >>> print([x + 3 for x in a]) [4, 5, 6] >>> print("a\nb") a b