mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
352 lines
9.5 KiB
Python
352 lines
9.5 KiB
Python
"""Example NumPy style docstrings.
|
|
|
|
This module demonstrates documentation as specified by the `NumPy
|
|
Documentation HOWTO`_. Docstrings may extend over multiple lines. Sections
|
|
are created with a section header followed by an underline of equal length.
|
|
|
|
Example
|
|
-------
|
|
Examples can be given using either the ``Example`` or ``Examples``
|
|
sections. Sections support any reStructuredText formatting, including
|
|
literal blocks::
|
|
|
|
$ python example_numpy.py
|
|
|
|
|
|
Section breaks are created with two blank lines. Section breaks are also
|
|
implicitly created anytime a new section starts. Section bodies *may* be
|
|
indented:
|
|
|
|
Notes
|
|
-----
|
|
This is an example of an indented section. It's like any other section,
|
|
but the body is indented to help it stand out from surrounding text.
|
|
|
|
If a section is indented, then a section break is created by
|
|
resuming unindented text.
|
|
|
|
Attributes
|
|
----------
|
|
module_level_variable1 : int
|
|
Module level variables may be documented in either the ``Attributes``
|
|
section of the module docstring, or in an inline docstring immediately
|
|
following the variable.
|
|
|
|
Either form is acceptable, but the two should not be mixed. Choose
|
|
one convention to document module level variables and be consistent
|
|
with it.
|
|
|
|
|
|
.. _NumPy docstring standard:
|
|
https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
|
|
|
|
"""
|
|
|
|
module_level_variable1 = 12345
|
|
|
|
module_level_variable2 = 98765
|
|
"""int: Module level variable documented inline.
|
|
|
|
The docstring may span multiple lines. The type may optionally be specified
|
|
on the first line, separated by a colon.
|
|
"""
|
|
|
|
|
|
def function_with_types_in_docstring(param1, param2):
|
|
"""Example function with types documented in the docstring.
|
|
|
|
:pep:`484` type annotations are supported. If attribute, parameter, and
|
|
return types are annotated according to `PEP 484`_, they do not need to be
|
|
included in the docstring:
|
|
|
|
Parameters
|
|
----------
|
|
param1 : int
|
|
The first parameter.
|
|
param2 : str
|
|
The second parameter.
|
|
|
|
Returns
|
|
-------
|
|
bool
|
|
True if successful, False otherwise.
|
|
"""
|
|
|
|
|
|
def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
|
|
"""Example function with PEP 484 type annotations.
|
|
|
|
The return type must be duplicated in the docstring to comply
|
|
with the NumPy docstring style.
|
|
|
|
Parameters
|
|
----------
|
|
param1
|
|
The first parameter.
|
|
param2
|
|
The second parameter.
|
|
|
|
Returns
|
|
-------
|
|
bool
|
|
True if successful, False otherwise.
|
|
|
|
"""
|
|
|
|
|
|
def module_level_function(param1, param2=None, *args, **kwargs):
|
|
"""This is an example of a module level function.
|
|
|
|
Function parameters should be documented in the ``Parameters`` section.
|
|
The name of each parameter is required. The type and description of each
|
|
parameter is optional, but should be included if not obvious.
|
|
|
|
If ``*args`` or ``**kwargs`` are accepted,
|
|
they should be listed as ``*args`` and ``**kwargs``.
|
|
|
|
The format for a parameter is::
|
|
|
|
name : type
|
|
description
|
|
|
|
The description may span multiple lines. Following lines
|
|
should be indented to match the first line of the description.
|
|
The ": type" is optional.
|
|
|
|
Multiple paragraphs are supported in parameter
|
|
descriptions.
|
|
|
|
Parameters
|
|
----------
|
|
param1 : int
|
|
The first parameter.
|
|
param2 : :obj:`str`, optional
|
|
The second parameter.
|
|
*args
|
|
Variable length argument list.
|
|
**kwargs
|
|
Arbitrary keyword arguments.
|
|
|
|
Returns
|
|
-------
|
|
bool
|
|
True if successful, False otherwise.
|
|
|
|
The return type is not optional. The ``Returns`` section may span
|
|
multiple lines and paragraphs. Following lines should be indented to
|
|
match the first line of the description.
|
|
|
|
The ``Returns`` section supports any reStructuredText formatting,
|
|
including literal blocks::
|
|
|
|
{
|
|
'param1': param1,
|
|
'param2': param2,
|
|
}
|
|
|
|
Raises
|
|
------
|
|
AttributeError
|
|
The ``Raises`` section is a list of all exceptions
|
|
that are relevant to the interface.
|
|
ValueError
|
|
If `param2` is equal to `param1`.
|
|
|
|
"""
|
|
if param1 == param2:
|
|
msg = 'param1 may not be equal to param2'
|
|
raise ValueError(msg)
|
|
return True
|
|
|
|
|
|
def example_generator(n):
|
|
"""Generators have a ``Yields`` section instead of a ``Returns`` section.
|
|
|
|
Parameters
|
|
----------
|
|
n : int
|
|
The upper limit of the range to generate, from 0 to `n` - 1.
|
|
|
|
Yields
|
|
------
|
|
int
|
|
The next number in the range of 0 to `n` - 1.
|
|
|
|
Examples
|
|
--------
|
|
Examples should be written in doctest format, and should illustrate how
|
|
to use the function.
|
|
|
|
>>> print([i for i in example_generator(4)])
|
|
[0, 1, 2, 3]
|
|
|
|
"""
|
|
yield from range(n)
|
|
|
|
|
|
class ExampleError(Exception):
|
|
"""Exceptions are documented in the same way as classes.
|
|
|
|
The __init__ method may be documented in either the class level
|
|
docstring, or as a docstring on the __init__ method itself.
|
|
|
|
Either form is acceptable, but the two should not be mixed. Choose one
|
|
convention to document the __init__ method and be consistent with it.
|
|
|
|
Note
|
|
----
|
|
Do not include the `self` parameter in the ``Parameters`` section.
|
|
|
|
Parameters
|
|
----------
|
|
msg : str
|
|
Human readable string describing the exception.
|
|
code : :obj:`int`, optional
|
|
Numeric error code.
|
|
|
|
Attributes
|
|
----------
|
|
msg : str
|
|
Human readable string describing the exception.
|
|
code : int
|
|
Numeric error code.
|
|
|
|
"""
|
|
|
|
def __init__(self, msg, code):
|
|
self.msg = msg
|
|
self.code = code
|
|
|
|
|
|
class ExampleClass:
|
|
"""The summary line for a class docstring should fit on one line.
|
|
|
|
If the class has public attributes, they may be documented here
|
|
in an ``Attributes`` section and follow the same formatting as a
|
|
function's ``Args`` section. Alternatively, attributes may be documented
|
|
inline with the attribute's declaration (see __init__ method below).
|
|
|
|
Properties created with the ``@property`` decorator should be documented
|
|
in the property's getter method.
|
|
|
|
Attributes
|
|
----------
|
|
attr1 : str
|
|
Description of `attr1`.
|
|
attr2 : :obj:`int`, optional
|
|
Description of `attr2`.
|
|
|
|
"""
|
|
|
|
def __init__(self, param1, param2, param3):
|
|
"""Example of docstring on the __init__ method.
|
|
|
|
The __init__ method may be documented in either the class level
|
|
docstring, or as a docstring on the __init__ method itself.
|
|
|
|
Either form is acceptable, but the two should not be mixed. Choose one
|
|
convention to document the __init__ method and be consistent with it.
|
|
|
|
Note
|
|
----
|
|
Do not include the `self` parameter in the ``Parameters`` section.
|
|
|
|
Parameters
|
|
----------
|
|
param1 : str
|
|
Description of `param1`.
|
|
param2 : list(str)
|
|
Description of `param2`. Multiple
|
|
lines are supported.
|
|
param3 : :obj:`int`, optional
|
|
Description of `param3`.
|
|
|
|
"""
|
|
self.attr1 = param1
|
|
self.attr2 = param2
|
|
self.attr3 = param3 #: Doc comment *inline* with attribute
|
|
|
|
#: list(str): Doc comment *before* attribute, with type specified
|
|
self.attr4 = ['attr4']
|
|
|
|
self.attr5 = None
|
|
"""str: Docstring *after* attribute, with type specified."""
|
|
|
|
@property
|
|
def readonly_property(self):
|
|
"""str: Properties should be documented in their getter method."""
|
|
return 'readonly_property'
|
|
|
|
@property
|
|
def readwrite_property(self):
|
|
"""list(str): Properties with both a getter and setter
|
|
should only be documented in their getter method.
|
|
|
|
If the setter method contains notable behavior, it should be
|
|
mentioned here.
|
|
"""
|
|
return ['readwrite_property']
|
|
|
|
@readwrite_property.setter
|
|
def readwrite_property(self, value):
|
|
_ = value
|
|
|
|
def example_method(self, param1, param2):
|
|
"""Class methods are similar to regular functions.
|
|
|
|
Note
|
|
----
|
|
Do not include the `self` parameter in the ``Parameters`` section.
|
|
|
|
Parameters
|
|
----------
|
|
param1
|
|
The first parameter.
|
|
param2
|
|
The second parameter.
|
|
|
|
Returns
|
|
-------
|
|
bool
|
|
True if successful, False otherwise.
|
|
|
|
"""
|
|
return True
|
|
|
|
def __special__(self):
|
|
"""By default special members with docstrings are not included.
|
|
|
|
Special members are any methods or attributes that start with and
|
|
end with a double underscore. Any special member with a docstring
|
|
will be included in the output, if
|
|
``napoleon_include_special_with_doc`` is set to True.
|
|
|
|
This behavior can be enabled by changing the following setting in
|
|
Sphinx's conf.py::
|
|
|
|
napoleon_include_special_with_doc = True
|
|
|
|
"""
|
|
pass
|
|
|
|
def __special_without_docstring__(self):
|
|
pass
|
|
|
|
def _private(self):
|
|
"""By default private members are not included.
|
|
|
|
Private members are any methods or attributes that start with an
|
|
underscore and are *not* special. By default they are not included
|
|
in the output.
|
|
|
|
This behavior can be changed such that private members *are* included
|
|
by changing the following setting in Sphinx's conf.py::
|
|
|
|
napoleon_include_private_with_doc = True
|
|
|
|
"""
|
|
pass
|
|
|
|
def _private_without_docstring(self):
|
|
pass
|