Adding upstream version 5.3.0.upstream/5.3.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

23 files changed, 4391 insertions, 0 deletions

diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst
new file mode 100644
index 0000000..255a059
--- /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 ``noindex`` 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
+   :noindex:
+
+   :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
+      ``noindex`` 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
+      ``noindex`` 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
+      ``noindex`` 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..4e2fa13
--- /dev/null
+++ b/doc/usage/extensions/autosummary.rst
@@ -0,0 +1,358 @@
+.. 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:: 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='=')
+   :noindex:
+
+   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..5e6b04f
--- /dev/null
+++ b/doc/usage/extensions/coverage.rst
@@ -0,0 +1,61 @@
+: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.
+
+   .. 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
+
+.. _Python regular expressions: https://docs.python.org/library/re
diff --git a/doc/usage/extensions/doctest.rst b/doc/usage/extensions/doctest.rst
new file mode 100644
index 0000000..1b9c822
--- /dev/null
+++ b/doc/usage/extensions/doctest.rst
@@ -0,0 +1,375 @@
+.. 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.3::
+
+         .. doctest::
+            :pyversion: > 3.3
+
+     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_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..6f82a2e
--- /dev/null
+++ b/doc/usage/extensions/example_google.py
@@ -0,0 +1,310 @@
+"""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]
+
+    """
+    for i in range(n):
+        yield i
+
+
+class ExampleError(Exception):
+    """Exceptions are documented in the same way as classes.
+
+    The __init__ method may be documented in either the class level
+    docstring, or as a docstring on the __init__ method itself.
+
+    Either form is acceptable, but the two should not be mixed. Choose one
+    convention to document the __init__ method and be consistent with it.
+
+    Note:
+        Do not include the `self` parameter in the ``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..22595b4
--- /dev/null
+++ b/doc/usage/extensions/example_numpy.py
@@ -0,0 +1,351 @@
+"""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]
+
+    """
+    for i in range(n):
+        yield i
+
+
+class ExampleError(Exception):
+    """Exceptions are documented in the same way as classes.
+
+    The __init__ method may be documented in either the class level
+    docstring, or as a docstring on the __init__ method itself.
+
+    Either form is acceptable, but the two should not be mixed. Choose one
+    convention to document the __init__ method and be consistent with it.
+
+    Note
+    ----
+    Do not include the `self` parameter in the ``Parameters`` section.
+
+    Parameters
+    ----------
+    msg : str
+        Human readable string describing the exception.
+    code : :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..37d71c5
--- /dev/null
+++ b/doc/usage/extensions/index.rst
@@ -0,0 +1,78 @@
+==========
+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::
+
+   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`__ project contains a curated list 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://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..7889591
--- /dev/null
+++ b/doc/usage/extensions/inheritance.rst
@@ -0,0 +1,169 @@
+.. 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
+
+
+
+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..a70c7c5
--- /dev/null
+++ b/doc/usage/extensions/intersphinx.rst
@@ -0,0 +1,238 @@
+: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.
+
+   **Old format for this config value**
+
+   This is the format used before Sphinx 1.0.  It is still recognized.
+
+   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.
+
+   **New format for this config value**
+
+   .. 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)),
+      }
+
+.. 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..9ce3efe
--- /dev/null
+++ b/doc/usage/extensions/math.rst
@@ -0,0 +1,295 @@
+.. 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::
+
+      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.
+
+.. 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..2c178d8
--- /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::
+
+      :attr:`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::
+
+      :attr:`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  :attr:`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::
+
+      :attr:`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..d3c3c44
--- /dev/null
+++ b/doc/usage/extensions/viewcode.rst
@@ -0,0 +1,98 @@
+: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.
+
+.. 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.