aboutsummaryrefslogtreecommitdiffstats
path: root/docs/example_numpy.py
diff options
context:
space:
mode:
Diffstat (limited to 'docs/example_numpy.py')
-rw-r--r--docs/example_numpy.py323
1 files changed, 323 insertions, 0 deletions
diff --git a/docs/example_numpy.py b/docs/example_numpy.py
new file mode 100644
index 0000000..bb91cac
--- /dev/null
+++ b/docs/example_numpy.py
@@ -0,0 +1,323 @@
+# -*- coding: utf-8 -*-
+"""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 Documentation HOWTO:
+ https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
+
+"""
+
+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 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.
+
+ Parameter types -- if given -- should be specified according to
+ `PEP 484`_, though `PEP 484`_ conformance isn't required or enforced.
+
+ 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 : Optional[str]
+ 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`.
+
+
+ .. _PEP 484:
+ https://www.python.org/dev/peps/pep-0484/
+
+ """
+ if param1 == param2:
+ raise ValueError('param1 may not be equal to param2')
+ 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]
+
+ """
+ for i in range(n):
+ yield i
+
+
+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 : Optional[int]
+ 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(object):
+ """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.
+
+ Attribute and property types -- if given -- should be specified according
+ to `PEP 484`_, though `PEP 484`_ conformance isn't required or enforced.
+
+ Attributes
+ ----------
+ attr1 : str
+ Description of `attr1`.
+ attr2 : Optional[int]
+ Description of `attr2`.
+
+
+ .. _PEP 484:
+ https://www.python.org/dev/peps/pep-0484/
+
+ """
+
+ 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 : Optional[int]
+ 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
+ """Optional[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