summaryrefslogtreecommitdiffstats
path: root/doc/usage/extensions
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 17:25:40 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 17:25:40 +0000
commitcf7da1843c45a4c2df7a749f7886a2d2ba0ee92a (patch)
tree18dcde1a8d1f5570a77cd0c361de3b490d02c789 /doc/usage/extensions
parentInitial commit. (diff)
downloadsphinx-cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a.tar.xz
sphinx-cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a.zip
Adding upstream version 7.2.6.upstream/7.2.6
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/usage/extensions')
-rw-r--r--doc/usage/extensions/autodoc.rst853
-rw-r--r--doc/usage/extensions/autosectionlabel.rst56
-rw-r--r--doc/usage/extensions/autosummary.rst364
-rw-r--r--doc/usage/extensions/coverage.rst99
-rw-r--r--doc/usage/extensions/doctest.rst385
-rw-r--r--doc/usage/extensions/duration.rst11
-rw-r--r--doc/usage/extensions/example_google.py309
-rw-r--r--doc/usage/extensions/example_google.rst17
-rw-r--r--doc/usage/extensions/example_numpy.py350
-rw-r--r--doc/usage/extensions/example_numpy.rst17
-rw-r--r--doc/usage/extensions/extlinks.rst69
-rw-r--r--doc/usage/extensions/githubpages.rst16
-rw-r--r--doc/usage/extensions/graphviz.rst239
-rw-r--r--doc/usage/extensions/ifconfig.rst38
-rw-r--r--doc/usage/extensions/imgconverter.rst55
-rw-r--r--doc/usage/extensions/index.rst81
-rw-r--r--doc/usage/extensions/inheritance.rst174
-rw-r--r--doc/usage/extensions/intersphinx.rst250
-rw-r--r--doc/usage/extensions/linkcode.rst51
-rw-r--r--doc/usage/extensions/math.rst320
-rw-r--r--doc/usage/extensions/napoleon.rst574
-rw-r--r--doc/usage/extensions/todo.rst62
-rw-r--r--doc/usage/extensions/viewcode.rst106
23 files changed, 4496 insertions, 0 deletions
diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst
new file mode 100644
index 0000000..1498ae9
--- /dev/null
+++ b/doc/usage/extensions/autodoc.rst
@@ -0,0 +1,853 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.autodoc` -- Include documentation from docstrings
+==================================================================
+
+.. module:: sphinx.ext.autodoc
+ :synopsis: Include documentation from docstrings.
+
+.. index:: pair: automatic; documentation
+ single: docstring
+
+This extension can import the modules you are documenting, and pull in
+documentation from docstrings in a semi-automatic way.
+
+.. note::
+
+ For Sphinx (actually, the Python interpreter that executes Sphinx) to find
+ your module, it must be importable. That means that the module or the
+ package must be in one of the directories on :data:`sys.path` -- adapt your
+ :data:`sys.path` in the configuration file accordingly.
+
+.. warning::
+
+ :mod:`~sphinx.ext.autodoc` **imports** the modules to be documented. If any
+ modules have side effects on import, these will be executed by ``autodoc``
+ when ``sphinx-build`` is run.
+
+ If you document scripts (as opposed to library modules), make sure their main
+ routine is protected by a ``if __name__ == '__main__'`` condition.
+
+For this to work, the docstrings must of course be written in correct
+reStructuredText. You can then use all of the usual Sphinx markup in the
+docstrings, and it will end up correctly in the documentation. Together with
+hand-written documentation, this technique eases the pain of having to maintain
+two locations for documentation, while at the same time avoiding
+auto-generated-looking pure API documentation.
+
+If you prefer `NumPy`_ or `Google`_ style docstrings over reStructuredText,
+you can also enable the :mod:`napoleon <sphinx.ext.napoleon>` extension.
+:mod:`napoleon <sphinx.ext.napoleon>` is a preprocessor that converts your
+docstrings to correct reStructuredText before :mod:`autodoc` processes them.
+
+.. _Google: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings
+.. _NumPy: https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
+
+
+Directives
+----------
+
+:mod:`autodoc` provides several directives that are versions of the usual
+:rst:dir:`py:module`, :rst:dir:`py:class` and so forth. On parsing time, they
+import the corresponding module and extract the docstring of the given objects,
+inserting them into the page source under a suitable :rst:dir:`py:module`,
+:rst:dir:`py:class` etc. directive.
+
+.. note::
+
+ Just as :rst:dir:`py:class` respects the current :rst:dir:`py:module`,
+ :rst:dir:`autoclass` will also do so. Likewise, :rst:dir:`automethod` will
+ respect the current :rst:dir:`py:class`.
+
+
+.. rst:directive:: automodule
+ autoclass
+ autoexception
+
+ Document a module, class or exception. All three directives will by default
+ only insert the docstring of the object itself::
+
+ .. autoclass:: Noodle
+
+ will produce source like this::
+
+ .. class:: Noodle
+
+ Noodle's docstring.
+
+ The "auto" directives can also contain content of their own, it will be
+ inserted into the resulting non-auto directive source after the docstring
+ (but before any automatic member documentation).
+
+ Therefore, you can also mix automatic and non-automatic member documentation,
+ like so::
+
+ .. autoclass:: Noodle
+ :members: eat, slurp
+
+ .. method:: boil(time=10)
+
+ Boil the noodle *time* minutes.
+
+ .. rubric:: Options
+
+ .. rst:directive:option:: members
+ :type: no value or comma separated list
+
+ If set, autodoc will generate document for the members of the target
+ module, class or exception.
+
+ For example::
+
+ .. automodule:: noodle
+ :members:
+
+ will document all module members (recursively), and ::
+
+ .. autoclass:: Noodle
+ :members:
+
+ will document all class member methods and properties.
+
+ By default, autodoc will not generate document for the members that are
+ private, not having docstrings, inherited from super class, or special
+ members.
+
+ For modules, ``__all__`` will be respected when looking for members unless
+ you give the ``ignore-module-all`` flag option. Without
+ ``ignore-module-all``, the order of the members will also be the order in
+ ``__all__``.
+
+ You can also give an explicit list of members; only these will then be
+ documented::
+
+ .. autoclass:: Noodle
+ :members: eat, slurp
+
+ .. rst:directive:option:: undoc-members
+ :type: no value
+
+ If set, autodoc will also generate document for the members not having
+ docstrings::
+
+ .. automodule:: noodle
+ :members:
+ :undoc-members:
+
+ .. rst:directive:option:: private-members
+ :type: no value or comma separated list
+
+ If set, autodoc will also generate document for the private members
+ (that is, those named like ``_private`` or ``__private``)::
+
+ .. automodule:: noodle
+ :members:
+ :private-members:
+
+ It can also take an explicit list of member names to be documented as
+ arguments::
+
+ .. automodule:: noodle
+ :members:
+ :private-members: _spicy, _garlickly
+
+ .. versionadded:: 1.1
+ .. versionchanged:: 3.2
+ The option can now take arguments.
+
+ .. rst:directive:option:: special-members
+ :type: no value or comma separated list
+
+ If set, autodoc will also generate document for the special members
+ (that is, those named like ``__special__``)::
+
+ .. autoclass:: my.Class
+ :members:
+ :special-members:
+
+ It can also take an explicit list of member names to be documented as
+ arguments::
+
+ .. autoclass:: my.Class
+ :members:
+ :special-members: __init__, __name__
+
+ .. versionadded:: 1.1
+
+ .. versionchanged:: 1.2
+ The option can now take arguments
+
+ **Options and advanced usage**
+
+ * If you want to make the ``members`` option (or other options described
+ below) the default, see :confval:`autodoc_default_options`.
+
+ .. tip::
+
+ You can use a negated form, :samp:`'no-{flag}'`, as an option of
+ autodoc directive, to disable it temporarily. For example::
+
+ .. automodule:: foo
+ :no-undoc-members:
+
+ .. tip::
+
+ You can use autodoc directive options to temporarily override or
+ extend default options which takes list as an input. For example::
+
+ .. autoclass:: Noodle
+ :members: eat
+ :private-members: +_spicy, _garlickly
+
+ .. versionchanged:: 3.5
+ The default options can be overridden or extended temporarily.
+
+ * autodoc considers a member private if its docstring contains
+ ``:meta private:`` in its :ref:`info-field-lists`.
+ For example:
+
+ .. code-block:: python
+
+ def my_function(my_arg, my_other_arg):
+ """blah blah blah
+
+ :meta private:
+ """
+
+ .. versionadded:: 3.0
+
+ * autodoc considers a member public if its docstring contains
+ ``:meta public:`` in its :ref:`info-field-lists`, even if it starts with
+ an underscore.
+ For example:
+
+ .. code-block:: python
+
+ def _my_function(my_arg, my_other_arg):
+ """blah blah blah
+
+ :meta public:
+ """
+
+ .. versionadded:: 3.1
+
+ * autodoc considers a variable member does not have any default value if its
+ docstring contains ``:meta hide-value:`` in its :ref:`info-field-lists`.
+ Example:
+
+ .. code-block:: python
+
+ var1 = None #: :meta hide-value:
+
+ .. versionadded:: 3.5
+
+ * For classes and exceptions, members inherited from base classes will be
+ left out when documenting all members, unless you give the
+ ``inherited-members`` option, in addition to ``members``::
+
+ .. autoclass:: Noodle
+ :members:
+ :inherited-members:
+
+ This can be combined with ``undoc-members`` to document *all* available
+ members of the class or module.
+
+ It can take an ancestor class not to document inherited members from it.
+ By default, members of ``object`` class are not documented. To show them
+ all, give ``None`` to the option.
+
+ For example; If your class ``Foo`` is derived from ``list`` class and
+ you don't want to document ``list.__len__()``, you should specify a
+ option ``:inherited-members: list`` to avoid special members of list
+ class.
+
+ Another example; If your class Foo has ``__str__`` special method and
+ autodoc directive has both ``inherited-members`` and ``special-members``,
+ ``__str__`` will be documented as in the past, but other special method
+ that are not implemented in your class ``Foo``.
+
+ Since v5.0, it can take a comma separated list of ancestor classes. It
+ allows to suppress inherited members of several classes on the module at
+ once by specifying the option to :rst:dir:`automodule` directive.
+
+ Note: this will lead to markup errors if the inherited members come from a
+ module whose docstrings are not reST formatted.
+
+ .. versionadded:: 0.3
+
+ .. versionchanged:: 3.0
+
+ It takes an ancestor class name as an argument.
+
+ .. versionchanged:: 5.0
+
+ It takes a comma separated list of ancestor class names.
+
+ * It's possible to override the signature for explicitly documented callable
+ objects (functions, methods, classes) with the regular syntax that will
+ override the signature gained from introspection::
+
+ .. autoclass:: Noodle(type)
+
+ .. automethod:: eat(persona)
+
+ This is useful if the signature from the method is hidden by a decorator.
+
+ .. versionadded:: 0.4
+
+ * The :rst:dir:`automodule`, :rst:dir:`autoclass` and
+ :rst:dir:`autoexception` directives also support a flag option called
+ ``show-inheritance``. When given, a list of base classes will be inserted
+ just below the class signature (when used with :rst:dir:`automodule`, this
+ will be inserted for every class that is documented in the module).
+
+ .. versionadded:: 0.4
+
+ * All autodoc directives support the ``no-index`` flag option that has the
+ same effect as for standard :rst:dir:`py:function` etc. directives: no
+ index entries are generated for the documented object (and all
+ autodocumented members).
+
+ .. versionadded:: 0.4
+
+ * :rst:dir:`automodule` also recognizes the ``synopsis``, ``platform`` and
+ ``deprecated`` options that the standard :rst:dir:`py:module` directive
+ supports.
+
+ .. versionadded:: 0.5
+
+ * :rst:dir:`automodule` and :rst:dir:`autoclass` also has an ``member-order``
+ option that can be used to override the global value of
+ :confval:`autodoc_member_order` for one directive.
+
+ .. versionadded:: 0.6
+
+ * The directives supporting member documentation also have a
+ ``exclude-members`` option that can be used to exclude single member names
+ from documentation, if all members are to be documented.
+
+ .. versionadded:: 0.6
+
+ * In an :rst:dir:`automodule` directive with the ``members`` option set, only
+ module members whose ``__module__`` attribute is equal to the module name
+ as given to ``automodule`` will be documented. This is to prevent
+ documentation of imported classes or functions. Set the
+ ``imported-members`` option if you want to prevent this behavior and
+ document all available members. Note that attributes from imported modules
+ will not be documented, because attribute documentation is discovered by
+ parsing the source file of the current module.
+
+ .. versionadded:: 1.2
+
+ * Add a list of modules in the :confval:`autodoc_mock_imports` to prevent
+ import errors to halt the building process when some external dependencies
+ are not importable at build time.
+
+ .. versionadded:: 1.3
+
+ * As a hint to autodoc extension, you can put a ``::`` separator in between
+ module name and object name to let autodoc know the correct module name if
+ it is ambiguous. ::
+
+ .. autoclass:: module.name::Noodle
+
+ * :rst:dir:`autoclass` also recognizes the ``class-doc-from`` option that
+ can be used to override the global value of :confval:`autoclass_content`.
+
+ .. versionadded:: 4.1
+
+.. rst:directive:: autofunction
+ autodecorator
+ autodata
+ automethod
+ autoattribute
+ autoproperty
+
+ These work exactly like :rst:dir:`autoclass` etc.,
+ but do not offer the options used for automatic member documentation.
+
+ :rst:dir:`autodata` and :rst:dir:`autoattribute` support the ``annotation``
+ option. The option controls how the value of variable is shown. If specified
+ without arguments, only the name of the variable will be printed, and its value
+ is not shown::
+
+ .. autodata:: CD_DRIVE
+ :annotation:
+
+ If the option specified with arguments, it is printed after the name as a value
+ of the variable::
+
+ .. autodata:: CD_DRIVE
+ :annotation: = your CD device name
+
+ By default, without ``annotation`` option, Sphinx tries to obtain the value of
+ the variable and print it after the name.
+
+ The ``no-value`` option can be used instead of a blank ``annotation`` to show the
+ type hint but not the value::
+
+ .. autodata:: CD_DRIVE
+ :no-value:
+
+ If both the ``annotation`` and ``no-value`` options are used, ``no-value`` has no
+ effect.
+
+ For module data members and class attributes, documentation can either be put
+ into a comment with special formatting (using a ``#:`` to start the comment
+ instead of just ``#``), or in a docstring *after* the definition. Comments
+ need to be either on a line of their own *before* the definition, or
+ immediately after the assignment *on the same line*. The latter form is
+ restricted to one line only.
+
+ This means that in the following class definition, all attributes can be
+ autodocumented::
+
+ class Foo:
+ """Docstring for class Foo."""
+
+ #: Doc comment for class attribute Foo.bar.
+ #: It can have multiple lines.
+ bar = 1
+
+ flox = 1.5 #: Doc comment for Foo.flox. One line only.
+
+ baz = 2
+ """Docstring for class attribute Foo.baz."""
+
+ def __init__(self):
+ #: Doc comment for instance attribute qux.
+ self.qux = 3
+
+ self.spam = 4
+ """Docstring for instance attribute spam."""
+
+ .. versionchanged:: 0.6
+ :rst:dir:`autodata` and :rst:dir:`autoattribute` can now extract
+ docstrings.
+ .. versionchanged:: 1.1
+ Comment docs are now allowed on the same line after an assignment.
+ .. versionchanged:: 1.2
+ :rst:dir:`autodata` and :rst:dir:`autoattribute` have an ``annotation``
+ option.
+ .. versionchanged:: 2.0
+ :rst:dir:`autodecorator` added.
+ .. versionchanged:: 2.1
+ :rst:dir:`autoproperty` added.
+ .. versionchanged:: 3.4
+ :rst:dir:`autodata` and :rst:dir:`autoattribute` now have a ``no-value``
+ option.
+
+ .. note::
+
+ If you document decorated functions or methods, keep in mind that autodoc
+ retrieves its docstrings by importing the module and inspecting the
+ ``__doc__`` attribute of the given function or method. That means that if
+ a decorator replaces the decorated function with another, it must copy the
+ original ``__doc__`` to the new function.
+
+
+Configuration
+-------------
+
+There are also config values that you can set:
+
+.. confval:: autoclass_content
+
+ This value selects what content will be inserted into the main body of an
+ :rst:dir:`autoclass` directive. The possible values are:
+
+ ``"class"``
+ Only the class' docstring is inserted. This is the default. You can
+ still document ``__init__`` as a separate method using
+ :rst:dir:`automethod` or the ``members`` option to :rst:dir:`autoclass`.
+ ``"both"``
+ Both the class' and the ``__init__`` method's docstring are concatenated
+ and inserted.
+ ``"init"``
+ Only the ``__init__`` method's docstring is inserted.
+
+ .. versionadded:: 0.3
+
+ If the class has no ``__init__`` method or if the ``__init__`` method's
+ docstring is empty, but the class has a ``__new__`` method's docstring,
+ it is used instead.
+
+ .. versionadded:: 1.4
+
+.. confval:: autodoc_class_signature
+
+ This value selects how the signature will be displayed for the class defined
+ by :rst:dir:`autoclass` directive. The possible values are:
+
+ ``"mixed"``
+ Display the signature with the class name.
+ ``"separated"``
+ Display the signature as a method.
+
+ The default is ``"mixed"``.
+
+ .. versionadded:: 4.1
+
+.. confval:: autodoc_member_order
+
+ This value selects if automatically documented members are sorted
+ alphabetical (value ``'alphabetical'``), by member type (value
+ ``'groupwise'``) or by source order (value ``'bysource'``). The default is
+ alphabetical.
+
+ Note that for source order, the module must be a Python module with the
+ source code available.
+
+ .. versionadded:: 0.6
+ .. versionchanged:: 1.0
+ Support for ``'bysource'``.
+
+.. confval:: autodoc_default_flags
+
+ This value is a list of autodoc directive flags that should be automatically
+ applied to all autodoc directives. The supported flags are ``'members'``,
+ ``'undoc-members'``, ``'private-members'``, ``'special-members'``,
+ ``'inherited-members'``, ``'show-inheritance'``, ``'ignore-module-all'``
+ and ``'exclude-members'``.
+
+ .. versionadded:: 1.0
+
+ .. deprecated:: 1.8
+
+ Integrated into :confval:`autodoc_default_options`.
+
+.. confval:: autodoc_default_options
+
+ The default options for autodoc directives. They are applied to all autodoc
+ directives automatically. It must be a dictionary which maps option names
+ to the values. For example::
+
+ autodoc_default_options = {
+ 'members': 'var1, var2',
+ 'member-order': 'bysource',
+ 'special-members': '__init__',
+ 'undoc-members': True,
+ 'exclude-members': '__weakref__'
+ }
+
+ Setting ``None`` or ``True`` to the value is equivalent to giving only the
+ option name to the directives.
+
+ The supported options are ``'members'``, ``'member-order'``,
+ ``'undoc-members'``, ``'private-members'``, ``'special-members'``,
+ ``'inherited-members'``, ``'show-inheritance'``, ``'ignore-module-all'``,
+ ``'imported-members'``, ``'exclude-members'``, ``'class-doc-from'`` and
+ ``'no-value'``.
+
+ .. versionadded:: 1.8
+
+ .. versionchanged:: 2.0
+ Accepts ``True`` as a value.
+
+ .. versionchanged:: 2.1
+ Added ``'imported-members'``.
+
+ .. versionchanged:: 4.1
+ Added ``'class-doc-from'``.
+
+ .. versionchanged:: 4.5
+ Added ``'no-value'``.
+
+.. confval:: autodoc_docstring_signature
+
+ Functions imported from C modules cannot be introspected, and therefore the
+ signature for such functions cannot be automatically determined. However, it
+ is an often-used convention to put the signature into the first line of the
+ function's docstring.
+
+ If this boolean value is set to ``True`` (which is the default), autodoc will
+ look at the first line of the docstring for functions and methods, and if it
+ looks like a signature, use the line as the signature and remove it from the
+ docstring content.
+
+ autodoc will continue to look for multiple signature lines,
+ stopping at the first line that does not look like a signature.
+ This is useful for declaring overloaded function signatures.
+
+ .. versionadded:: 1.1
+ .. versionchanged:: 3.1
+
+ Support overloaded signatures
+
+ .. versionchanged:: 4.0
+
+ Overloaded signatures do not need to be separated by a backslash
+
+.. confval:: autodoc_mock_imports
+
+ This value contains a list of modules to be mocked up. This is useful when
+ some external dependencies are not met at build time and break the building
+ process. You may only specify the root package of the dependencies
+ themselves and omit the sub-modules:
+
+ .. code-block:: python
+
+ autodoc_mock_imports = ["django"]
+
+ Will mock all imports under the ``django`` package.
+
+ .. versionadded:: 1.3
+
+ .. versionchanged:: 1.6
+ This config value only requires to declare the top-level modules that
+ should be mocked.
+
+.. confval:: autodoc_typehints
+
+ This value controls how to represent typehints. The setting takes the
+ following values:
+
+ * ``'signature'`` -- Show typehints in the signature (default)
+ * ``'description'`` -- Show typehints as content of the function or method
+ The typehints of overloaded functions or methods will still be represented
+ in the signature.
+ * ``'none'`` -- Do not show typehints
+ * ``'both'`` -- Show typehints in the signature and as content of
+ the function or method
+
+ Overloaded functions or methods will not have typehints included in the
+ description because it is impossible to accurately represent all possible
+ overloads as a list of parameters.
+
+ .. versionadded:: 2.1
+ .. versionadded:: 3.0
+
+ New option ``'description'`` is added.
+
+ .. versionadded:: 4.1
+
+ New option ``'both'`` is added.
+
+.. confval:: autodoc_typehints_description_target
+
+ This value controls whether the types of undocumented parameters and return
+ values are documented when ``autodoc_typehints`` is set to ``description``.
+
+ The default value is ``"all"``, meaning that types are documented for all
+ parameters and return values, whether they are documented or not.
+
+ When set to ``"documented"``, types will only be documented for a parameter
+ or a return value that is already documented by the docstring.
+
+ With ``"documented_params"``, parameter types will only be annotated if the
+ parameter is documented in the docstring. The return type is always
+ annotated (except if it is ``None``).
+
+ .. versionadded:: 4.0
+
+ .. versionadded:: 5.0
+
+ New option ``'documented_params'`` is added.
+
+.. confval:: autodoc_type_aliases
+
+ A dictionary for users defined `type aliases`__ that maps a type name to the
+ full-qualified object name. It is used to keep type aliases not evaluated in
+ the document. Defaults to empty (``{}``).
+
+ The type aliases are only available if your program enables :pep:`Postponed
+ Evaluation of Annotations (PEP 563) <563>` feature via ``from __future__ import
+ annotations``.
+
+ For example, there is code using a type alias::
+
+ from __future__ import annotations
+
+ AliasType = Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]
+
+ def f() -> AliasType:
+ ...
+
+ If ``autodoc_type_aliases`` is not set, autodoc will generate internal mark-up
+ from this code as following::
+
+ .. py:function:: f() -> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]
+
+ ...
+
+ If you set ``autodoc_type_aliases`` as
+ ``{'AliasType': 'your.module.AliasType'}``, it generates the following document
+ internally::
+
+ .. py:function:: f() -> your.module.AliasType:
+
+ ...
+
+ .. __: https://mypy.readthedocs.io/en/latest/kinds_of_types.html#type-aliases
+ .. versionadded:: 3.3
+
+.. confval:: autodoc_typehints_format
+
+ This value controls the format of typehints. The setting takes the
+ following values:
+
+ * ``'fully-qualified'`` -- Show the module name and its name of typehints
+ * ``'short'`` -- Suppress the leading module names of the typehints
+ (ex. ``io.StringIO`` -> ``StringIO``) (default)
+
+ .. versionadded:: 4.4
+
+ .. versionchanged:: 5.0
+
+ The default setting was changed to ``'short'``
+
+.. confval:: autodoc_preserve_defaults
+
+ If True, the default argument values of functions will be not evaluated on
+ generating document. It preserves them as is in the source code.
+
+ .. versionadded:: 4.0
+
+ Added as an experimental feature. This will be integrated into autodoc core
+ in the future.
+
+.. confval:: autodoc_warningiserror
+
+ This value controls the behavior of :option:`sphinx-build -W` during
+ importing modules.
+ If ``False`` is given, autodoc forcedly suppresses the error if the imported
+ module emits warnings. By default, ``True``.
+
+.. confval:: autodoc_inherit_docstrings
+
+ This value controls the docstrings inheritance.
+ If set to True the docstring for classes or methods, if not explicitly set,
+ is inherited from parents.
+
+ The default is ``True``.
+
+ .. versionadded:: 1.7
+
+.. confval:: suppress_warnings
+ :no-index:
+
+ :mod:`autodoc` supports to suppress warning messages via
+ :confval:`suppress_warnings`. It allows following warnings types in
+ addition:
+
+ * autodoc
+ * autodoc.import_object
+
+
+Docstring preprocessing
+-----------------------
+
+autodoc provides the following additional events:
+
+.. event:: autodoc-process-docstring (app, what, name, obj, options, lines)
+
+ .. versionadded:: 0.4
+
+ Emitted when autodoc has read and processed a docstring. *lines* is a list
+ of strings -- the lines of the processed docstring -- that the event handler
+ can modify **in place** to change what Sphinx puts into the output.
+
+ :param app: the Sphinx application object
+ :param what: the type of the object which the docstring belongs to (one of
+ ``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``,
+ ``"attribute"``)
+ :param name: the fully qualified name of the object
+ :param obj: the object itself
+ :param options: the options given to the directive: an object with attributes
+ ``inherited_members``, ``undoc_members``, ``show_inheritance`` and
+ ``no-index`` that are true if the flag option of same name was given to the
+ auto directive
+ :param lines: the lines of the docstring, see above
+
+.. event:: autodoc-before-process-signature (app, obj, bound_method)
+
+ .. versionadded:: 2.4
+
+ Emitted before autodoc formats a signature for an object. The event handler
+ can modify an object to change its signature.
+
+ :param app: the Sphinx application object
+ :param obj: the object itself
+ :param bound_method: a boolean indicates an object is bound method or not
+
+.. event:: autodoc-process-signature (app, what, name, obj, options, signature, return_annotation)
+
+ .. versionadded:: 0.5
+
+ Emitted when autodoc has formatted a signature for an object. The event
+ handler can return a new tuple ``(signature, return_annotation)`` to change
+ what Sphinx puts into the output.
+
+ :param app: the Sphinx application object
+ :param what: the type of the object which the docstring belongs to (one of
+ ``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``,
+ ``"attribute"``)
+ :param name: the fully qualified name of the object
+ :param obj: the object itself
+ :param options: the options given to the directive: an object with attributes
+ ``inherited_members``, ``undoc_members``, ``show_inheritance`` and
+ ``no-index`` that are true if the flag option of same name was given to the
+ auto directive
+ :param signature: function signature, as a string of the form
+ ``"(parameter_1, parameter_2)"``, or ``None`` if introspection didn't
+ succeed and signature wasn't specified in the directive.
+ :param return_annotation: function return annotation as a string of the form
+ ``" -> annotation"``, or ``None`` if there is no return annotation
+
+The :mod:`sphinx.ext.autodoc` module provides factory functions for commonly
+needed docstring processing in event :event:`autodoc-process-docstring`:
+
+.. autofunction:: cut_lines
+.. autofunction:: between
+
+.. event:: autodoc-process-bases (app, name, obj, options, bases)
+
+ Emitted when autodoc has read and processed a class to determine the
+ base-classes. *bases* is a list of classes that the event handler can
+ modify **in place** to change what Sphinx puts into the output. It's
+ emitted only if ``show-inheritance`` option given.
+
+ :param app: the Sphinx application object
+ :param name: the fully qualified name of the object
+ :param obj: the object itself
+ :param options: the options given to the class directive
+ :param bases: the list of base classes signature. see above.
+
+ .. versionadded:: 4.1
+ .. versionchanged:: 4.3
+
+ ``bases`` can contain a string as a base class name. It will be processed
+ as reST mark-up'ed text.
+
+
+Skipping members
+----------------
+
+autodoc allows the user to define a custom method for determining whether a
+member should be included in the documentation by using the following event:
+
+.. event:: autodoc-skip-member (app, what, name, obj, skip, options)
+
+ .. versionadded:: 0.5
+
+ Emitted when autodoc has to decide whether a member should be included in the
+ documentation. The member is excluded if a handler returns ``True``. It is
+ included if the handler returns ``False``.
+
+ If more than one enabled extension handles the ``autodoc-skip-member``
+ event, autodoc will use the first non-``None`` value returned by a handler.
+ Handlers should return ``None`` to fall back to the skipping behavior of
+ autodoc and other enabled extensions.
+
+ :param app: the Sphinx application object
+ :param what: the type of the object which the docstring belongs to (one of
+ ``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``,
+ ``"attribute"``)
+ :param name: the fully qualified name of the object
+ :param obj: the object itself
+ :param skip: a boolean indicating if autodoc will skip this member if the
+ user handler does not override the decision
+ :param options: the options given to the directive: an object with attributes
+ ``inherited_members``, ``undoc_members``, ``show_inheritance`` and
+ ``no-index`` that are true if the flag option of same name was given to the
+ auto directive
diff --git a/doc/usage/extensions/autosectionlabel.rst b/doc/usage/extensions/autosectionlabel.rst
new file mode 100644
index 0000000..b5b9b51
--- /dev/null
+++ b/doc/usage/extensions/autosectionlabel.rst
@@ -0,0 +1,56 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.autosectionlabel` -- Allow reference sections using its title
+==============================================================================
+
+.. module:: sphinx.ext.autosectionlabel
+ :synopsis: Allow reference section its title.
+
+.. versionadded:: 1.4
+
+This extension allows you to refer sections its title. This affects to the
+reference role (:rst:role:`ref`).
+
+For example::
+
+ A Plain Title
+ -------------
+
+ This is the text of the section.
+
+ It refers to the section title, see :ref:`A Plain Title`.
+
+
+Internally, this extension generates the labels for each section. If same
+section names are used in whole of document, any one is used for a target by
+default. The ``autosectionlabel_prefix_document`` configuration variable can be
+used to make headings which appear multiple times but in different documents
+unique.
+
+
+Configuration
+-------------
+
+.. confval:: autosectionlabel_prefix_document
+
+ True to prefix each section label with the name of the document it is in,
+ followed by a colon. For example, ``index:Introduction`` for a section
+ called ``Introduction`` that appears in document ``index.rst``. Useful for
+ avoiding ambiguity when the same section heading appears in different
+ documents.
+
+.. confval:: autosectionlabel_maxdepth
+
+ If set, autosectionlabel chooses the sections for labeling by its depth. For
+ example, when set 1 to ``autosectionlabel_maxdepth``, labels are generated
+ only for top level sections, and deeper sections are not labeled. It
+ defaults to ``None`` (disabled).
+
+
+Debugging
+---------
+
+The ``WARNING: undefined label`` indicates that your reference in
+:rst:role:`ref` is mis-spelled. Invoking :program:`sphinx-build` with ``-vv``
+(see :option:`-v`) will print all section names and the labels that have been
+generated for them. This output can help finding the right reference label.
diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst
new file mode 100644
index 0000000..a18460b
--- /dev/null
+++ b/doc/usage/extensions/autosummary.rst
@@ -0,0 +1,364 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.autosummary` -- Generate autodoc summaries
+===========================================================
+
+.. module:: sphinx.ext.autosummary
+ :synopsis: Generate autodoc summaries
+
+.. versionadded:: 0.6
+
+This extension generates function/method/attribute summary lists, similar to
+those output e.g. by Epydoc and other API doc generation tools. This is
+especially useful when your docstrings are long and detailed, and putting each
+one of them on a separate page makes them easier to read.
+
+The :mod:`sphinx.ext.autosummary` extension does this in two parts:
+
+1. There is an :rst:dir:`autosummary` directive for generating summary listings
+ that contain links to the documented items, and short summary blurbs
+ extracted from their docstrings.
+
+2. A :rst:dir:`autosummary` directive also generates short "stub" files for the
+ entries listed in its content. These files by default contain only the
+ corresponding :mod:`sphinx.ext.autodoc` directive, but can be customized with
+ templates.
+
+ The :program:`sphinx-autogen` script is also able to generate "stub" files
+ from command line.
+
+.. rst:directive:: autosummary
+
+ Insert a table that contains links to documented items, and a short summary
+ blurb (the first sentence of the docstring) for each of them.
+
+ The :rst:dir:`autosummary` directive can also optionally serve as a
+ :rst:dir:`toctree` entry for the included items. Optionally, stub
+ ``.rst`` files for these items can also be automatically generated
+ when :confval:`autosummary_generate` is `True`.
+
+ For example, ::
+
+ .. currentmodule:: sphinx
+
+ .. autosummary::
+
+ environment.BuildEnvironment
+ util.relative_uri
+
+ produces a table like this:
+
+ .. currentmodule:: sphinx
+
+ .. autosummary::
+
+ environment.BuildEnvironment
+ util.relative_uri
+
+ .. currentmodule:: sphinx.ext.autosummary
+
+ Autosummary preprocesses the docstrings and signatures with the same
+ :event:`autodoc-process-docstring` and :event:`autodoc-process-signature`
+ hooks as :mod:`~sphinx.ext.autodoc`.
+
+ **Options**
+
+ * If you want the :rst:dir:`autosummary` table to also serve as a
+ :rst:dir:`toctree` entry, use the ``toctree`` option, for example::
+
+ .. autosummary::
+ :toctree: DIRNAME
+
+ sphinx.environment.BuildEnvironment
+ sphinx.util.relative_uri
+
+ The ``toctree`` option also signals to the :program:`sphinx-autogen` script
+ that stub pages should be generated for the entries listed in this
+ directive. The option accepts a directory name as an argument;
+ :program:`sphinx-autogen` will by default place its output in this
+ directory. If no argument is given, output is placed in the same directory
+ as the file that contains the directive.
+
+ You can also use ``caption`` option to give a caption to the toctree.
+
+ .. versionadded:: 3.1
+
+ caption option added.
+
+ * If you don't want the :rst:dir:`autosummary` to show function signatures in
+ the listing, include the ``nosignatures`` option::
+
+ .. autosummary::
+ :nosignatures:
+
+ sphinx.environment.BuildEnvironment
+ sphinx.util.relative_uri
+
+ * You can specify a custom template with the ``template`` option.
+ For example, ::
+
+ .. autosummary::
+ :template: mytemplate.rst
+
+ sphinx.environment.BuildEnvironment
+
+ would use the template :file:`mytemplate.rst` in your
+ :confval:`templates_path` to generate the pages for all entries
+ listed. See `Customizing templates`_ below.
+
+ .. versionadded:: 1.0
+
+ * You can specify the ``recursive`` option to generate documents for
+ modules and sub-packages recursively. It defaults to disabled.
+ For example, ::
+
+ .. autosummary::
+ :recursive:
+
+ sphinx.environment.BuildEnvironment
+
+ .. versionadded:: 3.1
+
+
+:program:`sphinx-autogen` -- generate autodoc stub pages
+--------------------------------------------------------
+
+The :program:`sphinx-autogen` script can be used to conveniently generate stub
+documentation pages for items included in :rst:dir:`autosummary` listings.
+
+For example, the command ::
+
+ $ sphinx-autogen -o generated *.rst
+
+will read all :rst:dir:`autosummary` tables in the :file:`*.rst` files that have
+the ``:toctree:`` option set, and output corresponding stub pages in directory
+``generated`` for all documented items. The generated pages by default contain
+text of the form::
+
+ sphinx.util.relative_uri
+ ========================
+
+ .. autofunction:: sphinx.util.relative_uri
+
+If the ``-o`` option is not given, the script will place the output files in the
+directories specified in the ``:toctree:`` options.
+
+For more information, refer to the :doc:`sphinx-autogen documentation
+</man/sphinx-autogen>`
+
+
+Generating stub pages automatically
+-----------------------------------
+
+If you do not want to create stub pages with :program:`sphinx-autogen`, you can
+also use these config values:
+
+.. confval:: autosummary_context
+
+ A dictionary of values to pass into the template engine's context for
+ autosummary stubs files.
+
+ .. versionadded:: 3.1
+
+.. confval:: autosummary_generate
+
+ Boolean indicating whether to scan all found documents for autosummary
+ directives, and to generate stub pages for each. It is enabled by default.
+
+ Can also be a list of documents for which stub pages should be generated.
+
+ The new files will be placed in the directories specified in the
+ ``:toctree:`` options of the directives.
+
+ .. versionchanged:: 2.3
+
+ Emits :event:`autodoc-skip-member` event as :mod:`~sphinx.ext.autodoc`
+ does.
+
+ .. versionchanged:: 4.0
+
+ Enabled by default.
+
+.. confval:: autosummary_generate_overwrite
+
+ If true, autosummary overwrites existing files by generated stub pages.
+ Defaults to true (enabled).
+
+ .. versionadded:: 3.0
+
+.. confval:: autosummary_mock_imports
+
+ This value contains a list of modules to be mocked up. See
+ :confval:`autodoc_mock_imports` for more details. It defaults to
+ :confval:`autodoc_mock_imports`.
+
+ .. versionadded:: 2.0
+
+.. confval:: autosummary_imported_members
+
+ A boolean flag indicating whether to document classes and functions imported
+ in modules. Default is ``False``
+
+ .. versionadded:: 2.1
+
+ .. versionchanged:: 4.4
+
+ If ``autosummary_ignore_module_all`` is ``False``, this configuration
+ value is ignored for members listed in ``__all__``.
+
+.. confval:: autosummary_ignore_module_all
+
+ If ``False`` and a module has the ``__all__`` attribute set, autosummary
+ documents every member listed in ``__all__`` and no others. Default is
+ ``True``
+
+ Note that if an imported member is listed in ``__all__``, it will be
+ documented regardless of the value of ``autosummary_imported_members``. To
+ match the behaviour of ``from module import *``, set
+ ``autosummary_ignore_module_all`` to False and
+ ``autosummary_imported_members`` to True.
+
+ .. versionadded:: 4.4
+
+.. confval:: autosummary_filename_map
+
+ A dict mapping object names to filenames. This is necessary to avoid
+ filename conflicts where multiple objects have names that are
+ indistinguishable when case is ignored, on file systems where filenames
+ are case-insensitive.
+
+ .. versionadded:: 3.2
+
+.. _autosummary-customizing-templates:
+
+Customizing templates
+---------------------
+
+.. versionadded:: 1.0
+
+You can customize the stub page templates, in a similar way as the HTML Jinja
+templates, see :ref:`templating`. (:class:`~sphinx.application.TemplateBridge`
+is not supported.)
+
+.. note::
+
+ If you find yourself spending much time tailoring the stub templates, this
+ may indicate that it's a better idea to write custom narrative documentation
+ instead.
+
+Autosummary uses the following Jinja template files:
+
+- :file:`autosummary/base.rst` -- fallback template
+- :file:`autosummary/module.rst` -- template for modules
+- :file:`autosummary/class.rst` -- template for classes
+- :file:`autosummary/function.rst` -- template for functions
+- :file:`autosummary/attribute.rst` -- template for class attributes
+- :file:`autosummary/method.rst` -- template for class methods
+
+The following variables are available in the templates:
+
+.. currentmodule:: None
+
+.. data:: name
+
+ Name of the documented object, excluding the module and class parts.
+
+.. data:: objname
+
+ Name of the documented object, excluding the module parts.
+
+.. data:: fullname
+
+ Full name of the documented object, including module and class parts.
+
+.. data:: objtype
+
+ Type of the documented object, one of ``"module"``, ``"function"``,
+ ``"class"``, ``"method"``, ``"attribute"``, ``"data"``, ``"object"``,
+ ``"exception"``, ``"newvarattribute"``, ``"newtypedata"``, ``"property"``.
+
+.. data:: module
+
+ Name of the module the documented object belongs to.
+
+.. data:: class
+
+ Name of the class the documented object belongs to. Only available for
+ methods and attributes.
+
+.. data:: underline
+
+ A string containing ``len(full_name) * '='``. Use the ``underline`` filter
+ instead.
+
+.. data:: members
+
+ List containing names of all members of the module or class. Only available
+ for modules and classes.
+
+.. data:: inherited_members
+
+ List containing names of all inherited members of class. Only available for
+ classes.
+
+ .. versionadded:: 1.8.0
+
+.. data:: functions
+
+ List containing names of "public" functions in the module. Here, "public"
+ means that the name does not start with an underscore. Only available
+ for modules.
+
+.. data:: classes
+
+ List containing names of "public" classes in the module. Only available for
+ modules.
+
+.. data:: exceptions
+
+ List containing names of "public" exceptions in the module. Only available
+ for modules.
+
+.. data:: methods
+
+ List containing names of "public" methods in the class. Only available for
+ classes.
+
+.. data:: attributes
+
+ List containing names of "public" attributes in the class/module. Only
+ available for classes and modules.
+
+ .. versionchanged:: 3.1
+
+ Attributes of modules are supported.
+
+.. data:: modules
+
+ List containing names of "public" modules in the package. Only available for
+ modules that are packages and the ``recursive`` option is on.
+
+ .. versionadded:: 3.1
+
+Additionally, the following filters are available
+
+.. function:: escape(s)
+
+ Escape any special characters in the text to be used in formatting RST
+ contexts. For instance, this prevents asterisks making things bold. This
+ replaces the builtin Jinja `escape filter`_ that does html-escaping.
+
+.. function:: underline(s, line='=')
+ :no-index:
+
+ Add a title underline to a piece of text.
+
+For instance, ``{{ fullname | escape | underline }}`` should be used to produce
+the title of a page.
+
+.. note::
+
+ You can use the :rst:dir:`autosummary` directive in the stub pages.
+ Stub pages are generated also based on these directives.
+
+.. _`escape filter`: https://jinja.palletsprojects.com/en/3.0.x/templates/#jinja-filters.escape
diff --git a/doc/usage/extensions/coverage.rst b/doc/usage/extensions/coverage.rst
new file mode 100644
index 0000000..1390ebf
--- /dev/null
+++ b/doc/usage/extensions/coverage.rst
@@ -0,0 +1,99 @@
+:mod:`sphinx.ext.coverage` -- Collect doc coverage stats
+========================================================
+
+.. module:: sphinx.ext.coverage
+ :synopsis: Check Python modules and C API for coverage in the documentation.
+
+This extension features one additional builder, the :class:`CoverageBuilder`.
+
+.. class:: CoverageBuilder
+
+ To use this builder, activate the coverage extension in your configuration
+ file and give ``-b coverage`` on the command line.
+
+.. todo:: Write this section.
+
+Several configuration values can be used to specify what the builder
+should check:
+
+.. confval:: coverage_ignore_modules
+
+.. confval:: coverage_ignore_functions
+
+.. confval:: coverage_ignore_classes
+
+.. confval:: coverage_ignore_pyobjects
+
+ List of `Python regular expressions`_.
+
+ If any of these regular expressions matches any part of the full import path
+ of a Python object, that Python object is excluded from the documentation
+ coverage report.
+
+ .. _Python regular expressions: https://docs.python.org/library/re
+
+ .. versionadded:: 2.1
+
+.. confval:: coverage_c_path
+
+.. confval:: coverage_c_regexes
+
+.. confval:: coverage_ignore_c_items
+
+.. confval:: coverage_write_headline
+
+ Set to ``False`` to not write headlines.
+
+ .. versionadded:: 1.1
+
+.. confval:: coverage_skip_undoc_in_source
+
+ Skip objects that are not documented in the source with a docstring.
+ ``False`` by default.
+
+ .. versionadded:: 1.1
+
+.. confval:: coverage_show_missing_items
+
+ Print objects that are missing to standard output also.
+ ``False`` by default.
+
+ .. versionadded:: 3.1
+
+.. confval:: coverage_statistics_to_report
+
+ Print a tabluar report of the coverage statistics to the coverage report.
+ ``True`` by default.
+
+ Example output:
+
+ .. code-block:: text
+
+ +-----------------------+----------+--------------+
+ | Module | Coverage | Undocumented |
+ +=======================+==========+==============+
+ | package.foo_module | 100.00% | 0 |
+ +-----------------------+----------+--------------+
+ | package.bar_module | 83.33% | 1 |
+ +-----------------------+----------+--------------+
+
+ .. versionadded:: 7.2
+
+.. confval:: coverage_statistics_to_stdout
+
+ Print a tabluar report of the coverage statistics to standard output.
+ ``False`` by default.
+
+ Example output:
+
+ .. code-block:: text
+
+ +-----------------------+----------+--------------+
+ | Module | Coverage | Undocumented |
+ +=======================+==========+==============+
+ | package.foo_module | 100.00% | 0 |
+ +-----------------------+----------+--------------+
+ | package.bar_module | 83.33% | 1 |
+ +-----------------------+----------+--------------+
+
+ .. versionadded:: 7.2
diff --git a/doc/usage/extensions/doctest.rst b/doc/usage/extensions/doctest.rst
new file mode 100644
index 0000000..1848e1f
--- /dev/null
+++ b/doc/usage/extensions/doctest.rst
@@ -0,0 +1,385 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.doctest` -- Test snippets in the documentation
+===============================================================
+
+.. module:: sphinx.ext.doctest
+ :synopsis: Test snippets in the documentation.
+
+.. index:: pair: automatic; testing
+ single: doctest
+ pair: testing; snippets
+
+
+It is often helpful to include snippets of code in your documentation and
+demonstrate the results of executing them. But it is important to ensure that
+the documentation stays up-to-date with the code.
+
+This extension allows you to test such code snippets in the documentation in
+a natural way. If you mark the code blocks as shown here, the ``doctest``
+builder will collect them and run them as doctest tests.
+
+Within each document, you can assign each snippet to a *group*. Each group
+consists of:
+
+* zero or more *setup code* blocks (e.g. importing the module to test)
+* one or more *test* blocks
+
+When building the docs with the ``doctest`` builder, groups are collected for
+each document and run one after the other, first executing setup code blocks,
+then the test blocks in the order they appear in the file.
+
+There are two kinds of test blocks:
+
+* *doctest-style* blocks mimic interactive sessions by interleaving Python code
+ (including the interpreter prompt) and output.
+
+* *code-output-style* blocks consist of an ordinary piece of Python code, and
+ optionally, a piece of output for that code.
+
+
+Directives
+----------
+
+The *group* argument below is interpreted as follows: if it is empty, the block
+is assigned to the group named ``default``. If it is ``*``, the block is
+assigned to all groups (including the ``default`` group). Otherwise, it must be
+a comma-separated list of group names.
+
+.. rst:directive:: .. testsetup:: [group]
+
+ A setup code block. This code is not shown in the output for other builders,
+ but executed before the doctests of the group(s) it belongs to.
+
+
+.. rst:directive:: .. testcleanup:: [group]
+
+ A cleanup code block. This code is not shown in the output for other
+ builders, but executed after the doctests of the group(s) it belongs to.
+
+ .. versionadded:: 1.1
+
+
+.. rst:directive:: .. doctest:: [group]
+
+ A doctest-style code block. You can use standard :mod:`doctest` flags for
+ controlling how actual output is compared with what you give as output. The
+ default set of flags is specified by the :confval:`doctest_default_flags`
+ configuration variable.
+
+ This directive supports five options:
+
+ * ``hide``, a flag option, hides the doctest block in other builders. By
+ default it is shown as a highlighted doctest block.
+
+ * ``options``, a string option, can be used to give a comma-separated list of
+ doctest flags that apply to each example in the tests. (You still can give
+ explicit flags per example, with doctest comments, but they will show up in
+ other builders too.)
+
+ * ``pyversion``, a string option, can be used to specify the required Python
+ version for the example to be tested. For instance, in the following case
+ the example will be tested only for Python versions greater than 3.10::
+
+ .. doctest::
+ :pyversion: > 3.10
+
+ The following operands are supported:
+
+ * ``~=``: Compatible release clause
+ * ``==``: Version matching clause
+ * ``!=``: Version exclusion clause
+ * ``<=``, ``>=``: Inclusive ordered comparison clause
+ * ``<``, ``>``: Exclusive ordered comparison clause
+ * ``===``: Arbitrary equality clause.
+
+ ``pyversion`` option is followed :pep:`PEP-440: Version Specifiers
+ <440#version-specifiers>`.
+
+ .. versionadded:: 1.6
+
+ .. versionchanged:: 1.7
+
+ Supported PEP-440 operands and notations
+
+ * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option,
+ doctest flags (comments looking like ``# doctest: FLAG, ...``) at the
+ ends of lines and ``<BLANKLINE>`` markers are removed (or not removed)
+ individually. Default is ``trim-doctest-flags``.
+
+ Note that like with standard doctests, you have to use ``<BLANKLINE>`` to
+ signal a blank line in the expected output. The ``<BLANKLINE>`` is removed
+ when building presentation output (HTML, LaTeX etc.).
+
+ Also, you can give inline doctest options, like in doctest::
+
+ >>> datetime.date.now() # doctest: +SKIP
+ datetime.date(2008, 1, 1)
+
+ They will be respected when the test is run, but stripped from presentation
+ output.
+
+
+.. rst:directive:: .. testcode:: [group]
+
+ A code block for a code-output-style test.
+
+ This directive supports three options:
+
+ * ``hide``, a flag option, hides the code block in other builders. By
+ default it is shown as a highlighted code block.
+
+ * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option,
+ doctest flags (comments looking like ``# doctest: FLAG, ...``) at the
+ ends of lines and ``<BLANKLINE>`` markers are removed (or not removed)
+ individually. Default is ``trim-doctest-flags``.
+
+ .. note::
+
+ Code in a ``testcode`` block is always executed all at once, no matter how
+ many statements it contains. Therefore, output will *not* be generated
+ for bare expressions -- use ``print``. Example::
+
+ .. testcode::
+
+ 1+1 # this will give no output!
+ print(2+2) # this will give output
+
+ .. testoutput::
+
+ 4
+
+ Also, please be aware that since the doctest module does not support
+ mixing regular output and an exception message in the same snippet, this
+ applies to testcode/testoutput as well.
+
+
+.. rst:directive:: .. testoutput:: [group]
+
+ The corresponding output, or the exception message, for the last
+ :rst:dir:`testcode` block.
+
+ This directive supports four options:
+
+ * ``hide``, a flag option, hides the output block in other builders. By
+ default it is shown as a literal block without highlighting.
+
+ * ``options``, a string option, can be used to give doctest flags
+ (comma-separated) just like in normal doctest blocks.
+
+ * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option,
+ doctest flags (comments looking like ``# doctest: FLAG, ...``) at the
+ ends of lines and ``<BLANKLINE>`` markers are removed (or not removed)
+ individually. Default is ``trim-doctest-flags``.
+
+ Example::
+
+ .. testcode::
+
+ print('Output text.')
+
+ .. testoutput::
+ :hide:
+ :options: -ELLIPSIS, +NORMALIZE_WHITESPACE
+
+ Output text.
+
+The following is an example for the usage of the directives. The test via
+:rst:dir:`doctest` and the test via :rst:dir:`testcode` and
+:rst:dir:`testoutput` are equivalent. ::
+
+ The parrot module
+ =================
+
+ .. testsetup:: *
+
+ import parrot
+
+ The parrot module is a module about parrots.
+
+ Doctest example:
+
+ .. doctest::
+
+ >>> parrot.voom(3000)
+ This parrot wouldn't voom if you put 3000 volts through it!
+
+ Test-Output example:
+
+ .. testcode::
+
+ parrot.voom(3000)
+
+ This would output:
+
+ .. testoutput::
+
+ This parrot wouldn't voom if you put 3000 volts through it!
+
+
+Skipping tests conditionally
+----------------------------
+
+``skipif``, a string option, can be used to skip directives conditionally. This
+may be useful e.g. when a different set of tests should be run depending on the
+environment (hardware, network/VPN, optional dependencies or different versions
+of dependencies). The ``skipif`` option is supported by all of the doctest
+directives. Below are typical use cases for ``skipif`` when used for different
+directives:
+
+- :rst:dir:`testsetup` and :rst:dir:`testcleanup`
+
+ - conditionally skip test setup and/or cleanup
+ - customize setup/cleanup code per environment
+
+- :rst:dir:`doctest`
+
+ - conditionally skip both a test and its output verification
+
+- :rst:dir:`testcode`
+
+ - conditionally skip a test
+ - customize test code per environment
+
+- :rst:dir:`testoutput`
+
+ - conditionally skip output assertion for a skipped test
+ - expect different output depending on the environment
+
+The value of the ``skipif`` option is evaluated as a Python expression. If the
+result is a true value, the directive is omitted from the test run just as if
+it wasn't present in the file at all.
+
+Instead of repeating an expression, the :confval:`doctest_global_setup`
+configuration option can be used to assign it to a variable which can then be
+used instead.
+
+Here's an example which skips some tests if Pandas is not installed:
+
+.. code-block:: py
+ :caption: conf.py
+
+ extensions = ['sphinx.ext.doctest']
+ doctest_global_setup = '''
+ try:
+ import pandas as pd
+ except ImportError:
+ pd = None
+ '''
+
+.. code-block:: rst
+ :caption: contents.rst
+
+ .. testsetup::
+ :skipif: pd is None
+
+ data = pd.Series([42])
+
+ .. doctest::
+ :skipif: pd is None
+
+ >>> data.iloc[0]
+ 42
+
+ .. testcode::
+ :skipif: pd is None
+
+ print(data.iloc[-1])
+
+ .. testoutput::
+ :skipif: pd is None
+
+ 42
+
+
+Configuration
+-------------
+
+The doctest extension uses the following configuration values:
+
+.. confval:: doctest_default_flags
+
+ By default, these options are enabled:
+
+ - ``ELLIPSIS``, allowing you to put ellipses in the expected output that
+ match anything in the actual output;
+ - ``IGNORE_EXCEPTION_DETAIL``, causing everything following the leftmost
+ colon and any module information in the exception name to be ignored;
+ - ``DONT_ACCEPT_TRUE_FOR_1``, rejecting "True" in the output where "1" is
+ given -- the default behavior of accepting this substitution is a relic of
+ pre-Python 2.2 times.
+
+ .. versionadded:: 1.5
+
+.. confval:: doctest_show_successes
+
+ Defaults to ``True``.
+ Controls whether successes are reported.
+
+ For a project with many doctests,
+ it may be useful to set this to ``False`` to only highlight failures.
+
+ .. versionadded:: 7.2
+
+.. confval:: doctest_path
+
+ A list of directories that will be added to :data:`sys.path` when the doctest
+ builder is used. (Make sure it contains absolute paths.)
+
+.. confval:: doctest_global_setup
+
+ Python code that is treated like it were put in a ``testsetup`` directive for
+ *every* file that is tested, and for every group. You can use this to
+ e.g. import modules you will always need in your doctests.
+
+ .. versionadded:: 0.6
+
+.. confval:: doctest_global_cleanup
+
+ Python code that is treated like it were put in a ``testcleanup`` directive
+ for *every* file that is tested, and for every group. You can use this to
+ e.g. remove any temporary files that the tests leave behind.
+
+ .. versionadded:: 1.1
+
+.. confval:: doctest_test_doctest_blocks
+
+ If this is a nonempty string (the default is ``'default'``), standard reST
+ doctest blocks will be tested too. They will be assigned to the group name
+ given.
+
+ reST doctest blocks are simply doctests put into a paragraph of their own,
+ like so::
+
+ Some documentation text.
+
+ >>> print(1)
+ 1
+
+ Some more documentation text.
+
+ (Note that no special ``::`` is used to introduce a doctest block; docutils
+ recognizes them from the leading ``>>>``. Also, no additional indentation is
+ used, though it doesn't hurt.)
+
+ If this value is left at its default value, the above snippet is interpreted
+ by the doctest builder exactly like the following::
+
+ Some documentation text.
+
+ .. doctest::
+
+ >>> print(1)
+ 1
+
+ Some more documentation text.
+
+ This feature makes it easy for you to test doctests in docstrings included
+ with the :mod:`~sphinx.ext.autodoc` extension without marking them up with a
+ special directive.
+
+ Note though that you can't have blank lines in reST doctest blocks. They
+ will be interpreted as one block ending and another one starting. Also,
+ removal of ``<BLANKLINE>`` and ``# doctest:`` options only works in
+ :rst:dir:`doctest` blocks, though you may set :confval:`trim_doctest_flags`
+ to achieve that in all code blocks with Python console content.
diff --git a/doc/usage/extensions/duration.rst b/doc/usage/extensions/duration.rst
new file mode 100644
index 0000000..1213811
--- /dev/null
+++ b/doc/usage/extensions/duration.rst
@@ -0,0 +1,11 @@
+:mod:`sphinx.ext.duration` -- Measure durations of Sphinx processing
+====================================================================
+
+.. module:: sphinx.ext.duration
+ :synopsis: Measure durations of Sphinx processing
+
+.. versionadded:: 2.4
+
+This extension measures durations of Sphinx processing and show its
+result at end of the build. It is useful for inspecting what document
+is slowly built.
diff --git a/doc/usage/extensions/example_google.py b/doc/usage/extensions/example_google.py
new file mode 100644
index 0000000..434fa3b
--- /dev/null
+++ b/doc/usage/extensions/example_google.py
@@ -0,0 +1,309 @@
+"""Example Google style docstrings.
+
+This module demonstrates documentation as specified by the `Google Python
+Style Guide`_. Docstrings may extend over multiple lines. Sections are created
+with a section header and a colon followed by a block of indented text.
+
+Example:
+ Examples can be given using either the ``Example`` or ``Examples``
+ sections. Sections support any reStructuredText formatting, including
+ literal blocks::
+
+ $ python example_google.py
+
+Section breaks are created by resuming unindented text. Section breaks
+are also implicitly created anytime a new section starts.
+
+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.
+
+Todo:
+ * For module TODOs
+ * You have to also use ``sphinx.ext.todo`` extension
+
+.. _Google Python Style Guide:
+ https://google.github.io/styleguide/pyguide.html
+
+"""
+
+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:
+
+ Args:
+ param1 (int): The first parameter.
+ param2 (str): The second parameter.
+
+ Returns:
+ bool: The return value. True for success, False otherwise.
+ """
+
+
+def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
+ """Example function with PEP 484 type annotations.
+
+ Args:
+ param1: The first parameter.
+ param2: The second parameter.
+
+ Returns:
+ The return value. True for success, 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 ``Args`` 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. The "(type)" is optional.
+
+ Multiple paragraphs are supported in parameter
+ descriptions.
+
+ Args:
+ param1 (int): The first parameter.
+ param2 (:obj:`str`, optional): The second parameter. Defaults to None.
+ Second line of description should be indented.
+ *args: Variable length argument list.
+ **kwargs: Arbitrary keyword arguments.
+
+ Returns:
+ bool: True if successful, False otherwise.
+
+ The return type is optional and may be specified at the beginning of
+ the ``Returns`` section followed by a colon.
+
+ The ``Returns`` section may span multiple lines and paragraphs.
+ Following lines should be indented to match the first line.
+
+ 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:
+ 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.
+
+ Args:
+ 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 ``Args`` section.
+
+ Args:
+ msg (str): Human readable string describing the exception.
+ code (:obj:`int`, optional): Error code.
+
+ Attributes:
+ msg (str): Human readable string describing the exception.
+ code (int): Exception 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 ``Args`` section.
+
+ Args:
+ param1 (str): Description of `param1`.
+ param2 (:obj:`int`, optional): Description of `param2`. Multiple
+ lines are supported.
+ param3 (list(str)): 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 ``Args`` section.
+
+ Args:
+ param1: The first parameter.
+ param2: The second parameter.
+
+ Returns:
+ 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
+
+class ExamplePEP526Class:
+ """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. If ``napoleon_attr_annotations``
+ is True, types can be specified in the class body using ``PEP 526``
+ annotations.
+
+ Attributes:
+ attr1: Description of `attr1`.
+ attr2: Description of `attr2`.
+
+ """
+
+ attr1: str
+ attr2: int
diff --git a/doc/usage/extensions/example_google.rst b/doc/usage/extensions/example_google.rst
new file mode 100644
index 0000000..a06f161
--- /dev/null
+++ b/doc/usage/extensions/example_google.rst
@@ -0,0 +1,17 @@
+:orphan:
+
+.. _example_google:
+
+Example Google Style Python Docstrings
+======================================
+
+.. seealso::
+
+ :ref:`example_numpy`
+
+.. only:: builder_html
+
+ Download: :download:`example_google.py <example_google.py>`
+
+.. literalinclude:: example_google.py
+ :language: python
diff --git a/doc/usage/extensions/example_numpy.py b/doc/usage/extensions/example_numpy.py
new file mode 100644
index 0000000..2346b1e
--- /dev/null
+++ b/doc/usage/extensions/example_numpy.py
@@ -0,0 +1,350 @@
+"""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:
+ 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]
+
+ """
+ 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
diff --git a/doc/usage/extensions/example_numpy.rst b/doc/usage/extensions/example_numpy.rst
new file mode 100644
index 0000000..38d3439
--- /dev/null
+++ b/doc/usage/extensions/example_numpy.rst
@@ -0,0 +1,17 @@
+:orphan:
+
+.. _example_numpy:
+
+Example NumPy Style Python Docstrings
+======================================
+
+.. seealso::
+
+ :ref:`example_google`
+
+.. only:: builder_html
+
+ Download: :download:`example_numpy.py <example_numpy.py>`
+
+.. literalinclude:: example_numpy.py
+ :language: python
diff --git a/doc/usage/extensions/extlinks.rst b/doc/usage/extensions/extlinks.rst
new file mode 100644
index 0000000..97359ab
--- /dev/null
+++ b/doc/usage/extensions/extlinks.rst
@@ -0,0 +1,69 @@
+:mod:`sphinx.ext.extlinks` -- Markup to shorten external links
+==============================================================
+
+.. module:: sphinx.ext.extlinks
+ :synopsis: Allow inserting external links with common base URLs easily.
+.. moduleauthor:: Georg Brandl
+
+.. versionadded:: 1.0
+
+This extension is meant to help with the common pattern of having many external
+links that point to URLs on one and the same site, e.g. links to bug trackers,
+version control web interfaces, or simply subpages in other websites. It does
+so by providing aliases to base URLs, so that you only need to give the subpage
+name when creating a link.
+
+Let's assume that you want to include many links to issues at the Sphinx
+tracker, at :samp:`https://github.com/sphinx-doc/sphinx/issues/{num}`. Typing
+this URL again and again is tedious, so you can use :mod:`~sphinx.ext.extlinks`
+to avoid repeating yourself.
+
+The extension adds a config value:
+
+.. confval:: extlinks
+
+ This config value must be a dictionary of external sites, mapping unique
+ short alias names to a *base URL* and a *caption*. For example, to create an
+ alias for the above mentioned issues, you would add ::
+
+ extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
+ 'issue %s')}
+
+ Now, you can use the alias name as a new role, e.g. ``:issue:`123```. This
+ then inserts a link to https://github.com/sphinx-doc/sphinx/issues/123.
+ As you can see, the target given in the role is substituted in the *base URL*
+ in the place of ``%s``.
+
+ The link caption depends on the second item in the tuple, the *caption*:
+
+ - If *caption* is ``None``, the link caption is the full URL.
+ - If *caption* is a string, then it must contain ``%s`` exactly once. In
+ this case the link caption is *caption* with the partial URL substituted
+ for ``%s`` -- in the above example, the link caption would be
+ ``issue 123``.
+
+ To produce a literal ``%`` in either *base URL* or *caption*, use ``%%``::
+
+ extlinks = {'KnR': ('https://example.org/K%%26R/page/%s',
+ '[K&R; page %s]')}
+
+ You can also use the usual "explicit title" syntax supported by other roles
+ that generate links, i.e. ``:issue:`this issue <123>```. In this case, the
+ *caption* is not relevant.
+
+ .. versionchanged:: 4.0
+
+ Support to substitute by '%s' in the caption.
+
+.. note::
+
+ Since links are generated from the role in the reading stage, they appear as
+ ordinary links to e.g. the ``linkcheck`` builder.
+
+.. confval:: extlinks_detect_hardcoded_links
+
+ If enabled, extlinks emits a warning if a hardcoded link is replaceable
+ by an extlink, and suggests a replacement via warning. It defaults to
+ ``False``.
+
+ .. versionadded:: 4.5
diff --git a/doc/usage/extensions/githubpages.rst b/doc/usage/extensions/githubpages.rst
new file mode 100644
index 0000000..6d56a30
--- /dev/null
+++ b/doc/usage/extensions/githubpages.rst
@@ -0,0 +1,16 @@
+:mod:`sphinx.ext.githubpages` -- Publish HTML docs in GitHub Pages
+==================================================================
+
+.. module:: sphinx.ext.githubpages
+ :synopsis: Publish HTML docs in GitHub Pages
+
+.. versionadded:: 1.4
+
+.. versionchanged:: 2.0
+ Support ``CNAME`` file
+
+This extension creates ``.nojekyll`` file on generated HTML directory to publish
+the document on GitHub Pages.
+
+It also creates a ``CNAME`` file for custom domains when :confval:`html_baseurl`
+set.
diff --git a/doc/usage/extensions/graphviz.rst b/doc/usage/extensions/graphviz.rst
new file mode 100644
index 0000000..c134f6d
--- /dev/null
+++ b/doc/usage/extensions/graphviz.rst
@@ -0,0 +1,239 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.graphviz` -- Add Graphviz graphs
+=================================================
+
+.. module:: sphinx.ext.graphviz
+ :synopsis: Support for Graphviz graphs.
+
+.. versionadded:: 0.6
+
+This extension allows you to embed `Graphviz <https://graphviz.org/>`_ graphs in
+your documents.
+
+It adds these directives:
+
+.. rst:directive:: graphviz
+
+ Directive to embed graphviz code. The input code for ``dot`` is given as the
+ content. For example::
+
+ .. graphviz::
+
+ digraph foo {
+ "bar" -> "baz";
+ }
+
+ In HTML output, the code will be rendered to a PNG or SVG image (see
+ :confval:`graphviz_output_format`). In LaTeX output, the code will be
+ rendered to an embeddable PDF file.
+
+ You can also embed external dot files, by giving the file name as an
+ argument to :rst:dir:`graphviz` and no additional content::
+
+ .. graphviz:: external.dot
+
+ As for all file references in Sphinx, if the filename is absolute, it is
+ taken as relative to the source directory.
+
+ .. versionchanged:: 1.1
+ Added support for external files.
+
+ .. rubric:: options
+
+ .. rst:directive:option:: alt: alternate text
+ :type: text
+
+ The alternate text of the graph. By default, the graph code is used to
+ the alternate text.
+
+ .. versionadded:: 1.0
+
+ .. rst:directive:option:: align: alignment of the graph
+ :type: left, center or right
+
+ The horizontal alignment of the graph.
+
+ .. versionadded:: 1.5
+
+ .. rst:directive:option:: caption: caption of the graph
+ :type: text
+
+ The caption of the graph.
+
+ .. versionadded:: 1.1
+
+ .. rst:directive:option:: layout: layout type of the graph
+ :type: text
+
+ The layout of the graph (ex. ``dot``, ``neato`` and so on). A path to the
+ graphviz commands are also allowed. By default, :confval:`graphviz_dot`
+ is used.
+
+ .. versionadded:: 1.4
+ .. versionchanged:: 2.2
+
+ Renamed from ``graphviz_dot``
+
+ .. rst:directive:option:: name: label
+ :type: text
+
+ The label of the graph.
+
+ .. versionadded:: 1.6
+
+ .. rst:directive:option:: class: class names
+ :type: a list of class names separated by spaces
+
+ The class name of the graph.
+
+ .. versionadded:: 2.4
+
+
+.. rst:directive:: graph
+
+ Directive for embedding a single undirected graph. The name is given as a
+ directive argument, the contents of the graph are the directive content.
+ This is a convenience directive to generate ``graph <name> { <content> }``.
+
+ For example::
+
+ .. graph:: foo
+
+ "bar" -- "baz";
+
+ .. note:: The graph name is passed unchanged to Graphviz. If it contains
+ non-alphanumeric characters (e.g. a dash), you will have to double-quote
+ it.
+
+ .. rubric:: options
+
+ Same as :rst:dir:`graphviz`.
+
+ .. rst:directive:option:: alt: alternate text
+ :type: text
+
+ .. versionadded:: 1.0
+
+ .. rst:directive:option:: align: alignment of the graph
+ :type: left, center or right
+
+ .. versionadded:: 1.5
+
+ .. rst:directive:option:: caption: caption of the graph
+ :type: text
+
+ .. versionadded:: 1.1
+
+ .. rst:directive:option:: layout: layout type of the graph
+ :type: text
+
+ .. versionadded:: 1.4
+ .. versionchanged:: 2.2
+
+ Renamed from ``graphviz_dot``
+
+ .. rst:directive:option:: name: label
+ :type: text
+
+ .. versionadded:: 1.6
+
+ .. rst:directive:option:: class: class names
+ :type: a list of class names separated by spaces
+
+ The class name of the graph.
+
+ .. versionadded:: 2.4
+
+
+.. rst:directive:: digraph
+
+ Directive for embedding a single directed graph. The name is given as a
+ directive argument, the contents of the graph are the directive content.
+ This is a convenience directive to generate ``digraph <name> { <content> }``.
+
+ For example::
+
+ .. digraph:: foo
+
+ "bar" -> "baz" -> "quux";
+
+ .. rubric:: options
+
+ Same as :rst:dir:`graphviz`.
+
+ .. rst:directive:option:: alt: alternate text
+ :type: text
+
+ .. versionadded:: 1.0
+
+ .. rst:directive:option:: align: alignment of the graph
+ :type: left, center or right
+
+ .. versionadded:: 1.5
+
+ .. rst:directive:option:: caption: caption of the graph
+ :type: text
+
+ .. versionadded:: 1.1
+
+ .. rst:directive:option:: layout: layout type of the graph
+ :type: text
+
+ .. versionadded:: 1.4
+ .. versionchanged:: 2.2
+
+ Renamed from ``graphviz_dot``
+
+ .. rst:directive:option:: name: label
+ :type: text
+
+ .. versionadded:: 1.6
+
+ .. rst:directive:option:: class: class names
+ :type: a list of class names separated by spaces
+
+ The class name of the graph.
+
+ .. versionadded:: 2.4
+
+
+There are also these config values:
+
+.. confval:: graphviz_dot
+
+ The command name with which to invoke ``dot``. The default is ``'dot'``; you
+ may need to set this to a full path if ``dot`` is not in the executable
+ search path.
+
+ Since this setting is not portable from system to system, it is normally not
+ useful to set it in ``conf.py``; rather, giving it on the
+ :program:`sphinx-build` command line via the :option:`-D <sphinx-build -D>`
+ option should be preferable, like this::
+
+ sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html
+
+.. confval:: graphviz_dot_args
+
+ Additional command-line arguments to give to dot, as a list. The default is
+ an empty list. This is the right place to set global graph, node or edge
+ attributes via dot's ``-G``, ``-N`` and ``-E`` options.
+
+.. confval:: graphviz_output_format
+
+ The output format for Graphviz when building HTML files. This must be either
+ ``'png'`` or ``'svg'``; the default is ``'png'``. If ``'svg'`` is used, in
+ order to make the URL links work properly, an appropriate ``target``
+ attribute must be set, such as ``"_top"`` and ``"_blank"``. For example, the
+ link in the following graph should work in the svg output: ::
+
+ .. graphviz::
+
+ digraph example {
+ a [label="sphinx", href="https://www.sphinx-doc.org/", target="_top"];
+ b [label="other"];
+ a -> b;
+ }
+
+ .. versionadded:: 1.0
+ Previously, output always was PNG.
diff --git a/doc/usage/extensions/ifconfig.rst b/doc/usage/extensions/ifconfig.rst
new file mode 100644
index 0000000..837c0b3
--- /dev/null
+++ b/doc/usage/extensions/ifconfig.rst
@@ -0,0 +1,38 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.ifconfig` -- Include content based on configuration
+====================================================================
+
+.. module:: sphinx.ext.ifconfig
+ :synopsis: Include documentation content based on configuration values.
+
+This extension is quite simple, and features only one directive:
+
+.. warning::
+
+ This directive is designed to control only content of document. It could
+ not control sections, labels and so on.
+
+.. rst:directive:: ifconfig
+
+ Include content of the directive only if the Python expression given as an
+ argument is ``True``, evaluated in the namespace of the project's
+ configuration (that is, all registered variables from :file:`conf.py` are
+ available).
+
+ For example, one could write ::
+
+ .. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
+
+ This stuff is only included in the built docs for unstable versions.
+
+ To make a custom config value known to Sphinx, use
+ :func:`~sphinx.application.Sphinx.add_config_value` in the setup function in
+ :file:`conf.py`, e.g.::
+
+ def setup(app):
+ app.add_config_value('releaselevel', '', 'env')
+
+ The second argument is the default value, the third should always be
+ ``'env'`` for such values (it selects if Sphinx re-reads the documents if the
+ value changes).
diff --git a/doc/usage/extensions/imgconverter.rst b/doc/usage/extensions/imgconverter.rst
new file mode 100644
index 0000000..b9af22d
--- /dev/null
+++ b/doc/usage/extensions/imgconverter.rst
@@ -0,0 +1,55 @@
+.. _sphinx.ext.imgconverter:
+
+:mod:`sphinx.ext.imgconverter` -- A reference image converter using Imagemagick
+===============================================================================
+
+.. module:: sphinx.ext.imgconverter
+ :synopsis: Convert images to appropriate format for builders
+
+.. versionadded:: 1.6
+
+This extension converts images in your document to appropriate format for
+builders. For example, it allows you to use SVG images with LaTeX builder.
+As a result, you don't mind what image format the builder supports.
+
+By default the extension uses ImageMagick_ to perform conversions,
+and will not work if ImageMagick is not installed.
+
+.. _ImageMagick: https://www.imagemagick.org
+
+.. note::
+
+ ImageMagick rasterizes a SVG image on conversion. As a result, the image
+ becomes not scalable. To avoid that, please use other image converters like
+ `sphinxcontrib-svg2pdfconverter`__ (which uses Inkscape or
+ ``rsvg-convert``).
+
+.. __: https://github.com/missinglinkelectronics/sphinxcontrib-svg2pdfconverter
+
+
+Configuration
+-------------
+
+.. confval:: image_converter
+
+ A path to a conversion command. By default, the imgconverter finds
+ the command from search paths.
+
+ On Unix platforms, the command :command:`convert` is used by default.
+
+ On Windows, the command :command:`magick` is used by default.
+
+ .. versionchanged:: 3.1
+
+ Use :command:`magick` command by default on windows
+
+.. confval:: image_converter_args
+
+ Additional command-line arguments to give to :command:`convert`, as a list.
+ The default is an empty list ``[]``.
+
+ On Windows, it defaults to ``["convert"]``.
+
+ .. versionchanged:: 3.1
+
+ Use ``["convert"]`` by default on Windows
diff --git a/doc/usage/extensions/index.rst b/doc/usage/extensions/index.rst
new file mode 100644
index 0000000..929f2b6
--- /dev/null
+++ b/doc/usage/extensions/index.rst
@@ -0,0 +1,81 @@
+==========
+Extensions
+==========
+
+Since many projects will need special features in their documentation, Sphinx
+allows adding "extensions" to the build process, each of which can modify
+almost any aspect of document processing.
+
+This chapter describes the extensions bundled with Sphinx. For the API
+documentation on writing your own extension, refer to :ref:`dev-extensions`.
+
+
+.. _builtin-extensions:
+
+Built-in extensions
+-------------------
+
+These extensions are built in and can be activated by respective entries in the
+:confval:`extensions` configuration value:
+
+.. toctree::
+ :maxdepth: 1
+
+ autodoc
+ autosectionlabel
+ autosummary
+ coverage
+ doctest
+ duration
+ extlinks
+ githubpages
+ graphviz
+ ifconfig
+ imgconverter
+ inheritance
+ intersphinx
+ linkcode
+ math
+ napoleon
+ todo
+ viewcode
+
+
+.. _third-party-extensions:
+
+Third-party extensions
+----------------------
+
+You can find several extensions contributed by users in the `sphinx-contrib`__
+organization. If you wish to include your extension in this organization,
+simply follow the instructions provided in the `github-administration`__
+project. This is optional and there are several extensions hosted elsewhere.
+The `awesome-sphinxdoc`__ and `sphinx-extensions`__ projects are both curated
+lists of Sphinx packages, and many packages use the
+`Framework :: Sphinx :: Extension`__ and
+`Framework :: Sphinx :: Theme`__ trove classifiers for Sphinx extensions and
+themes, respectively.
+
+.. __: https://github.com/sphinx-contrib/
+.. __: https://github.com/sphinx-contrib/github-administration
+.. __: https://github.com/yoloseem/awesome-sphinxdoc
+.. __: https://sphinx-extensions.readthedocs.io/en/latest/
+.. __: https://pypi.org/search/?c=Framework+%3A%3A+Sphinx+%3A%3A+Extension
+.. __: https://pypi.org/search/?c=Framework+%3A%3A+Sphinx+%3A%3A+Theme
+
+Where to put your own extensions?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Extensions local to a project should be put within the project's directory
+structure. Set Python's module search path, ``sys.path``, accordingly so that
+Sphinx can find them. For example, if your extension ``foo.py`` lies in the
+``exts`` subdirectory of the project root, put into :file:`conf.py`::
+
+ import sys, os
+
+ sys.path.append(os.path.abspath('exts'))
+
+ extensions = ['foo']
+
+You can also install extensions anywhere else on ``sys.path``, e.g. in the
+``site-packages`` directory.
diff --git a/doc/usage/extensions/inheritance.rst b/doc/usage/extensions/inheritance.rst
new file mode 100644
index 0000000..33284b5
--- /dev/null
+++ b/doc/usage/extensions/inheritance.rst
@@ -0,0 +1,174 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.inheritance_diagram` -- Include inheritance diagrams
+=====================================================================
+
+.. module:: sphinx.ext.inheritance_diagram
+ :synopsis: Support for displaying inheritance diagrams via graphviz.
+
+.. versionadded:: 0.6
+
+This extension allows you to include inheritance diagrams, rendered via the
+:mod:`Graphviz extension <sphinx.ext.graphviz>`.
+
+It adds this directive:
+
+.. rst:directive:: inheritance-diagram
+
+ This directive has one or more arguments, each giving a module or class
+ name. Class names can be unqualified; in that case they are taken to exist
+ in the currently described module (see :rst:dir:`py:module`).
+
+ For each given class, and each class in each given module, the base classes
+ are determined. Then, from all classes and their base classes, a graph is
+ generated which is then rendered via the graphviz extension to a directed
+ graph.
+
+ This directive supports an option called ``parts`` that, if given, must be an
+ integer, advising the directive to keep that many dot-separated parts
+ in the displayed names (from right to left). For example, ``parts=1`` will
+ only display class names, without the names of the modules that contain
+ them.
+
+ .. versionchanged:: 2.0
+ The value of for ``parts`` can also be negative, indicating how many
+ parts to drop from the left. For example, if all your class names start
+ with ``lib.``, you can give ``:parts: -1`` to remove that prefix from the
+ displayed node names.
+
+ The directive also supports a ``private-bases`` flag option; if given,
+ private base classes (those whose name starts with ``_``) will be included.
+
+ You can use ``caption`` option to give a caption to the diagram.
+
+ .. versionchanged:: 1.1
+ Added ``private-bases`` option; previously, all bases were always
+ included.
+
+ .. versionchanged:: 1.5
+ Added ``caption`` option
+
+ It also supports a ``top-classes`` option which requires one or more class
+ names separated by comma. If specified inheritance traversal will stop at the
+ specified class names. Given the following Python module::
+
+ """
+ A
+ / \
+ B C
+ / \ / \
+ E D F
+ """
+
+ class A:
+ pass
+
+ class B(A):
+ pass
+
+ class C(A):
+ pass
+
+ class D(B, C):
+ pass
+
+ class E(B):
+ pass
+
+ class F(C):
+ pass
+
+ If you have specified a module in the inheritance diagram like this::
+
+ .. inheritance-diagram:: dummy.test
+ :top-classes: dummy.test.B, dummy.test.C
+
+ any base classes which are ancestors to ``top-classes`` and are also defined
+ in the same module will be rendered as stand alone nodes. In this example
+ class A will be rendered as stand alone node in the graph. This is a known
+ issue due to how this extension works internally.
+
+ If you don't want class A (or any other ancestors) to be visible then specify
+ only the classes you would like to generate the diagram for like this::
+
+ .. inheritance-diagram:: dummy.test.D dummy.test.E dummy.test.F
+ :top-classes: dummy.test.B, dummy.test.C
+
+ .. versionchanged:: 1.7
+ Added ``top-classes`` option to limit the scope of inheritance graphs.
+
+
+Examples
+--------
+
+The following are different inheritance diagrams for the internal
+``InheritanceDiagram`` class that implements the directive.
+
+With full names::
+
+ .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
+
+.. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
+
+
+Showing class names only::
+
+ .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
+ :parts: 1
+
+.. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
+ :parts: 1
+
+Stopping the diagram at :class:`sphinx.util.docutils.SphinxDirective` (the
+highest superclass still part of Sphinx), and dropping the common left-most
+part (``sphinx``) from all names::
+
+ .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
+ :top-classes: sphinx.util.docutils.SphinxDirective
+ :parts: -1
+
+.. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
+ :top-classes: sphinx.util.docutils.SphinxDirective
+ :parts: -1
+
+.. py:class:: sphinx.ext.inheritance_diagram.InheritanceDiagram
+ :no-contents-entry:
+ :no-index-entry:
+
+ The internal class that implements the ``inheritance-diagram`` directive.
+
+
+Configuration
+-------------
+
+.. confval:: inheritance_graph_attrs
+
+ A dictionary of graphviz graph attributes for inheritance diagrams.
+
+ For example::
+
+ inheritance_graph_attrs = dict(rankdir="LR", size='"6.0, 8.0"',
+ fontsize=14, ratio='compress')
+
+.. confval:: inheritance_node_attrs
+
+ A dictionary of graphviz node attributes for inheritance diagrams.
+
+ For example::
+
+ inheritance_node_attrs = dict(shape='ellipse', fontsize=14, height=0.75,
+ color='dodgerblue1', style='filled')
+
+.. confval:: inheritance_edge_attrs
+
+ A dictionary of graphviz edge attributes for inheritance diagrams.
+
+.. confval:: inheritance_alias
+
+ Allows mapping the full qualified name of the class to custom values
+ (useful when exposing the underlying path of a class is not desirable,
+ e.g. it's a private class and should not be instantiated by the user).
+
+ For example::
+
+ inheritance_alias = {'_pytest.Magic': 'pytest.Magic'}
diff --git a/doc/usage/extensions/intersphinx.rst b/doc/usage/extensions/intersphinx.rst
new file mode 100644
index 0000000..5aaaf9f
--- /dev/null
+++ b/doc/usage/extensions/intersphinx.rst
@@ -0,0 +1,250 @@
+:mod:`sphinx.ext.intersphinx` -- Link to other projects' documentation
+======================================================================
+
+.. module:: sphinx.ext.intersphinx
+ :synopsis: Link to other Sphinx documentation.
+
+.. index:: pair: automatic; linking
+
+.. versionadded:: 0.5
+
+This extension can generate links to the documentation of objects in external
+projects, either explicitly through the :rst:role:`external` role, or as a
+fallback resolution for any other cross-reference.
+
+Usage for fallback resolution is simple: whenever Sphinx encounters a
+cross-reference that has no matching target in the current documentation set,
+it looks for targets in the external documentation sets configured in
+:confval:`intersphinx_mapping`. A reference like
+``:py:class:`zipfile.ZipFile``` can then link to the Python documentation
+for the ZipFile class, without you having to specify where it is located
+exactly.
+
+When using the :rst:role:`external` role, you can force lookup to any external
+projects, and optionally to a specific external project.
+A link like ``:external:ref:`comparison manual <comparisons>``` will then link
+to the label "comparisons" in whichever configured external project, if it
+exists,
+and a link like ``:external+python:ref:`comparison manual <comparisons>``` will
+link to the label "comparisons" only in the doc set "python", if it exists.
+
+Behind the scenes, this works as follows:
+
+* Each Sphinx HTML build creates a file named :file:`objects.inv` that contains
+ a mapping from object names to URIs relative to the HTML set's root.
+
+* Projects using the Intersphinx extension can specify the location of such
+ mapping files in the :confval:`intersphinx_mapping` config value. The mapping
+ will then be used to resolve both :rst:role:`external` references, and also
+ otherwise missing references to objects into links to the other documentation.
+
+* By default, the mapping file is assumed to be at the same location as the rest
+ of the documentation; however, the location of the mapping file can also be
+ specified individually, e.g. if the docs should be buildable without Internet
+ access.
+
+
+Configuration
+-------------
+
+To use Intersphinx linking, add ``'sphinx.ext.intersphinx'`` to your
+:confval:`extensions` config value, and use these config values to activate
+linking:
+
+.. confval:: intersphinx_mapping
+
+ This config value contains the locations and names of other projects that
+ should be linked to in this documentation.
+
+ Relative local paths for target locations are taken as relative to the base
+ of the built documentation, while relative local paths for inventory
+ locations are taken as relative to the source directory.
+
+ When fetching remote inventory files, proxy settings will be read from
+ the ``$HTTP_PROXY`` environment variable.
+
+ **Format**
+
+ .. versionadded:: 1.0
+
+ A dictionary mapping unique identifiers to a tuple ``(target, inventory)``.
+ Each ``target`` is the base URI of a foreign Sphinx documentation set and can
+ be a local path or an HTTP URI. The ``inventory`` indicates where the
+ inventory file can be found: it can be ``None`` (an :file:`objects.inv` file
+ at the same location as the base URI) or another local file path or a full
+ HTTP URI to an inventory file.
+
+ The unique identifier can be used in the :rst:role:`external` role, so that
+ it is clear which intersphinx set the target belongs to. A link like
+ ``external:python+ref:`comparison manual <comparisons>``` will link to the
+ label "comparisons" in the doc set "python", if it exists.
+
+ **Example**
+
+ To add links to modules and objects in the Python standard library
+ documentation, use::
+
+ intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
+
+ This will download the corresponding :file:`objects.inv` file from the
+ Internet and generate links to the pages under the given URI. The downloaded
+ inventory is cached in the Sphinx environment, so it must be re-downloaded
+ whenever you do a full rebuild.
+
+ A second example, showing the meaning of a non-``None`` value of the second
+ tuple item::
+
+ intersphinx_mapping = {'python': ('https://docs.python.org/3',
+ 'python-inv.txt')}
+
+ This will read the inventory from :file:`python-inv.txt` in the source
+ directory, but still generate links to the pages under
+ ``https://docs.python.org/3``. It is up to you to update the inventory file
+ as new objects are added to the Python documentation.
+
+ **Multiple targets for the inventory**
+
+ .. versionadded:: 1.3
+
+ Alternative files can be specified for each inventory. One can give a
+ tuple for the second inventory tuple item as shown in the following
+ example. This will read the inventory iterating through the (second)
+ tuple items until the first successful fetch. The primary use case for
+ this to specify mirror sites for server downtime of the primary
+ inventory::
+
+ intersphinx_mapping = {'python': ('https://docs.python.org/3',
+ (None, 'python-inv.txt'))}
+
+ For a set of books edited and tested locally and then published
+ together, it could be helpful to try a local inventory file first,
+ to check references before publication::
+
+ intersphinx_mapping = {
+ 'otherbook':
+ ('https://myproj.readthedocs.io/projects/otherbook/en/latest',
+ ('../../otherbook/build/html/objects.inv', None)),
+ }
+
+ **Old format for this config value**
+
+ .. deprecated:: 6.2
+
+ .. RemovedInSphinx80Warning
+
+ .. caution:: This is the format used before Sphinx 1.0.
+ It is deprecated and will be removed in Sphinx 8.0.
+
+ A dictionary mapping URIs to either ``None`` or an URI. The keys are the
+ base URI of the foreign Sphinx documentation sets and can be local paths or
+ HTTP URIs. The values indicate where the inventory file can be found: they
+ can be ``None`` (at the same location as the base URI) or another local or
+ HTTP URI.
+
+ Example:
+
+ .. code:: python
+
+ intersphinx_mapping = {'https://docs.python.org/': None}
+
+
+.. confval:: intersphinx_cache_limit
+
+ The maximum number of days to cache remote inventories. The default is
+ ``5``, meaning five days. Set this to a negative value to cache inventories
+ for unlimited time.
+
+.. confval:: intersphinx_timeout
+
+ The number of seconds for timeout. The default is ``None``, meaning do not
+ timeout.
+
+ .. note::
+
+ timeout is not a time limit on the entire response download; rather, an
+ exception is raised if the server has not issued a response for timeout
+ seconds.
+
+.. confval:: intersphinx_disabled_reftypes
+
+ .. versionadded:: 4.3
+
+ .. versionchanged:: 5.0
+
+ Changed default value from an empty list to ``['std:doc']``.
+
+ A list of strings being either:
+
+ - the name of a specific reference type in a domain,
+ e.g., ``std:doc``, ``py:func``, or ``cpp:class``,
+ - the name of a domain, and a wildcard, e.g.,
+ ``std:*``, ``py:*``, or ``cpp:*``, or
+ - simply a wildcard ``*``.
+
+ The default value is ``['std:doc']``.
+
+ When a non-:rst:role:`external` cross-reference is being resolved by
+ intersphinx, skip resolution if it matches one of the specifications in this
+ list.
+
+ For example, with ``intersphinx_disabled_reftypes = ['std:doc']``
+ a cross-reference ``:doc:`installation``` will not be attempted to be
+ resolved by intersphinx, but ``:external+otherbook:doc:`installation``` will
+ be attempted to be resolved in the inventory named ``otherbook`` in
+ :confval:`intersphinx_mapping`.
+ At the same time, all cross-references generated in, e.g., Python,
+ declarations will still be attempted to be resolved by intersphinx.
+
+ If ``*`` is in the list of domains, then no non-:rst:role:`external`
+ references will be resolved by intersphinx.
+
+Explicitly Reference External Objects
+-------------------------------------
+
+The Intersphinx extension provides the following role.
+
+.. rst:role:: external
+
+ .. versionadded:: 4.4
+
+ Use Intersphinx to perform lookup only in external projects, and not the
+ current project. Intersphinx still needs to know the type of object you
+ would like to find, so the general form of this role is to write the
+ cross-refererence as if the object is in the current project, but then prefix
+ it with ``:external``.
+ The two forms are then
+
+ - ``:external:domain:reftype:`target```,
+ e.g., ``:external:py:class:`zipfile.ZipFile```, or
+ - ``:external:reftype:`target```,
+ e.g., ``:external:doc:`installation```.
+
+ If you would like to constrain the lookup to a specific external project,
+ then the key of the project, as specified in :confval:`intersphinx_mapping`,
+ is added as well to get the two forms
+
+ - ``:external+invname:domain:reftype:`target```,
+ e.g., ``:external+python:py:class:`zipfile.ZipFile```, or
+ - ``:external+invname:reftype:`target```,
+ e.g., ``:external+python:doc:`installation```.
+
+Showing all links of an Intersphinx mapping file
+------------------------------------------------
+
+To show all Intersphinx links and their targets of an Intersphinx mapping file,
+run ``python -msphinx.ext.intersphinx url-or-path``. This is helpful when
+searching for the root cause of a broken Intersphinx link in a documentation
+project. The following example prints the Intersphinx mapping of the Python 3
+documentation::
+
+ $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
+
+Using Intersphinx with inventory file under Basic Authorization
+---------------------------------------------------------------
+
+Intersphinx supports Basic Authorization like this::
+
+ intersphinx_mapping = {'python': ('https://user:password@docs.python.org/3',
+ None)}
+
+The user and password will be stripped from the URL when generating the links.
diff --git a/doc/usage/extensions/linkcode.rst b/doc/usage/extensions/linkcode.rst
new file mode 100644
index 0000000..e65a0b7
--- /dev/null
+++ b/doc/usage/extensions/linkcode.rst
@@ -0,0 +1,51 @@
+:mod:`sphinx.ext.linkcode` -- Add external links to source code
+===============================================================
+
+.. module:: sphinx.ext.linkcode
+ :synopsis: Add external links to source code.
+.. moduleauthor:: Pauli Virtanen
+
+.. versionadded:: 1.2
+
+This extension looks at your object descriptions (``.. class::``,
+``.. function::`` etc.) and adds external links to code hosted
+somewhere on the web. The intent is similar to the
+``sphinx.ext.viewcode`` extension, but assumes the source code can be
+found somewhere on the Internet.
+
+In your configuration, you need to specify a :confval:`linkcode_resolve`
+function that returns an URL based on the object.
+
+
+Configuration
+-------------
+
+.. confval:: linkcode_resolve
+
+ This is a function ``linkcode_resolve(domain, info)``,
+ which should return the URL to source code corresponding to
+ the object in given domain with given information.
+
+ The function should return ``None`` if no link is to be added.
+
+ The argument ``domain`` specifies the language domain the object is
+ in. ``info`` is a dictionary with the following keys guaranteed to
+ be present (dependent on the domain):
+
+ - ``py``: ``module`` (name of the module), ``fullname`` (name of the object)
+ - ``c``: ``names`` (list of names for the object)
+ - ``cpp``: ``names`` (list of names for the object)
+ - ``javascript``: ``object`` (name of the object), ``fullname``
+ (name of the item)
+
+ Example:
+
+ .. code-block:: python
+
+ def linkcode_resolve(domain, info):
+ if domain != 'py':
+ return None
+ if not info['module']:
+ return None
+ filename = info['module'].replace('.', '/')
+ return "https://somesite/sourcerepo/%s.py" % filename
diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst
new file mode 100644
index 0000000..df4fc6b
--- /dev/null
+++ b/doc/usage/extensions/math.rst
@@ -0,0 +1,320 @@
+.. highlight:: rest
+
+.. _math-support:
+
+Math support for HTML outputs in Sphinx
+=======================================
+
+.. module:: sphinx.ext.mathbase
+ :synopsis: Common math support for imgmath and mathjax / jsmath.
+
+.. versionadded:: 0.5
+.. versionchanged:: 1.8
+
+ Math support for non-HTML builders is integrated to sphinx-core.
+ So mathbase extension is no longer needed.
+
+Since mathematical notation isn't natively supported by HTML in any way, Sphinx
+gives a math support to HTML document with several extensions. These use the
+reStructuredText math :rst:dir:`directive <math>` and :rst:role:`role <math>`.
+
+:mod:`sphinx.ext.imgmath` -- Render math as images
+--------------------------------------------------
+
+.. module:: sphinx.ext.imgmath
+ :synopsis: Render math as PNG or SVG images.
+
+.. versionadded:: 1.4
+
+This extension renders math via LaTeX and dvipng_ or dvisvgm_ into PNG or SVG
+images. This of course means that the computer where the docs are built must
+have both programs available.
+
+There are various configuration values you can set to influence how the images
+are built:
+
+.. confval:: imgmath_image_format
+
+ The output image format. The default is ``'png'``. It should be either
+ ``'png'`` or ``'svg'``. The image is produced by first executing ``latex``
+ on the TeX mathematical mark-up then (depending on the requested format)
+ either `dvipng`_ or `dvisvgm`_.
+
+.. confval:: imgmath_use_preview
+
+ ``dvipng`` and ``dvisvgm`` both have the ability to collect from LaTeX the
+ "depth" of the rendered math: an inline image should use this "depth" in a
+ ``vertical-align`` style to get correctly aligned with surrounding text.
+
+ This mechanism requires the `LaTeX preview package`_ (available as
+ ``preview-latex-style`` on Ubuntu xenial). Therefore, the default for this
+ option is ``False`` but it is strongly recommended to set it to ``True``.
+
+ .. versionchanged:: 2.2
+
+ This option can be used with the ``'svg'`` :confval:`imgmath_image_format`.
+
+.. confval:: imgmath_add_tooltips
+
+ Default: ``True``. If false, do not add the LaTeX code as an "alt" attribute
+ for math images.
+
+.. confval:: imgmath_font_size
+
+ The font size (in ``pt``) of the displayed math. The default value is
+ ``12``. It must be a positive integer.
+
+.. confval:: imgmath_latex
+
+ The command name with which to invoke LaTeX. The default is ``'latex'``; you
+ may need to set this to a full path if ``latex`` is not in the executable
+ search path.
+
+ Since this setting is not portable from system to system, it is normally not
+ useful to set it in ``conf.py``; rather, giving it on the
+ :program:`sphinx-build` command line via the :option:`-D <sphinx-build -D>`
+ option should be preferable, like this::
+
+ sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html
+
+ This value should only contain the path to the latex executable, not further
+ arguments; use :confval:`imgmath_latex_args` for that purpose.
+
+ .. hint::
+
+ To use `OpenType Math fonts`__ with ``unicode-math``, via a custom
+ :confval:`imgmath_latex_preamble`, you can set :confval:`imgmath_latex`
+ to ``'dvilualatex'``, but must then set :confval:`imgmath_image_format`
+ to ``'svg'``. Note: this has only been tested with ``dvisvgm 3.0.3``.
+ It significantly increases image production duration compared to using
+ standard ``'latex'`` with traditional TeX math fonts.
+
+ __ https://tex.stackexchange.com/questions/425098/which-opentype-math-fonts-are-available
+
+
+ .. hint::
+
+ Some fancy LaTeX mark-up (an example was reported which used TikZ to add
+ various decorations to the equation) require multiple runs of the LaTeX
+ executable. To handle this, set this configuration setting to
+ ``'latexmk'`` (or a full path to it) as this Perl script reliably
+ chooses dynamically how many latex runs are needed.
+
+ .. versionchanged:: 6.2.0
+
+ Using ``'xelatex'`` (or a full path to it) is now supported. But you
+ must then add ``'-no-pdf'`` to the :confval:`imgmath_latex_args` list of
+ the command options. The ``'svg'`` :confval:`imgmath_image_format` is
+ required. Also, you may need the ``dvisvgm`` binary to be relatively
+ recent (testing was done only with its ``3.0.3`` release).
+
+ .. note::
+
+ Regarding the previous note, it is currently not supported to use
+ ``latexmk`` with option ``-xelatex``.
+
+.. confval:: imgmath_latex_args
+
+ Additional arguments to give to latex, as a list. The default is an empty
+ list.
+
+.. confval:: imgmath_latex_preamble
+
+ Additional LaTeX code to put into the preamble of the LaTeX files used to
+ translate the math snippets. This is left empty by default. Use it
+ e.g. to add packages which modify the fonts used for math, such as
+ ``'\\usepackage{newtxsf}'`` for sans-serif fonts, or
+ ``'\\usepackage{fouriernc}'`` for serif fonts. Indeed, the default LaTeX
+ math fonts have rather thin glyphs which (in HTML output) often do not
+ match well with the font for text.
+
+.. confval:: imgmath_dvipng
+
+ The command name to invoke ``dvipng``. The default is
+ ``'dvipng'``; you may need to set this to a full path if ``dvipng`` is not in
+ the executable search path. This option is only used when
+ ``imgmath_image_format`` is set to ``'png'``.
+
+.. confval:: imgmath_dvipng_args
+
+ Additional arguments to give to dvipng, as a list. The default value is
+ ``['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']`` which makes the
+ image a bit darker and larger then it is by default (this compensates
+ somewhat for the thinness of default LaTeX math fonts), and produces PNGs with a
+ transparent background. This option is used only when
+ ``imgmath_image_format`` is ``'png'``.
+
+.. confval:: imgmath_dvisvgm
+
+ The command name to invoke ``dvisvgm``. The default is
+ ``'dvisvgm'``; you may need to set this to a full path if ``dvisvgm`` is not
+ in the executable search path. This option is only used when
+ ``imgmath_image_format`` is ``'svg'``.
+
+.. confval:: imgmath_dvisvgm_args
+
+ Additional arguments to give to dvisvgm, as a list. The default value is
+ ``['--no-fonts']``, which means that ``dvisvgm`` will render glyphs as path
+ elements (cf the `dvisvgm FAQ`_). This option is used only when
+ ``imgmath_image_format`` is ``'svg'``.
+
+.. confval:: imgmath_embed
+
+ Default: ``False``. If true, encode LaTeX output images within HTML files
+ (base64 encoded) and do not save separate png/svg files to disk.
+
+ .. versionadded:: 5.2
+
+:mod:`sphinx.ext.mathjax` -- Render math via JavaScript
+-------------------------------------------------------
+
+.. module:: sphinx.ext.mathjax
+ :synopsis: Render math using JavaScript via MathJax.
+
+.. warning::
+ Version 4.0 changes the version of MathJax used to version 3. You may need to
+ override ``mathjax_path`` to
+ ``https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML``
+ or update your configuration options for version 3
+ (see :confval:`mathjax3_config`).
+
+.. versionadded:: 1.1
+
+This extension puts math as-is into the HTML files. The JavaScript package
+MathJax_ is then loaded and transforms the LaTeX markup to readable math live in
+the browser.
+
+Because MathJax (and the necessary fonts) is very large, it is not included in
+Sphinx but is set to automatically include it from a third-party site.
+
+.. attention::
+
+ You should use the math :rst:dir:`directive <math>` and
+ :rst:role:`role <math>`, not the native MathJax ``$$``, ``\(``, etc.
+
+
+.. confval:: mathjax_path
+
+ The path to the JavaScript file to include in the HTML files in order to load
+ MathJax.
+
+ The default is the ``https://`` URL that loads the JS files from the
+ `jsdelivr`__ Content Delivery Network. See the `MathJax Getting Started
+ page`__ for details. If you want MathJax to be available offline or
+ without including resources from a third-party site, you have to
+ download it and set this value to a different path.
+
+ __ https://www.jsdelivr.com/
+
+ __ https://www.mathjax.org/#gettingstarted
+
+ The path can be absolute or relative; if it is relative, it is relative to
+ the ``_static`` directory of the built docs.
+
+ For example, if you put MathJax into the static path of the Sphinx docs, this
+ value would be ``MathJax/MathJax.js``. If you host more than one Sphinx
+ documentation set on one server, it is advisable to install MathJax in a
+ shared location.
+
+ You can also give a full ``https://`` URL different from the CDN URL.
+
+.. confval:: mathjax_options
+
+ The options to script tag for mathjax. For example, you can set integrity
+ option with following setting::
+
+ mathjax_options = {
+ 'integrity': 'sha384-......',
+ }
+
+ The default is empty (``{}``).
+
+ .. versionadded:: 1.8
+
+ .. versionchanged:: 4.4.1
+
+ Allow to change the loading method (async or defer) of MathJax if "async"
+ or "defer" key is set.
+
+.. confval:: mathjax3_config
+
+ The configuration options for MathJax v3 (which is used by default).
+ The given dictionary is assigned to the JavaScript variable
+ ``window.MathJax``.
+ For more information, please read `Configuring MathJax`__.
+
+ __ https://docs.mathjax.org/en/latest/web/configuration.html#configuration
+
+ The default is empty (not configured).
+
+ .. versionadded:: 4.0
+
+.. confval:: mathjax2_config
+
+ The configuration options for MathJax v2 (which can be loaded via
+ :confval:`mathjax_path`).
+ The value is used as a parameter of ``MathJax.Hub.Config()``.
+ For more information, please read `Using in-line configuration options`__.
+
+ __ https://docs.mathjax.org/en/v2.7-latest/
+ configuration.html#using-in-line-configuration-options
+
+ For example::
+
+ mathjax2_config = {
+ 'extensions': ['tex2jax.js'],
+ 'jax': ['input/TeX', 'output/HTML-CSS'],
+ }
+
+ The default is empty (not configured).
+
+ .. versionadded:: 4.0
+
+ :confval:`mathjax_config` has been renamed to :confval:`mathjax2_config`.
+
+.. confval:: mathjax_config
+
+ Former name of :confval:`mathjax2_config`.
+
+ For help converting your old MathJax configuration to to the new
+ :confval:`mathjax3_config`, see `Converting Your v2 Configuration to v3`__.
+
+ __ https://docs.mathjax.org/en/latest/web/
+ configuration.html#converting-your-v2-configuration-to-v3
+
+ .. versionadded:: 1.8
+
+ .. versionchanged:: 4.0
+
+ This has been renamed to :confval:`mathjax2_config`.
+ :confval:`mathjax_config` is still supported for backwards compatibility.
+
+:mod:`sphinx.ext.jsmath` -- Render math via JavaScript
+------------------------------------------------------
+
+.. module:: sphinx.ext.jsmath
+ :synopsis: Render math using JavaScript via JSMath.
+
+This extension works just as the MathJax extension does, but uses the older
+package jsMath_. It provides this config value:
+
+.. confval:: jsmath_path
+
+ The path to the JavaScript file to include in the HTML files in order to load
+ JSMath. There is no default.
+
+ The path can be absolute or relative; if it is relative, it is relative to
+ the ``_static`` directory of the built docs.
+
+ For example, if you put JSMath into the static path of the Sphinx docs, this
+ value would be ``jsMath/easy/load.js``. If you host more than one
+ Sphinx documentation set on one server, it is advisable to install jsMath in
+ a shared location.
+
+
+.. _dvipng: https://savannah.nongnu.org/projects/dvipng/
+.. _dvisvgm: https://dvisvgm.de/
+.. _dvisvgm FAQ: https://dvisvgm.de/FAQ
+.. _MathJax: https://www.mathjax.org/
+.. _jsMath: http://www.math.union.edu/~dpvc/jsmath/
+.. _LaTeX preview package: https://www.gnu.org/software/auctex/preview-latex.html
diff --git a/doc/usage/extensions/napoleon.rst b/doc/usage/extensions/napoleon.rst
new file mode 100644
index 0000000..d2391da
--- /dev/null
+++ b/doc/usage/extensions/napoleon.rst
@@ -0,0 +1,574 @@
+:mod:`sphinx.ext.napoleon` -- Support for NumPy and Google style docstrings
+===========================================================================
+
+.. module:: sphinx.ext.napoleon
+ :synopsis: Support for NumPy and Google style docstrings
+
+.. moduleauthor:: Rob Ruana
+
+.. versionadded:: 1.3
+
+Overview
+--------
+
+.. highlight:: text
+
+Are you tired of writing docstrings that look like this::
+
+ :param path: The path of the file to wrap
+ :type path: str
+ :param field_storage: The :class:`FileStorage` instance to wrap
+ :type field_storage: FileStorage
+ :param temporary: Whether or not to delete the file when the File
+ instance is destructed
+ :type temporary: bool
+ :returns: A buffered writable file descriptor
+ :rtype: BufferedFileStorage
+
+`reStructuredText`_ is great, but it creates visually dense, hard to read
+:pep:`docstrings <287>`. Compare the jumble above to the same thing rewritten
+according to the `Google Python Style Guide`_::
+
+ Args:
+ path (str): The path of the file to wrap
+ field_storage (FileStorage): The :class:`FileStorage` instance to wrap
+ temporary (bool): Whether or not to delete the file when the File
+ instance is destructed
+
+ Returns:
+ BufferedFileStorage: A buffered writable file descriptor
+
+Much more legible, no?
+
+Napoleon is a :term:`extension` that enables Sphinx to parse both `NumPy`_ and
+`Google`_ style docstrings - the style recommended by `Khan Academy`_.
+
+Napoleon is a pre-processor that parses `NumPy`_ and `Google`_ style
+docstrings and converts them to reStructuredText before Sphinx attempts to
+parse them. This happens in an intermediate step while Sphinx is processing
+the documentation, so it doesn't modify any of the docstrings in your actual
+source code files.
+
+.. _ReStructuredText: https://docutils.sourceforge.io/rst.html
+.. _Google Python Style Guide:
+ https://google.github.io/styleguide/pyguide.html
+.. _Google:
+ https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings
+.. _NumPy:
+ https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
+.. _Khan Academy:
+ https://github.com/Khan/style-guides/blob/master/style/python.md#docstrings
+
+Getting Started
+~~~~~~~~~~~~~~~
+
+1. After :doc:`setting up Sphinx </usage/quickstart>` to build your docs,
+ enable napoleon in the Sphinx `conf.py` file::
+
+ # conf.py
+
+ # Add napoleon to the extensions list
+ extensions = ['sphinx.ext.napoleon']
+
+2. Use `sphinx-apidoc` to build your API documentation::
+
+ $ sphinx-apidoc -f -o docs/source projectdir
+
+
+Docstrings
+~~~~~~~~~~
+
+Napoleon interprets every docstring that :mod:`autodoc <sphinx.ext.autodoc>`
+can find, including docstrings on: ``modules``, ``classes``, ``attributes``,
+``methods``, ``functions``, and ``variables``. Inside each docstring,
+specially formatted `Sections`_ are parsed and converted to
+reStructuredText.
+
+All standard reStructuredText formatting still works as expected.
+
+
+.. _Sections:
+
+Docstring Sections
+~~~~~~~~~~~~~~~~~~
+
+All of the following section headers are supported:
+
+* ``Args`` *(alias of Parameters)*
+* ``Arguments`` *(alias of Parameters)*
+* ``Attention``
+* ``Attributes``
+* ``Caution``
+* ``Danger``
+* ``Error``
+* ``Example``
+* ``Examples``
+* ``Hint``
+* ``Important``
+* ``Keyword Args`` *(alias of Keyword Arguments)*
+* ``Keyword Arguments``
+* ``Methods``
+* ``Note``
+* ``Notes``
+* ``Other Parameters``
+* ``Parameters``
+* ``Return`` *(alias of Returns)*
+* ``Returns``
+* ``Raise`` *(alias of Raises)*
+* ``Raises``
+* ``References``
+* ``See Also``
+* ``Tip``
+* ``Todo``
+* ``Warning``
+* ``Warnings`` *(alias of Warning)*
+* ``Warn`` *(alias of Warns)*
+* ``Warns``
+* ``Yield`` *(alias of Yields)*
+* ``Yields``
+
+Google vs NumPy
+~~~~~~~~~~~~~~~
+
+Napoleon supports two styles of docstrings: `Google`_ and `NumPy`_. The
+main difference between the two styles is that Google uses indentation to
+separate sections, whereas NumPy uses underlines.
+
+Google style:
+
+.. code-block:: python
+
+ def func(arg1, arg2):
+ """Summary line.
+
+ Extended description of function.
+
+ Args:
+ arg1 (int): Description of arg1
+ arg2 (str): Description of arg2
+
+ Returns:
+ bool: Description of return value
+
+ """
+ return True
+
+NumPy style:
+
+.. code-block:: python
+
+ def func(arg1, arg2):
+ """Summary line.
+
+ Extended description of function.
+
+ Parameters
+ ----------
+ arg1 : int
+ Description of arg1
+ arg2 : str
+ Description of arg2
+
+ Returns
+ -------
+ bool
+ Description of return value
+
+ """
+ return True
+
+NumPy style tends to require more vertical space, whereas Google style
+tends to use more horizontal space. Google style tends to be easier to
+read for short and simple docstrings, whereas NumPy style tends be easier
+to read for long and in-depth docstrings.
+
+The choice between styles is largely aesthetic, but the two styles should
+not be mixed. Choose one style for your project and be consistent with it.
+
+.. seealso::
+
+ For complete examples:
+
+ * :ref:`example_google`
+ * :ref:`example_numpy`
+
+
+Type Annotations
+~~~~~~~~~~~~~~~~
+
+:pep:`484` introduced a standard way to express types in Python code.
+This is an alternative to expressing types directly in docstrings.
+One benefit of expressing types according to :pep:`484` is that
+type checkers and IDEs can take advantage of them for static code
+analysis. :pep:`484` was then extended by :pep:`526` which introduced
+a similar way to annotate variables (and attributes).
+
+Google style with Python 3 type annotations::
+
+ def func(arg1: int, arg2: str) -> bool:
+ """Summary line.
+
+ Extended description of function.
+
+ Args:
+ arg1: Description of arg1
+ arg2: Description of arg2
+
+ Returns:
+ Description of return value
+
+ """
+ return True
+
+ class Class:
+ """Summary line.
+
+ Extended description of class
+
+ Attributes:
+ attr1: Description of attr1
+ attr2: Description of attr2
+ """
+
+ attr1: int
+ attr2: str
+
+Google style with types in docstrings::
+
+ def func(arg1, arg2):
+ """Summary line.
+
+ Extended description of function.
+
+ Args:
+ arg1 (int): Description of arg1
+ arg2 (str): Description of arg2
+
+ Returns:
+ bool: Description of return value
+
+ """
+ return True
+
+ class Class:
+ """Summary line.
+
+ Extended description of class
+
+ Attributes:
+ attr1 (int): Description of attr1
+ attr2 (str): Description of attr2
+ """
+
+.. Note::
+ `Python 2/3 compatible annotations`_ aren't currently
+ supported by Sphinx and won't show up in the docs.
+
+.. _Python 2/3 compatible annotations: https://peps.python.org/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code
+
+
+Configuration
+-------------
+
+Listed below are all the settings used by napoleon and their default
+values. These settings can be changed in the Sphinx `conf.py` file. Make
+sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
+
+ # conf.py
+
+ # Add any Sphinx extension module names here, as strings
+ extensions = ['sphinx.ext.napoleon']
+
+ # Napoleon settings
+ napoleon_google_docstring = True
+ napoleon_numpy_docstring = True
+ napoleon_include_init_with_doc = False
+ napoleon_include_private_with_doc = False
+ napoleon_include_special_with_doc = True
+ napoleon_use_admonition_for_examples = False
+ napoleon_use_admonition_for_notes = False
+ napoleon_use_admonition_for_references = False
+ napoleon_use_ivar = False
+ napoleon_use_param = True
+ napoleon_use_rtype = True
+ napoleon_preprocess_types = False
+ napoleon_type_aliases = None
+ napoleon_attr_annotations = True
+
+.. _Google style:
+ https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings
+.. _NumPy style:
+ https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
+
+.. confval:: napoleon_google_docstring
+
+ True to parse `Google style`_ docstrings. False to disable support
+ for Google style docstrings. *Defaults to True.*
+
+.. confval:: napoleon_numpy_docstring
+
+ True to parse `NumPy style`_ docstrings. False to disable support
+ for NumPy style docstrings. *Defaults to True.*
+
+.. confval:: napoleon_include_init_with_doc
+
+ True to list ``__init___`` docstrings separately from the class
+ docstring. False to fall back to Sphinx's default behavior, which
+ considers the ``__init___`` docstring as part of the class
+ documentation. *Defaults to False.*
+
+ **If True**::
+
+ def __init__(self):
+ """
+ This will be included in the docs because it has a docstring
+ """
+
+ def __init__(self):
+ # This will NOT be included in the docs
+
+.. confval:: napoleon_include_private_with_doc
+
+ True to include private members (like ``_membername``) with docstrings
+ in the documentation. False to fall back to Sphinx's default behavior.
+ *Defaults to False.*
+
+ **If True**::
+
+ def _included(self):
+ """
+ This will be included in the docs because it has a docstring
+ """
+ pass
+
+ def _skipped(self):
+ # This will NOT be included in the docs
+ pass
+
+.. confval:: napoleon_include_special_with_doc
+
+ True to include special members (like ``__membername__``) with
+ docstrings in the documentation. False to fall back to Sphinx's
+ default behavior. *Defaults to True.*
+
+ **If True**::
+
+ def __str__(self):
+ """
+ This will be included in the docs because it has a docstring
+ """
+ return unicode(self).encode('utf-8')
+
+ def __unicode__(self):
+ # This will NOT be included in the docs
+ return unicode(self.__class__.__name__)
+
+.. confval:: napoleon_use_admonition_for_examples
+
+ True to use the ``.. admonition::`` directive for the **Example** and
+ **Examples** sections. False to use the ``.. rubric::`` directive
+ instead. One may look better than the other depending on what HTML
+ theme is used. *Defaults to False.*
+
+ This `NumPy style`_ snippet will be converted as follows::
+
+ Example
+ -------
+ This is just a quick example
+
+ **If True**::
+
+ .. admonition:: Example
+
+ This is just a quick example
+
+ **If False**::
+
+ .. rubric:: Example
+
+ This is just a quick example
+
+.. confval:: napoleon_use_admonition_for_notes
+
+ True to use the ``.. admonition::`` directive for **Notes** sections.
+ False to use the ``.. rubric::`` directive instead. *Defaults to False.*
+
+ .. note:: The singular **Note** section will always be converted to a
+ ``.. note::`` directive.
+
+ .. seealso::
+
+ :confval:`napoleon_use_admonition_for_examples`
+
+.. confval:: napoleon_use_admonition_for_references
+
+ True to use the ``.. admonition::`` directive for **References**
+ sections. False to use the ``.. rubric::`` directive instead.
+ *Defaults to False.*
+
+ .. seealso::
+
+ :confval:`napoleon_use_admonition_for_examples`
+
+.. confval:: napoleon_use_ivar
+
+ True to use the ``:ivar:`` role for instance variables. False to use
+ the ``.. attribute::`` directive instead. *Defaults to False.*
+
+ This `NumPy style`_ snippet will be converted as follows::
+
+ Attributes
+ ----------
+ attr1 : int
+ Description of `attr1`
+
+ **If True**::
+
+ :ivar attr1: Description of `attr1`
+ :vartype attr1: int
+
+ **If False**::
+
+ .. attribute:: attr1
+
+ Description of `attr1`
+
+ :type: int
+
+.. confval:: napoleon_use_param
+
+ True to use a ``:param:`` role for each function parameter. False to
+ use a single ``:parameters:`` role for all the parameters.
+ *Defaults to True.*
+
+ This `NumPy style`_ snippet will be converted as follows::
+
+ Parameters
+ ----------
+ arg1 : str
+ Description of `arg1`
+ arg2 : int, optional
+ Description of `arg2`, defaults to 0
+
+ **If True**::
+
+ :param arg1: Description of `arg1`
+ :type arg1: str
+ :param arg2: Description of `arg2`, defaults to 0
+ :type arg2: :class:`int`, *optional*
+
+ **If False**::
+
+ :parameters: * **arg1** (*str*) --
+ Description of `arg1`
+ * **arg2** (*int, optional*) --
+ Description of `arg2`, defaults to 0
+
+.. confval:: napoleon_use_keyword
+
+ True to use a ``:keyword:`` role for each function keyword argument.
+ False to use a single ``:keyword arguments:`` role for all the
+ keywords.
+ *Defaults to True.*
+
+ This behaves similarly to :confval:`napoleon_use_param`. Note unlike docutils,
+ ``:keyword:`` and ``:param:`` will not be treated the same way - there will
+ be a separate "Keyword Arguments" section, rendered in the same fashion as
+ "Parameters" section (type links created if possible)
+
+ .. seealso::
+
+ :confval:`napoleon_use_param`
+
+.. confval:: napoleon_use_rtype
+
+ True to use the ``:rtype:`` role for the return type. False to output
+ the return type inline with the description. *Defaults to True.*
+
+ This `NumPy style`_ snippet will be converted as follows::
+
+ Returns
+ -------
+ bool
+ True if successful, False otherwise
+
+ **If True**::
+
+ :returns: True if successful, False otherwise
+ :rtype: bool
+
+ **If False**::
+
+ :returns: *bool* -- True if successful, False otherwise
+
+.. confval:: napoleon_preprocess_types
+
+ True to convert the type definitions in the docstrings as references.
+ Defaults to *False*.
+
+ .. versionadded:: 3.2.1
+ .. versionchanged:: 3.5
+
+ Do preprocess the Google style docstrings also.
+
+.. confval:: napoleon_type_aliases
+
+ A mapping to translate type names to other names or references. Works
+ only when ``napoleon_use_param = True``. *Defaults to None.*
+
+ With::
+
+ napoleon_type_aliases = {
+ "CustomType": "mypackage.CustomType",
+ "dict-like": ":term:`dict-like <mapping>`",
+ }
+
+ This `NumPy style`_ snippet::
+
+ Parameters
+ ----------
+ arg1 : CustomType
+ Description of `arg1`
+ arg2 : dict-like
+ Description of `arg2`
+
+ becomes::
+
+ :param arg1: Description of `arg1`
+ :type arg1: mypackage.CustomType
+ :param arg2: Description of `arg2`
+ :type arg2: :term:`dict-like <mapping>`
+
+ .. versionadded:: 3.2
+
+.. confval:: napoleon_attr_annotations
+
+ True to allow using :pep:`526` attributes annotations in classes.
+ If an attribute is documented in the docstring without a type and
+ has an annotation in the class body, that type is used.
+
+ .. versionadded:: 3.4
+
+.. confval:: napoleon_custom_sections
+
+ Add a list of custom sections to include, expanding the list of parsed sections.
+ *Defaults to None.*
+
+ The entries can either be strings or tuples, depending on the intention:
+
+ * To create a custom "generic" section, just pass a string.
+ * To create an alias for an existing section, pass a tuple containing the
+ alias name and the original, in that order.
+ * To create a custom section that displays like the parameters or returns
+ section, pass a tuple containing the custom section name and a string
+ value, "params_style" or "returns_style".
+
+ If an entry is just a string, it is interpreted as a header for a generic
+ section. If the entry is a tuple/list/indexed container, the first entry
+ is the name of the section, the second is the section key to emulate. If the
+ second entry value is "params_style" or "returns_style", the custom section
+ will be displayed like the parameters section or returns section.
+
+ .. versionadded:: 1.8
+ .. versionchanged:: 3.5
+ Support ``params_style`` and ``returns_style``
diff --git a/doc/usage/extensions/todo.rst b/doc/usage/extensions/todo.rst
new file mode 100644
index 0000000..bf8b922
--- /dev/null
+++ b/doc/usage/extensions/todo.rst
@@ -0,0 +1,62 @@
+:mod:`sphinx.ext.todo` -- Support for todo items
+================================================
+
+.. module:: sphinx.ext.todo
+ :synopsis: Allow inserting todo items into documents.
+.. moduleauthor:: Daniel Bültmann
+
+.. versionadded:: 0.5
+
+There are two additional directives when using this extension:
+
+.. rst:directive:: todo
+
+ Use this directive like, for example, :rst:dir:`note`.
+
+ It will only show up in the output if :confval:`todo_include_todos` is
+ ``True``.
+
+ .. versionadded:: 1.3.2
+ This directive supports an ``class`` option that determines the class
+ attribute for HTML output. If not given, the class defaults to
+ ``admonition-todo``.
+
+
+.. rst:directive:: todolist
+
+ This directive is replaced by a list of all todo directives in the whole
+ documentation, if :confval:`todo_include_todos` is ``True``.
+
+
+These can be configured as seen below.
+
+Configuration
+-------------
+
+.. confval:: todo_include_todos
+
+ If this is ``True``, :rst:dir:`todo` and :rst:dir:`todolist` produce output,
+ else they produce nothing. The default is ``False``.
+
+.. confval:: todo_emit_warnings
+
+ If this is ``True``, :rst:dir:`todo` emits a warning for each TODO entries.
+ The default is ``False``.
+
+ .. versionadded:: 1.5
+
+.. confval:: todo_link_only
+
+ If this is ``True``, :rst:dir:`todolist` produce output without file path and
+ line, The default is ``False``.
+
+ .. versionadded:: 1.4
+
+autodoc provides the following an additional event:
+
+.. event:: todo-defined (app, node)
+
+ .. versionadded:: 1.5
+
+ Emitted when a todo is defined. *node* is the defined
+ ``sphinx.ext.todo.todo_node`` node.
diff --git a/doc/usage/extensions/viewcode.rst b/doc/usage/extensions/viewcode.rst
new file mode 100644
index 0000000..c90d2ba
--- /dev/null
+++ b/doc/usage/extensions/viewcode.rst
@@ -0,0 +1,106 @@
+:mod:`sphinx.ext.viewcode` -- Add links to highlighted source code
+==================================================================
+
+.. module:: sphinx.ext.viewcode
+ :synopsis: Add links to a highlighted version of the source code.
+.. moduleauthor:: Georg Brandl
+
+.. versionadded:: 1.0
+
+This extension looks at your Python object descriptions (``.. class::``, ``..
+function::`` etc.) and tries to find the source files where the objects are
+contained. When found, a separate HTML page will be output for each module with
+a highlighted version of the source code, and a link will be added to all object
+descriptions that leads to the source code of the described object. A link back
+from the source to the description will also be inserted.
+
+.. warning::
+
+ Basically, ``viewcode`` extension will import the modules being linked to.
+ If any modules have side effects on import, these will be executed when
+ ``sphinx-build`` is run.
+
+ If you document scripts (as opposed to library modules), make sure their
+ main routine is protected by a ``if __name__ == '__main__'`` condition.
+
+ In addition, if you don't want to import the modules by ``viewcode``,
+ you can tell the location of the location of source code to ``viewcode``
+ using the :event:`viewcode-find-source` event.
+
+ If :confval:`viewcode_follow_imported_members` is enabled,
+ you will also need to resolve imported attributes
+ using the :event:`viewcode-follow-imported` event.
+
+This extension works only on HTML related builders like ``html``,
+``applehelp``, ``devhelp``, ``htmlhelp``, ``qthelp`` and so on except
+``singlehtml``. By default ``epub`` builder doesn't
+support this extension (see :confval:`viewcode_enable_epub`).
+
+Configuration
+-------------
+
+.. confval:: viewcode_follow_imported_members
+
+ If this is ``True``, viewcode extension will emit
+ :event:`viewcode-follow-imported` event to resolve the name of the module
+ by other extensions. The default is ``True``.
+
+ .. versionadded:: 1.3
+
+ .. versionchanged:: 1.8
+ Renamed from ``viewcode_import`` to ``viewcode_follow_imported_members``.
+
+.. confval:: viewcode_enable_epub
+
+ If this is ``True``, viewcode extension is also enabled even if you use
+ epub builders. This extension generates pages outside toctree, but this
+ is not preferred as epub format.
+
+ Until 1.4.x, this extension is always enabled. If you want to generate
+ epub as same as 1.4.x, you should set ``True``, but epub format checker's
+ score becomes worse.
+
+ The default is ``False``.
+
+ .. versionadded:: 1.5
+
+ .. warning::
+
+ Not all epub readers support pages generated by viewcode extension.
+ These readers ignore links to pages are not under toctree.
+
+ Some reader's rendering result are corrupted and
+ `epubcheck <https://github.com/IDPF/epubcheck>`_'s score
+ becomes worse even if the reader supports.
+
+.. confval:: viewcode_line_numbers
+
+ Default: ``False``.
+
+ If set to ``True``, inline line numbers will be added to the highlighted code.
+
+ .. versionadded:: 7.2
+
+.. event:: viewcode-find-source (app, modname)
+
+ .. versionadded:: 1.8
+
+ Find the source code for a module.
+ An event handler for this event should return
+ a tuple of the source code itself and a dictionary of tags.
+ The dictionary maps the name of a class, function, attribute, etc
+ to a tuple of its type, the start line number, and the end line number.
+ The type should be one of "class", "def", or "other".
+
+ :param app: The Sphinx application object.
+ :param modname: The name of the module to find source code for.
+
+.. event:: viewcode-follow-imported (app, modname, attribute)
+
+ .. versionadded:: 1.8
+
+ Find the name of the original module for an attribute.
+
+ :param app: The Sphinx application object.
+ :param modname: The name of the module that the attribute belongs to.
+ :param attribute: The name of the member to follow.