Adding upstream version 7.2.6.upstream/7.2.6upstream

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

42 files changed, 14925 insertions, 0 deletions

diff --git a/doc/usage/advanced/intl.rst b/doc/usage/advanced/intl.rst
new file mode 100644
index 0000000..ae6e7dc
--- /dev/null
+++ b/doc/usage/advanced/intl.rst
@@ -0,0 +1,372 @@
+.. _intl:
+
+Internationalization
+====================
+
+.. versionadded:: 1.1
+
+Complementary to translations provided for Sphinx-generated messages such as
+navigation bars, Sphinx provides mechanisms facilitating the translation of
+*documents*.  See the :ref:`intl-options` for details on configuration.
+
+.. figure:: /_static/translation.*
+   :width: 100%
+
+   Workflow visualization of translations in Sphinx.  (The figure is created by
+   `plantuml <https://plantuml.com>`_.)
+
+.. contents::
+   :local:
+
+Sphinx internationalization details
+-----------------------------------
+
+**gettext** [1]_ is an established standard for internationalization and
+localization.  It naively maps messages in a program to a translated string.
+Sphinx uses these facilities to translate whole documents.
+
+Initially project maintainers have to collect all translatable strings (also
+referred to as *messages*) to make them known to translators.  Sphinx extracts
+these through invocation of ``sphinx-build -b gettext``.
+
+Every single element in the doctree will end up in a single message which
+results in lists being equally split into different chunks while large
+paragraphs will remain as coarsely-grained as they were in the original
+document.  This grants seamless document updates while still providing a little
+bit of context for translators in free-text passages.  It is the maintainer's
+task to split up paragraphs which are too large as there is no sane automated
+way to do that.
+
+After Sphinx successfully ran the
+:class:`~sphinx.builders.gettext.MessageCatalogBuilder` you will find a
+collection of ``.pot`` files in your output directory.  These are **catalog
+templates** and contain messages in your original language *only*.
+
+They can be delivered to translators which will transform them to ``.po`` files
+--- so called **message catalogs** --- containing a mapping from the original
+messages to foreign-language strings.
+
+*gettext* compiles them into a binary format known as **binary catalogs**
+through :program:`msgfmt` for efficiency reasons.  If you make these files
+discoverable with :confval:`locale_dirs` for your :confval:`language`, Sphinx
+will pick them up automatically.
+
+An example: you have a document ``usage.rst`` in your Sphinx project.  The
+*gettext* builder will put its messages into ``usage.pot``.  Imagine you have
+Spanish translations [2]_ stored in ``usage.po`` --- for your builds to
+be translated you need to follow these instructions:
+
+* Compile your message catalog to a locale directory, say ``locale``, so it
+  ends up in ``./locale/es/LC_MESSAGES/usage.mo`` in your source directory
+  (where ``es`` is the language code for Spanish.) ::
+
+        msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
+
+* Set :confval:`locale_dirs` to ``["locale/"]``.
+* Set :confval:`language` to ``es`` (also possible via
+  :option:`-D <sphinx-build -D>`).
+* Run your desired build.
+
+
+In order to protect against mistakes, a warning is emitted if
+cross-references in the translated paragraph do not match those from the
+original.  This can be turned off globally using the
+:confval:`suppress_warnings` configuration variable.  Alternatively, to
+turn it off for one message only, end the message with ``#noqa`` like
+this::
+
+   Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
+   risus tortor, luctus id ultrices at. #noqa
+
+(Write ``\#noqa`` in case you want to have "#noqa" literally in the
+text.  This does not apply to code blocks, where ``#noqa`` is ignored
+because code blocks do not contain references anyway.)
+
+.. versionadded:: 4.5
+   The ``#noqa`` mechanism.
+
+
+Translating with sphinx-intl
+----------------------------
+
+Quick guide
+~~~~~~~~~~~
+
+`sphinx-intl`_ is a useful tool to work with Sphinx translation flow.  This
+section describe an easy way to translate with *sphinx-intl*.
+
+#. Install `sphinx-intl`_.
+
+   .. code-block:: console
+
+      $ pip install sphinx-intl
+
+#. Add configurations to ``conf.py``.
+
+   ::
+
+      locale_dirs = ['locale/']   # path is example but recommended.
+      gettext_compact = False     # optional.
+
+   This case-study assumes that BUILDDIR is set to ``_build``,
+   :confval:`locale_dirs` is set to ``locale/`` and :confval:`gettext_compact`
+   is set to ``False`` (the Sphinx document is already configured as such).
+
+#. Extract translatable messages into pot files.
+
+   .. code-block:: console
+
+      $ make gettext
+
+   The generated pot files will be placed in the ``_build/gettext`` directory.
+
+#. Generate po files.
+
+   We'll use the pot files generated in the above step.
+
+   .. code-block:: console
+
+      $ sphinx-intl update -p _build/gettext -l de -l ja
+
+   Once completed, the generated po files will be placed in the below
+   directories:
+
+   * ``./locale/de/LC_MESSAGES/``
+   * ``./locale/ja/LC_MESSAGES/``
+
+#. Translate po files.
+
+   As noted above, these are located in the ``./locale/<lang>/LC_MESSAGES``
+   directory.  An example of one such file, from Sphinx, ``builders.po``, is
+   given below.
+
+   .. code-block:: po
+
+      # a5600c3d2e3d48fc8c261ea0284db79b
+      #: ../../builders.rst:4
+      msgid "Available builders"
+      msgstr "<FILL HERE BY TARGET LANGUAGE>"
+
+   Another case, msgid is multi-line text and contains reStructuredText syntax:
+
+   .. code-block:: po
+
+      # 302558364e1d41c69b3277277e34b184
+      #: ../../builders.rst:9
+      msgid ""
+      "These are the built-in Sphinx builders. More builders can be added by "
+      ":ref:`extensions <extensions>`."
+      msgstr ""
+      "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
+      "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
+
+   Please be careful not to break reST notation.  Most po-editors will help you
+   with that.
+
+#. Build translated document.
+
+   You need a :confval:`language` parameter in ``conf.py`` or you may also
+   specify the parameter on the command line.
+
+   For BSD/GNU make, run:
+
+   .. code-block:: console
+
+      $ make -e SPHINXOPTS="-D language='de'" html
+
+   For Windows :command:`cmd.exe`, run:
+
+   .. code-block:: console
+
+      > set SPHINXOPTS=-D language=de
+      > .\make.bat html
+
+   For PowerShell, run:
+
+   .. code-block:: console
+
+      > Set-Item env:SPHINXOPTS "-D language=de"
+      > .\make.bat html
+
+Congratulations! You got the translated documentation in the ``_build/html``
+directory.
+
+.. versionadded:: 1.3
+
+   :program:`sphinx-build` that is invoked by make command will build po files
+   into mo files.
+
+   If you are using 1.2.x or earlier, please invoke :command:`sphinx-intl build`
+   command before :command:`make` command.
+
+Translating
+~~~~~~~~~~~
+
+Update your po files by new pot files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If a document is updated, it is necessary to generate updated pot files and to
+apply differences to translated po files.  In order to apply the updates from a
+pot file to the po file, use the :command:`sphinx-intl update` command.
+
+.. code-block:: console
+
+   $ sphinx-intl update -p _build/gettext
+
+
+Using Transifex service for team translation
+--------------------------------------------
+
+Transifex_ is one of several services that allow collaborative translation via a
+web interface.  It has a nifty Python-based command line client that makes it
+easy to fetch and push translations.
+
+.. TODO: why use transifex?
+
+
+#. Install `transifex-client`_.
+
+   You need :command:`tx` command to upload resources (pot files).
+
+   .. code-block:: console
+
+      $ pip install transifex-client
+
+   .. seealso:: `Transifex Client documentation`_
+
+#. Create your Transifex_ account and create new project for your document.
+
+   Currently, Transifex does not allow for a translation project to have more
+   than one version of the document, so you'd better include a version number in
+   your project name.
+
+   For example:
+
+   :Project ID: ``sphinx-document-test_1_0``
+   :Project URL: ``https://www.transifex.com/projects/p/sphinx-document-test_1_0/``
+
+#. Create config files for :command:`tx` command.
+
+   This process will create ``.tx/config`` in the current directory, as well as
+   a ``~/.transifexrc`` file that includes auth information.
+
+   .. code-block:: console
+
+      $ tx init
+      Creating .tx folder...
+      Transifex instance [https://www.transifex.com]:
+      ...
+      Please enter your transifex username: <transifex-username>
+      Password: <transifex-password>
+      ...
+      Done.
+
+#. Upload pot files to Transifex service.
+
+   Register pot files to ``.tx/config`` file:
+
+   .. code-block:: console
+
+      $ cd /your/document/root
+      $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
+        --transifex-project-name sphinx-document-test_1_0
+
+   and upload pot files:
+
+   .. code-block:: console
+
+      $ tx push -s
+      Pushing translations for resource sphinx-document-test_1_0.builders:
+      Pushing source file (locale/pot/builders.pot)
+      Resource does not exist.  Creating...
+      ...
+      Done.
+
+#. Forward the translation on Transifex.
+
+   .. TODO: write this section
+
+#. Pull translated po files and make translated HTML.
+
+   Get translated catalogs and build mo files. For example, to build mo files
+   for German (de):
+
+   .. code-block:: console
+
+      $ cd /your/document/root
+      $ tx pull -l de
+      Pulling translations for resource sphinx-document-test_1_0.builders (...)
+       -> de: locale/de/LC_MESSAGES/builders.po
+      ...
+      Done.
+
+   Invoke :command:`make html` (for BSD/GNU make):
+
+   .. code-block:: console
+
+      $ make -e SPHINXOPTS="-D language='de'" html
+
+That's all!
+
+.. tip:: Translating locally and on Transifex
+
+   If you want to push all language's po files, you can be done by using
+   :command:`tx push -t` command.  Watch out! This operation overwrites
+   translations in Transifex.
+
+   In other words, if you have updated each in the service and local po files,
+   it would take much time and effort to integrate them.
+
+
+Using Weblate service for team translation
+------------------------------------------
+
+Read more in `Weblate's documentation`_.
+
+
+Contributing to Sphinx reference translation
+--------------------------------------------
+
+The recommended way for new contributors to translate Sphinx reference is to
+join the translation team on Transifex.
+
+There is a `sphinx translation page`_ for Sphinx (master) documentation.
+
+1. Login to Transifex_ service.
+2. Go to `sphinx translation page`_.
+3. Click ``Request language`` and fill form.
+4. Wait acceptance by Transifex sphinx translation maintainers.
+5. (After acceptance) Translate on Transifex.
+
+Detail is here: https://docs.transifex.com/getting-started-1/translators
+
+
+Translation progress and statistics
+-----------------------------------
+
+.. versionadded:: 7.1.0
+
+During the rendering process,
+Sphinx marks each translatable node with a ``translated`` attribute,
+indicating if a translation was found for the text in that node.
+
+The :confval:`translation_progress_classes` configuration value
+can be used to add a class to each element,
+depending on the value of the ``translated`` attribute.
+
+The ``|translation progress|`` substitution can be used to display the
+percentage of nodes that have been translated on a per-document basis.
+
+.. rubric:: Footnotes
+
+.. [1] See the `GNU gettext utilities
+       <https://www.gnu.org/software/gettext/manual/gettext.html#Introduction>`_
+       for details on that software suite.
+.. [2] Because nobody expects the Spanish Inquisition!
+
+.. _`transifex-client`: https://pypi.org/project/transifex-client/
+.. _`sphinx-intl`: https://pypi.org/project/sphinx-intl/
+.. _Transifex: https://www.transifex.com/
+.. _Weblate's documentation: https://docs.weblate.org/en/latest/devel/sphinx.html
+.. _`sphinx translation page`: https://www.transifex.com/sphinx-doc/sphinx-doc/
+.. _`Transifex Client documentation`: https://docs.transifex.com/client/introduction/
diff --git a/doc/usage/advanced/websupport/api.rst b/doc/usage/advanced/websupport/api.rst
new file mode 100644
index 0000000..79b51ee
--- /dev/null
+++ b/doc/usage/advanced/websupport/api.rst
@@ -0,0 +1,80 @@
+.. _websupportapi:
+
+.. currentmodule:: sphinxcontrib.websupport
+
+The WebSupport Class
+====================
+
+.. class:: WebSupport
+
+   The main API class for the web support package.  All interactions with the
+   web support package should occur through this class.
+
+   The class takes the following keyword arguments:
+
+   srcdir
+      The directory containing reStructuredText source files.
+
+   builddir
+      The directory that build data and static files should be placed in.  This
+      should be used when creating a :class:`WebSupport` object that will be
+      used to build data.
+
+   datadir
+      The directory that the web support data is in.  This should be used when
+      creating a :class:`WebSupport` object that will be used to retrieve data.
+
+   search
+       This may contain either a string (e.g. 'xapian') referencing a built-in
+       search adapter to use, or an instance of a subclass of
+       :class:`~.search.BaseSearch`.
+
+   storage
+       This may contain either a string representing a database uri, or an
+       instance of a subclass of :class:`~.storage.StorageBackend`.  If this is
+       not provided, a new sqlite database will be created.
+
+   moderation_callback
+       A callable to be called when a new comment is added that is not
+       displayed.  It must accept one argument: a dictionary representing the
+       comment that was added.
+
+   staticdir
+       If the static files should be created in a different location
+       **and not in** ``'/static'``, this should be a string with the name of
+       that location (e.g. ``builddir + '/static_files'``).
+
+       .. note::
+           If you specify ``staticdir``, you will typically want to adjust
+           ``staticroot`` accordingly.
+
+   staticroot
+       If the static files are not served from ``'/static'``, this should be a
+       string with the name of that location (e.g. ``'/static_files'``).
+
+   docroot
+       If the documentation is not served from the base path of a URL, this
+       should be a string specifying that path (e.g. ``'docs'``).
+
+
+.. versionchanged:: 1.6
+
+   WebSupport class is moved to sphinxcontrib.websupport from sphinx.websupport.
+   Please add ``sphinxcontrib-websupport`` package in your dependency and use
+   moved class instead.
+
+
+Methods
+-------
+
+.. automethod:: sphinxcontrib.websupport.WebSupport.build
+
+.. automethod:: sphinxcontrib.websupport.WebSupport.get_document
+
+.. automethod:: sphinxcontrib.websupport.WebSupport.get_data
+
+.. automethod:: sphinxcontrib.websupport.WebSupport.add_comment
+
+.. automethod:: sphinxcontrib.websupport.WebSupport.process_vote
+
+.. automethod:: sphinxcontrib.websupport.WebSupport.get_search_results
diff --git a/doc/usage/advanced/websupport/index.rst b/doc/usage/advanced/websupport/index.rst
new file mode 100644
index 0000000..0816640
--- /dev/null
+++ b/doc/usage/advanced/websupport/index.rst
@@ -0,0 +1,16 @@
+.. _websupport:
+
+Sphinx Web Support
+==================
+
+.. versionadded:: 1.1
+
+Sphinx provides a Python API to easily integrate Sphinx documentation into your
+web application.  To learn more read the :ref:`websupportquickstart`.
+
+.. toctree::
+
+   quickstart
+   api
+   searchadapters
+   storagebackends
diff --git a/doc/usage/advanced/websupport/quickstart.rst b/doc/usage/advanced/websupport/quickstart.rst
new file mode 100644
index 0000000..1cdd23f
--- /dev/null
+++ b/doc/usage/advanced/websupport/quickstart.rst
@@ -0,0 +1,255 @@
+.. _websupportquickstart:
+
+Web Support Quick Start
+=======================
+
+Building Documentation Data
+----------------------------
+
+To make use of the web support package in your application you'll need to build
+the data it uses.  This data includes pickle files representing documents,
+search indices, and node data that is used to track where comments and other
+things are in a document.  To do this you will need to create an instance of the
+:class:`~.WebSupport` class and call its :meth:`~.WebSupport.build` method::
+
+   from sphinxcontrib.websupport import WebSupport
+
+   support = WebSupport(srcdir='/path/to/rst/sources/',
+                        builddir='/path/to/build/outdir',
+                        search='xapian')
+
+   support.build()
+
+This will read reStructuredText sources from ``srcdir`` and place the necessary
+data in ``builddir``.  The ``builddir`` will contain two sub-directories: one
+named "data" that contains all the data needed to display documents, search
+through documents, and add comments to documents.  The other directory will be
+called "static" and contains static files that should be served from "/static".
+
+.. note::
+
+   If you wish to serve static files from a path other than "/static", you can
+   do so by providing the *staticdir* keyword argument when creating the
+   :class:`~.WebSupport` object.
+
+
+Integrating Sphinx Documents Into Your Webapp
+----------------------------------------------
+
+Now that the data is built, it's time to do something useful with it.  Start off
+by creating a :class:`~.WebSupport` object for your application::
+
+   from sphinxcontrib.websupport import WebSupport
+
+   support = WebSupport(datadir='/path/to/the/data',
+                        search='xapian')
+
+You'll only need one of these for each set of documentation you will be working
+with.  You can then call its :meth:`~.WebSupport.get_document` method to access
+individual documents::
+
+   contents = support.get_document('contents')
+
+This will return a dictionary containing the following items:
+
+* **body**: The main body of the document as HTML
+* **sidebar**: The sidebar of the document as HTML
+* **relbar**: A div containing links to related documents
+* **title**: The title of the document
+* **css**: Links to CSS files used by Sphinx
+* **script**: JavaScript containing comment options
+
+This dict can then be used as context for templates.  The goal is to be easy to
+integrate with your existing templating system.  An example using `Jinja2
+<https://jinja.palletsprojects.com/>`_ is:
+
+.. code-block:: html+jinja
+
+   {%- extends "layout.html" %}
+
+   {%- block title %}
+       {{ document.title }}
+   {%- endblock %}
+
+   {% block css %}
+       {{ super() }}
+       {{ document.css|safe }}
+       <link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
+   {% endblock %}
+
+   {%- block script %}
+       {{ super() }}
+       {{ document.script|safe }}
+   {%- endblock %}
+
+   {%- block relbar %}
+       {{ document.relbar|safe }}
+   {%- endblock %}
+
+   {%- block body %}
+       {{ document.body|safe }}
+   {%- endblock %}
+
+   {%- block sidebar %}
+       {{ document.sidebar|safe }}
+   {%- endblock %}
+
+
+Authentication
+~~~~~~~~~~~~~~
+
+To use certain features such as voting, it must be possible to authenticate
+users.  The details of the authentication are left to your application.  Once a
+user has been authenticated you can pass the user's details to certain
+:class:`~.WebSupport` methods using the *username* and *moderator* keyword
+arguments.  The web support package will store the username with comments and
+votes.  The only caveat is that if you allow users to change their username you
+must update the websupport package's data::
+
+   support.update_username(old_username, new_username)
+
+*username* should be a unique string which identifies a user, and *moderator*
+should be a boolean representing whether the user has moderation privileges.
+The default value for *moderator* is ``False``.
+
+An example `Flask <https://flask.palletsprojects.com/>`_ function that checks
+whether a user is logged in and then retrieves a document is::
+
+   from sphinxcontrib.websupport.errors import *
+
+   @app.route('/<path:docname>')
+   def doc(docname):
+       username = g.user.name if g.user else ''
+       moderator = g.user.moderator if g.user else False
+       try:
+           document = support.get_document(docname, username, moderator)
+       except DocumentNotFoundError:
+           abort(404)
+       return render_template('doc.html', document=document)
+
+The first thing to notice is that the *docname* is just the request path.  This
+makes accessing the correct document easy from a single view.  If the user is
+authenticated, then the username and moderation status are passed along with the
+docname to :meth:`~.WebSupport.get_document`.  The web support package will then
+add this data to the ``COMMENT_OPTIONS`` that are used in the template.
+
+.. note::
+
+   This only works if your documentation is served from your
+   document root. If it is served from another directory, you will
+   need to prefix the url route with that directory, and give the `docroot`
+   keyword argument when creating the web support object::
+
+      support = WebSupport(..., docroot='docs')
+
+      @app.route('/docs/<path:docname>')
+
+
+Performing Searches
+-------------------
+
+To use the search form built-in to the Sphinx sidebar, create a function to
+handle requests to the URL 'search' relative to the documentation root.  The
+user's search query will be in the GET parameters, with the key `q`.  Then use
+the :meth:`~sphinxcontrib.websupport.WebSupport.get_search_results` method to
+retrieve search results. In `Flask <https://flask.palletsprojects.com/>`_ that
+would be like this::
+
+   @app.route('/search')
+   def search():
+       q = request.args.get('q')
+       document = support.get_search_results(q)
+       return render_template('doc.html', document=document)
+
+Note that we used the same template to render our search results as we did to
+render our documents.  That's because :meth:`~.WebSupport.get_search_results`
+returns a context dict in the same format that :meth:`~.WebSupport.get_document`
+does.
+
+
+Comments & Proposals
+--------------------
+
+Now that this is done it's time to define the functions that handle the AJAX
+calls from the script.  You will need three functions.  The first function is
+used to add a new comment, and will call the web support method
+:meth:`~.WebSupport.add_comment`::
+
+   @app.route('/docs/add_comment', methods=['POST'])
+   def add_comment():
+       parent_id = request.form.get('parent', '')
+       node_id = request.form.get('node', '')
+       text = request.form.get('text', '')
+       proposal = request.form.get('proposal', '')
+       username = g.user.name if g.user is not None else 'Anonymous'
+       comment = support.add_comment(text, node_id='node_id',
+                                     parent_id='parent_id',
+                                     username=username, proposal=proposal)
+       return jsonify(comment=comment)
+
+You'll notice that both a ``parent_id`` and ``node_id`` are sent with the
+request. If the comment is being attached directly to a node, ``parent_id``
+will be empty. If the comment is a child of another comment, then ``node_id``
+will be empty. Then next function handles the retrieval of comments for a
+specific node, and is aptly named
+:meth:`~sphinxcontrib.websupport.WebSupport.get_data`::
+
+    @app.route('/docs/get_comments')
+    def get_comments():
+        username = g.user.name if g.user else None
+        moderator = g.user.moderator if g.user else False
+        node_id = request.args.get('node', '')
+        data = support.get_data(node_id, username, moderator)
+        return jsonify(**data)
+
+The final function that is needed will call :meth:`~.WebSupport.process_vote`,
+and will handle user votes on comments::
+
+   @app.route('/docs/process_vote', methods=['POST'])
+   def process_vote():
+       if g.user is None:
+           abort(401)
+       comment_id = request.form.get('comment_id')
+       value = request.form.get('value')
+       if value is None or comment_id is None:
+           abort(400)
+       support.process_vote(comment_id, g.user.id, value)
+       return "success"
+
+
+Comment Moderation
+------------------
+
+By default, all comments added through :meth:`~.WebSupport.add_comment` are
+automatically displayed.  If you wish to have some form of moderation, you can
+pass the ``displayed`` keyword argument::
+
+   comment = support.add_comment(text, node_id='node_id',
+                                 parent_id='parent_id',
+                                 username=username, proposal=proposal,
+                                 displayed=False)
+
+You can then create a new view to handle the moderation of comments.  It
+will be called when a moderator decides a comment should be accepted and
+displayed::
+
+   @app.route('/docs/accept_comment', methods=['POST'])
+   def accept_comment():
+       moderator = g.user.moderator if g.user else False
+       comment_id = request.form.get('id')
+       support.accept_comment(comment_id, moderator=moderator)
+       return 'OK'
+
+Rejecting comments happens via comment deletion.
+
+To perform a custom action (such as emailing a moderator) when a new comment is
+added but not displayed, you can pass callable to the :class:`~.WebSupport`
+class when instantiating your support object::
+
+   def moderation_callback(comment):
+       """Do something..."""
+
+   support = WebSupport(..., moderation_callback=moderation_callback)
+
+The moderation callback must take one argument, which will be the same comment
+dict that is returned by :meth:`.WebSupport.add_comment`.
diff --git a/doc/usage/advanced/websupport/searchadapters.rst b/doc/usage/advanced/websupport/searchadapters.rst
new file mode 100644
index 0000000..262d666
--- /dev/null
+++ b/doc/usage/advanced/websupport/searchadapters.rst
@@ -0,0 +1,49 @@
+.. _searchadapters:
+
+.. currentmodule:: sphinxcontrib.websupport.search
+
+Search Adapters
+===============
+
+To create a custom search adapter you will need to subclass the
+:class:`BaseSearch` class.  Then create an instance of the new class and pass
+that as the `search` keyword argument when you create the :class:`~.WebSupport`
+object::
+
+   support = WebSupport(srcdir=srcdir,
+                        builddir=builddir,
+                        search=MySearch())
+
+For more information about creating a custom search adapter, please see the
+documentation of the :class:`BaseSearch` class below.
+
+.. class:: BaseSearch
+
+   Defines an interface for search adapters.
+
+.. versionchanged:: 1.6
+
+   BaseSearch class is moved to sphinxcontrib.websupport.search from
+   sphinx.websupport.search.
+
+Methods
+-------
+
+The following methods are defined in the BaseSearch class. Some methods do not
+need to be overridden, but some (:meth:`~BaseSearch.add_document` and
+:meth:`~BaseSearch.handle_query`) must be overridden in your subclass. For a
+working example, look at the built-in adapter for whoosh.
+
+.. automethod:: BaseSearch.init_indexing
+
+.. automethod:: BaseSearch.finish_indexing
+
+.. automethod:: BaseSearch.feed
+
+.. automethod:: BaseSearch.add_document
+
+.. automethod:: BaseSearch.query
+
+.. automethod:: BaseSearch.handle_query
+
+.. automethod:: BaseSearch.extract_context
diff --git a/doc/usage/advanced/websupport/storagebackends.rst b/doc/usage/advanced/websupport/storagebackends.rst
new file mode 100644
index 0000000..ccb00b6
--- /dev/null
+++ b/doc/usage/advanced/websupport/storagebackends.rst
@@ -0,0 +1,49 @@
+.. _storagebackends:
+
+.. currentmodule:: sphinxcontrib.websupport.storage
+
+Storage Backends
+================
+
+To create a custom storage backend you will need to subclass the
+:class:`StorageBackend` class.  Then create an instance of the new class and
+pass that as the `storage` keyword argument when you create the
+:class:`~.WebSupport` object::
+
+   support = WebSupport(srcdir=srcdir,
+                        builddir=builddir,
+                        storage=MyStorage())
+
+For more information about creating a custom storage backend, please see the
+documentation of the :class:`StorageBackend` class below.
+
+.. class:: StorageBackend
+
+   Defines an interface for storage backends.
+
+.. versionchanged:: 1.6
+
+   StorageBackend class is moved to sphinxcontrib.websupport.storage from
+   sphinx.websupport.storage.
+
+
+Methods
+-------
+
+.. automethod:: StorageBackend.pre_build
+
+.. automethod:: StorageBackend.add_node
+
+.. automethod:: StorageBackend.post_build
+
+.. automethod:: StorageBackend.add_comment
+
+.. automethod:: StorageBackend.delete_comment
+
+.. automethod:: StorageBackend.get_data
+
+.. automethod:: StorageBackend.process_vote
+
+.. automethod:: StorageBackend.update_username
+
+.. automethod:: StorageBackend.accept_comment
diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst
new file mode 100644
index 0000000..ce2c5dc
--- /dev/null
+++ b/doc/usage/builders/index.rst
@@ -0,0 +1,565 @@
+.. _builders:
+
+========
+Builders
+========
+
+.. module:: sphinx.builders
+   :synopsis: Available built-in builder classes.
+
+These are the built-in Sphinx builders.  More builders can be added by
+:doc:`extensions </usage/extensions/index>`.
+
+The builder's "name" must be given to the **-b** command-line option of
+:program:`sphinx-build` to select a builder.
+
+
+.. module:: sphinx.builders.html
+.. class:: StandaloneHTMLBuilder
+
+   This is the standard HTML builder.  Its output is a directory with HTML
+   files, complete with style sheets and optionally the reST sources.  There are
+   quite a few configuration values that customize the output of this builder,
+   see the chapter :ref:`html-options` for details.
+
+   .. autoattribute:: name
+
+   .. autoattribute:: format
+
+   .. autoattribute:: supported_image_types
+
+.. module:: sphinx.builders.dirhtml
+.. class:: DirectoryHTMLBuilder
+
+   This is a subclass of the standard HTML builder.  Its output is a directory
+   with HTML files, where each file is called ``index.html`` and placed in a
+   subdirectory named like its page name.  For example, the document
+   ``markup/rest.rst`` will not result in an output file ``markup/rest.html``,
+   but ``markup/rest/index.html``.  When generating links between pages, the
+   ``index.html`` is omitted, so that the URL would look like ``markup/rest/``.
+
+   .. autoattribute:: name
+
+   .. autoattribute:: format
+
+   .. autoattribute:: supported_image_types
+
+   .. versionadded:: 0.6
+
+.. module:: sphinx.builders.singlehtml
+.. class:: SingleFileHTMLBuilder
+
+   This is an HTML builder that combines the whole project in one output file.
+   (Obviously this only works with smaller projects.)  The file is named like
+   the root document.  No indices will be generated.
+
+   .. autoattribute:: name
+
+   .. autoattribute:: format
+
+   .. autoattribute:: supported_image_types
+
+   .. versionadded:: 1.0
+
+.. module:: sphinxcontrib.htmlhelp
+.. class:: HTMLHelpBuilder
+
+   This builder produces the same output as the standalone HTML builder, but
+   also generates HTML Help support files that allow the Microsoft HTML Help
+   Workshop to compile them into a CHM file.
+
+   .. autoattribute:: name
+
+   .. autoattribute:: format
+
+   .. autoattribute:: supported_image_types
+
+.. module:: sphinxcontrib.qthelp
+.. class:: QtHelpBuilder
+
+   This builder produces the same output as the standalone HTML builder, but
+   also generates `Qt help`_ collection support files that allow the Qt
+   collection generator to compile them.
+
+   .. versionchanged:: 2.0
+
+      Moved to sphinxcontrib.qthelp from sphinx.builders package.
+
+   .. autoattribute:: name
+
+   .. autoattribute:: format
+
+   .. autoattribute:: supported_image_types
+
+   .. _Qt help: https://doc.qt.io/qt-4.8/qthelp-framework.html
+
+.. module:: sphinxcontrib.applehelp
+.. class:: AppleHelpBuilder
+
+   This builder produces an Apple Help Book based on the same output as the
+   standalone HTML builder.
+
+   If the source directory contains any ``.lproj`` folders, the one
+   corresponding to the selected language will have its contents merged with
+   the generated output.  These folders will be ignored by all other
+   documentation types.
+
+   In order to generate a valid help book, this builder requires the command
+   line tool :program:`hiutil`, which is only available on Mac OS X 10.6 and
+   above.  You can disable the indexing step by setting
+   :confval:`applehelp_disable_external_tools` to ``True``, in which case the
+   output will not be valid until :program:`hiutil` has been run on all of the
+   ``.lproj`` folders within the bundle.
+
+   .. autoattribute:: name
+
+   .. autoattribute:: format
+
+   .. autoattribute:: supported_image_types
+
+   .. versionadded:: 1.3
+
+   .. versionchanged:: 2.0
+
+      Moved to sphinxcontrib.applehelp from sphinx.builders package.
+
+.. module:: sphinxcontrib.devhelp
+.. class:: DevhelpBuilder
+
+   This builder produces the same output as the standalone HTML builder, but
+   also generates `GNOME Devhelp <https://wiki.gnome.org/Apps/Devhelp>`__
+   support file that allows the GNOME Devhelp reader to view them.
+
+   .. autoattribute:: name
+
+   .. autoattribute:: format
+
+   .. autoattribute:: supported_image_types
+
+   .. versionchanged:: 2.0
+
+      Moved to sphinxcontrib.devhelp from sphinx.builders package.
+
+.. module:: sphinx.builders.epub3
+.. class:: Epub3Builder
+
+   This builder produces the same output as the standalone HTML builder, but
+   also generates an *epub* file for ebook readers.  See :ref:`epub-faq` for
+   details about it.  For definition of the epub format, have a look at
+   `<http://idpf.org/epub>`_ or `<https://en.wikipedia.org/wiki/EPUB>`_.
+   The builder creates *EPUB 3* files.
+
+   .. autoattribute:: name
+
+   .. autoattribute:: format
+
+   .. autoattribute:: supported_image_types
+
+   .. versionadded:: 1.4
+
+   .. versionchanged:: 1.5
+
+      Since Sphinx 1.5, the epub3 builder is used as the default epub builder.
+
+.. module:: sphinx.builders.latex
+.. class:: LaTeXBuilder
+
+   This builder produces LaTeX source files in the output directory.  The
+   actual PDF builds happen inside this output directory and need to be
+   triggered in a second step.  This can be done via
+   :program:`make all-pdf` there.
+   To combine the two steps into only one, use :option:`sphinx-build -M`
+   (i.e. ``-M latexpdf`` not ``-b latexpdf``) or :program:`make latexpdf`
+   at the project root.
+
+   See :confval:`latex_documents` and the chapter :ref:`latex-options` for
+   available options.
+
+   PDF builds need a sufficiently complete LaTeX installation.
+   The testing is currently (since 5.3.0) done on Ubuntu 22.04LTS,
+   whose LaTeX distribution matches upstream TeXLive 2021 as of 2022/02/04,
+   but PDF builds can be successfully done on much older LaTeX installations.
+
+   At any rate, on Ubuntu for example, following packages must all be present:
+
+   * ``texlive-latex-recommended``
+   * ``texlive-fonts-recommended``
+   * ``tex-gyre`` (if :confval:`latex_engine` left to default)
+   * ``texlive-latex-extra``
+   * ``latexmk``
+
+   .. versionchanged:: 4.0.0
+      TeX Gyre fonts now required for ``'pdflatex'`` engine (default).
+
+   Additional packages are needed in some circumstances:
+
+   * ``texlive-lang-cyrillic`` for Cyrillic (and also then
+     ``cm-super`` if using the default fonts),
+   * ``texlive-lang-greek`` for Greek (and also then
+     ``cm-super`` if using the default fonts),
+   * ``texlive-xetex`` if :confval:`latex_engine` is ``'xelatex'``,
+   * ``texlive-luatex`` if :confval:`latex_engine` is ``'lualatex'``,
+   * ``fonts-freefont-otf`` if :confval:`latex_engine` is either
+     ``'xelatex'`` or ``'lualatex'``.
+
+   .. note::
+
+      Since 1.6, ``make latexpdf`` uses on GNU/Linux and macOS
+      :program:`latexmk`, as it
+      makes sure the needed number of runs is automatically executed.
+      On Windows the PDF builds execute a fix number of LaTeX runs
+      (three, then ``makeindex``, then two more).
+
+      One can pass to ``latexmk`` options via the ``LATEXMKOPTS``
+      Makefile variable. For example:
+
+      .. code-block:: console
+
+         make latexpdf LATEXMKOPTS="-silent"
+
+      reduces console output to a minimum.
+
+      Also, if ``latexmk`` is at version 4.52b or higher (January 2017)
+      ``LATEXMKOPTS="-xelatex"`` speeds up PDF builds via XeLateX in case
+      of numerous graphics inclusions.
+
+      To pass options directly to the ``(pdf|xe|lua)latex`` binary, use
+      variable ``LATEXOPTS``, for example:
+
+      .. code-block:: console
+
+         make latexpdf LATEXOPTS="--halt-on-error"
+
+   .. autoattribute:: name
+
+   .. autoattribute:: format
+
+   .. autoattribute:: supported_image_types
+
+Note that a direct PDF builder is being provided by `rinohtype`_. The builder's
+name is ``rinoh``. Refer to the `rinohtype manual`_ for details.
+
+.. _rinohtype: https://github.com/brechtm/rinohtype
+.. _rinohtype manual: https://www.mos6581.org/rinohtype/master/quickstart.html#sphinx-builder
+
+.. module:: sphinx.builders.text
+.. class:: TextBuilder
+
+   This builder produces a text file for each reST file -- this is almost the
+   same as the reST source, but with much of the markup stripped for better
+   readability.
+
+   .. autoattribute:: name
+
+   .. autoattribute:: format
+
+   .. autoattribute:: supported_image_types
+
+   .. versionadded:: 0.4
+
+.. module:: sphinx.builders.manpage
+.. class:: ManualPageBuilder
+
+   This builder produces manual pages in the groff format.  You have to specify
+   which documents are to be included in which manual pages via the
+   :confval:`man_pages` configuration value.
+
+   .. autoattribute:: name
+
+   .. autoattribute:: format
+
+   .. autoattribute:: supported_image_types
+
+   .. versionadded:: 1.0
+
+
+.. module:: sphinx.builders.texinfo
+.. class:: TexinfoBuilder
+
+   This builder produces Texinfo files that can be processed into Info files by
+   the :program:`makeinfo` program.  You have to specify which documents are to
+   be included in which Texinfo files via the :confval:`texinfo_documents`
+   configuration value.
+
+   The Info format is the basis of the on-line help system used by GNU Emacs and
+   the terminal-based program :program:`info`.  See :ref:`texinfo-faq` for more
+   details.  The Texinfo format is the official documentation system used by the
+   GNU project.  More information on Texinfo can be found at
+   `<https://www.gnu.org/software/texinfo/>`_.
+
+   .. autoattribute:: name
+
+   .. autoattribute:: format
+
+   .. autoattribute:: supported_image_types
+
+   .. versionadded:: 1.1
+
+
+.. currentmodule:: sphinxcontrib.serializinghtml
+.. class:: SerializingHTMLBuilder
+
+   This builder uses a module that implements the Python serialization API
+   (`pickle`, `simplejson`, `phpserialize`, and others) to dump the generated
+   HTML documentation.  The pickle builder is a subclass of it.
+
+   A concrete subclass of this builder serializing to the `PHP serialization`_
+   format could look like this::
+
+        import phpserialize
+
+        class PHPSerializedBuilder(SerializingHTMLBuilder):
+            name = 'phpserialized'
+            implementation = phpserialize
+            out_suffix = '.file.phpdump'
+            globalcontext_filename = 'globalcontext.phpdump'
+            searchindex_filename = 'searchindex.phpdump'
+
+   .. _PHP serialization: https://pypi.org/project/phpserialize/
+
+   .. attribute:: implementation
+
+      A module that implements `dump()`, `load()`, `dumps()` and `loads()`
+      functions that conform to the functions with the same names from the
+      pickle module.  Known modules implementing this interface are
+      `simplejson`, `phpserialize`, `plistlib`, and others.
+
+   .. attribute:: out_suffix
+
+      The suffix for all regular files.
+
+   .. attribute:: globalcontext_filename
+
+      The filename for the file that contains the "global context".  This
+      is a dict with some general configuration values such as the name
+      of the project.
+
+   .. attribute:: searchindex_filename
+
+      The filename for the search index Sphinx generates.
+
+   See :ref:`serialization-details` for details about the output format.
+
+   .. versionadded:: 0.5
+
+.. class:: PickleHTMLBuilder
+
+   This builder produces a directory with pickle files containing mostly HTML
+   fragments and TOC information, for use of a web application (or custom
+   postprocessing tool) that doesn't use the standard HTML templates.
+
+   See :ref:`serialization-details` for details about the output format.
+
+   .. autoattribute:: name
+
+      The old name ``web`` still works as well.
+
+   .. autoattribute:: format
+
+   .. autoattribute:: supported_image_types
+
+   The file suffix is ``.fpickle``.  The global context is called
+   ``globalcontext.pickle``, the search index ``searchindex.pickle``.
+
+.. class:: JSONHTMLBuilder
+
+   This builder produces a directory with JSON files containing mostly HTML
+   fragments and TOC information, for use of a web application (or custom
+   postprocessing tool) that doesn't use the standard HTML templates.
+
+   See :ref:`serialization-details` for details about the output format.
+
+   .. autoattribute:: name
+
+   .. autoattribute:: format
+
+   .. autoattribute:: supported_image_types
+
+   The file suffix is ``.fjson``.  The global context is called
+   ``globalcontext.json``, the search index ``searchindex.json``.
+
+   .. versionadded:: 0.5
+
+.. module:: sphinx.builders.gettext
+.. class:: MessageCatalogBuilder
+
+   This builder produces gettext-style message catalogs.  Each top-level file or
+   subdirectory grows a single ``.pot`` catalog template.
+
+   See the documentation on :ref:`intl` for further reference.
+
+   .. autoattribute:: name
+
+   .. autoattribute:: format
+
+   .. autoattribute:: supported_image_types
+
+   .. versionadded:: 1.1
+
+.. module:: sphinx.builders.changes
+.. class:: ChangesBuilder
+
+   This builder produces an HTML overview of all :rst:dir:`versionadded`,
+   :rst:dir:`versionchanged` and :rst:dir:`deprecated` directives for the
+   current :confval:`version`.  This is useful to generate a ChangeLog file, for
+   example.
+
+   .. autoattribute:: name
+
+   .. autoattribute:: format
+
+   .. autoattribute:: supported_image_types
+
+.. module:: sphinx.builders.dummy
+.. class:: DummyBuilder
+
+   This builder produces no output.  The input is only parsed and checked for
+   consistency.  This is useful for linting purposes.
+
+   .. autoattribute:: name
+
+   .. autoattribute:: supported_image_types
+
+   .. versionadded:: 1.4
+
+.. module:: sphinx.builders.linkcheck
+.. class:: CheckExternalLinksBuilder
+
+   This builder scans all documents for external links, tries to open them with
+   ``requests``, and writes an overview which ones are broken and redirected to
+   standard output and to :file:`output.txt` in the output directory.
+
+   .. autoattribute:: name
+
+   .. autoattribute:: format
+
+   .. autoattribute:: supported_image_types
+
+   .. versionchanged:: 1.5
+
+      Since Sphinx 1.5, the linkcheck builder uses the requests module.
+
+   .. versionchanged:: 3.4
+
+      The linkcheck builder retries links when servers apply rate limits.
+
+.. module:: sphinx.builders.xml
+.. class:: XMLBuilder
+
+   This builder produces Docutils-native XML files.  The output can be
+   transformed with standard XML tools such as XSLT processors into arbitrary
+   final forms.
+
+   .. autoattribute:: name
+
+   .. autoattribute:: format
+
+   .. autoattribute:: supported_image_types
+
+   .. versionadded:: 1.2
+
+.. class:: PseudoXMLBuilder
+
+   This builder is used for debugging the Sphinx/Docutils "Reader to Transform
+   to Writer" pipeline. It produces compact pretty-printed "pseudo-XML", files
+   where nesting is indicated by indentation (no end-tags). External
+   attributes for all elements are output, and internal attributes for any
+   leftover "pending" elements are also given.
+
+   .. autoattribute:: name
+
+   .. autoattribute:: format
+
+   .. autoattribute:: supported_image_types
+
+   .. versionadded:: 1.2
+
+
+Built-in Sphinx extensions that offer more builders are:
+
+* :mod:`~sphinx.ext.doctest`
+* :mod:`~sphinx.ext.coverage`
+
+
+.. _serialization-details:
+
+Serialization builder details
+-----------------------------
+
+All serialization builders outputs one file per source file and a few special
+files.  They also copy the reST source files in the directory ``_sources``
+under the output directory.
+
+The :class:`.PickleHTMLBuilder` is a builtin subclass that implements the pickle
+serialization interface.
+
+The files per source file have the extensions of
+:attr:`~.SerializingHTMLBuilder.out_suffix`, and are arranged in directories
+just as the source files are.  They unserialize to a dictionary (or dictionary
+like structure) with these keys:
+
+``body``
+   The HTML "body" (that is, the HTML rendering of the source file), as rendered
+   by the HTML translator.
+
+``title``
+   The title of the document, as HTML (may contain markup).
+
+``toc``
+   The table of contents for the file, rendered as an HTML ``<ul>``.
+
+``display_toc``
+   A boolean that is ``True`` if the ``toc`` contains more than one entry.
+
+``current_page_name``
+   The document name of the current file.
+
+``parents``, ``prev`` and ``next``
+   Information about related chapters in the TOC tree.  Each relation is a
+   dictionary with the keys ``link`` (HREF for the relation) and ``title``
+   (title of the related document, as HTML).  ``parents`` is a list of
+   relations, while ``prev`` and ``next`` are a single relation.
+
+``sourcename``
+   The name of the source file under ``_sources``.
+
+The special files are located in the root output directory.  They are:
+
+:attr:`.SerializingHTMLBuilder.globalcontext_filename`
+   A pickled dict with these keys:
+
+   ``project``, ``copyright``, ``release``, ``version``
+      The same values as given in the configuration file.
+
+   ``style``
+      :confval:`html_style`.
+
+   ``last_updated``
+      Date of last build.
+
+   ``builder``
+      Name of the used builder, in the case of pickles this is always
+      ``'pickle'``.
+
+   ``titles``
+      A dictionary of all documents' titles, as HTML strings.
+
+:attr:`.SerializingHTMLBuilder.searchindex_filename`
+   An index that can be used for searching the documentation.  It is a pickled
+   list with these entries:
+
+   * A list of indexed docnames.
+   * A list of document titles, as HTML strings, in the same order as the first
+     list.
+   * A dict mapping word roots (processed by an English-language stemmer) to a
+     list of integers, which are indices into the first list.
+
+``environment.pickle``
+   The build environment.  This is always a pickle file, independent of the
+   builder and a copy of the environment that was used when the builder was
+   started.
+
+   .. todo:: Document common members.
+
+   Unlike the other pickle files this pickle file requires that the ``sphinx``
+   package is available on unpickling.
diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst
new file mode 100644
index 0000000..d440132
--- /dev/null
+++ b/doc/usage/configuration.rst
@@ -0,0 +1,3094 @@
+.. highlight:: python
+
+.. _build-config:
+
+=============
+Configuration
+=============
+
+.. module:: conf
+   :synopsis: Build configuration file.
+
+The :term:`configuration directory` must contain a file named :file:`conf.py`.
+This file (containing Python code) is called the "build configuration file"
+and contains (almost) all configuration needed to customize Sphinx input
+and output behavior.
+
+An optional file `docutils.conf`_ can be added to the configuration
+directory to adjust `Docutils`_ configuration if not otherwise overridden or
+set by Sphinx.
+
+.. _`docutils`: https://docutils.sourceforge.io/
+.. _`docutils.conf`: https://docutils.sourceforge.io/docs/user/config.html
+
+The configuration file is executed as Python code at build time (using
+:func:`importlib.import_module`, and with the current directory set to its
+containing directory), and therefore can execute arbitrarily complex code.
+Sphinx then reads simple names from the file's namespace as its configuration.
+
+Important points to note:
+
+* If not otherwise documented, values must be strings, and their default is the
+  empty string.
+
+* The term "fully-qualified name" refers to a string that names an importable
+  Python object inside a module; for example, the FQN
+  ``"sphinx.builders.Builder"`` means the ``Builder`` class in the
+  ``sphinx.builders`` module.
+
+* Remember that document names use ``/`` as the path separator and don't
+  contain the file name extension.
+
+* Since :file:`conf.py` is read as a Python file, the usual rules apply for
+  encodings and Unicode support.
+
+* The contents of the config namespace are pickled (so that Sphinx can find out
+  when configuration changes), so it may not contain unpickleable values --
+  delete them from the namespace with ``del`` if appropriate.  Modules are
+  removed automatically, so you don't need to ``del`` your imports after use.
+
+  .. _conf-tags:
+
+* There is a special object named ``tags`` available in the config file.
+  It can be used to query and change the tags (see :ref:`tags`).  Use
+  ``tags.has('tag')`` to query, ``tags.add('tag')`` and ``tags.remove('tag')``
+  to change. Only tags set via the ``-t`` command-line option or via
+  ``tags.add('tag')`` can be queried using ``tags.has('tag')``.
+  Note that the current builder tag is not available in ``conf.py``, as it is
+  created *after* the builder is initialized.
+
+
+Project information
+-------------------
+
+.. confval:: project
+
+   The documented project's name.
+
+.. confval:: author
+
+   The author name(s) of the document.  The default value is ``'unknown'``.
+
+.. confval:: copyright
+
+   A copyright statement in the style ``'2008, Author Name'``.
+
+   .. versionchanged:: 7.1
+      The value may now be a sequence of copyright statements in the above form,
+      which will be displayed each to their own line.
+
+.. confval:: project_copyright
+
+   An alias of :confval:`copyright`.
+
+   .. versionadded:: 3.5
+
+.. confval:: version
+
+   The major project version, used as the replacement for ``|version|``.  For
+   example, for the Python documentation, this may be something like ``2.6``.
+
+.. confval:: release
+
+   The full project version, used as the replacement for ``|release|`` and
+   e.g. in the HTML templates.  For example, for the Python documentation, this
+   may be something like ``2.6.0rc1``.
+
+   If you don't need the separation provided between :confval:`version` and
+   :confval:`release`, just set them both to the same value.
+
+
+General configuration
+---------------------
+
+.. confval:: extensions
+
+   A list of strings that are module names of :doc:`extensions
+   <extensions/index>`. These can be extensions coming with Sphinx (named
+   ``sphinx.ext.*``) or custom ones.
+
+   Note that you can extend :data:`sys.path` within the conf file if your
+   extensions live in another directory -- but make sure you use absolute paths.
+   If your extension path is relative to the :term:`configuration directory`,
+   use :func:`os.path.abspath` like so::
+
+      import sys, os
+
+      sys.path.append(os.path.abspath('sphinxext'))
+
+      extensions = ['extname']
+
+   That way, you can load an extension called ``extname`` from the subdirectory
+   ``sphinxext``.
+
+   The configuration file itself can be an extension; for that, you only need
+   to provide a :func:`setup` function in it.
+
+.. confval:: source_suffix
+
+   The file extensions of source files.  Sphinx considers the files with this
+   suffix as sources.  The value can be a dictionary mapping file extensions
+   to file types.  For example::
+
+      source_suffix = {
+          '.rst': 'restructuredtext',
+          '.txt': 'restructuredtext',
+          '.md': 'markdown',
+      }
+
+   By default, Sphinx only supports ``'restructuredtext'`` file type.  You can
+   add a new file type using source parser extensions.  Please read a document
+   of the extension to know which file type the extension supports.
+
+   The value may also be a list of file extensions: then Sphinx will consider
+   that they all map to the ``'restructuredtext'`` file type.
+
+   Default is ``{'.rst': 'restructuredtext'}``.
+
+   .. note:: file extensions have to start with a dot (e.g. ``.rst``).
+
+   .. versionchanged:: 1.3
+      Can now be a list of extensions.
+
+   .. versionchanged:: 1.8
+      Support file type mapping
+
+.. confval:: source_encoding
+
+   The encoding of all reST source files.  The recommended encoding, and the
+   default value, is ``'utf-8-sig'``.
+
+   .. versionadded:: 0.5
+      Previously, Sphinx accepted only UTF-8 encoded sources.
+
+.. confval:: source_parsers
+
+   If given, a dictionary of parser classes for different source suffices.  The
+   keys are the suffix, the values can be either a class or a string giving a
+   fully-qualified name of a parser class.  The parser class can be either
+   ``docutils.parsers.Parser`` or :class:`sphinx.parsers.Parser`.  Files with a
+   suffix that is not in the dictionary will be parsed with the default
+   reStructuredText parser.
+
+   For example::
+
+      source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
+
+   .. note::
+
+      Refer to :doc:`/usage/markdown` for more information on using Markdown
+      with Sphinx.
+
+   .. versionadded:: 1.3
+
+   .. deprecated:: 1.8
+      Now Sphinx provides an API :meth:`.Sphinx.add_source_parser` to register
+      a source parser.  Please use it instead.
+
+.. confval:: master_doc
+
+   Same as :confval:`root_doc`.
+
+   .. versionchanged:: 4.0
+      Renamed ``master_doc`` to ``root_doc``.
+
+.. confval:: root_doc
+
+   The document name of the "root" document, that is, the document that
+   contains the root :rst:dir:`toctree` directive.  Default is ``'index'``.
+
+   .. versionchanged:: 2.0
+      The default is changed to ``'index'`` from ``'contents'``.
+   .. versionchanged:: 4.0
+      Renamed ``root_doc`` from ``master_doc``.
+
+.. confval:: exclude_patterns
+
+   A list of glob-style patterns [1]_ that should be excluded when looking for
+   source files. They are matched against the source file names relative
+   to the source directory, using slashes as directory separators on all
+   platforms.
+
+   Example patterns:
+
+   - ``'library/xml.rst'`` -- ignores the ``library/xml.rst`` file
+   - ``'library/xml'`` -- ignores the ``library/xml`` directory
+   - ``'library/xml*'`` -- ignores all files and directories starting with
+     ``library/xml``
+   - ``'**/.svn'`` -- ignores all ``.svn`` directories
+
+   :confval:`exclude_patterns` is also consulted when looking for static files
+   in :confval:`html_static_path` and :confval:`html_extra_path`.
+
+   .. versionadded:: 1.0
+
+.. confval:: include_patterns
+
+   A list of glob-style patterns [1]_ that are used to find source files. They
+   are matched against the source file names relative to the source directory,
+   using slashes as directory separators on all platforms. The default is ``**``,
+   meaning that all files are recursively included from the source directory.
+
+   Example patterns:
+
+   - ``'**'`` -- all files in the source directory and subdirectories, recursively
+   - ``'library/xml'`` -- just the ``library/xml`` directory
+   - ``'library/xml*'`` -- all files and directories starting with ``library/xml``
+   - ``'**/doc'`` -- all ``doc`` directories (this might be useful if
+     documentation is co-located with source files)
+
+   .. versionadded:: 5.1
+
+.. confval:: templates_path
+
+   A list of paths that contain extra templates (or templates that overwrite
+   builtin/theme-specific templates).  Relative paths are taken as relative to
+   the configuration directory.
+
+   .. versionchanged:: 1.3
+      As these files are not meant to be built, they are automatically added to
+      :confval:`exclude_patterns`.
+
+.. confval:: template_bridge
+
+   A string with the fully-qualified name of a callable (or simply a class)
+   that returns an instance of :class:`~sphinx.application.TemplateBridge`.
+   This instance is then used to render HTML documents, and possibly the output
+   of other builders (currently the changes builder).  (Note that the template
+   bridge must be made theme-aware if HTML themes are to be used.)
+
+.. confval:: rst_epilog
+
+   .. index:: pair: global; substitutions
+
+   A string of reStructuredText that will be included at the end of every source
+   file that is read.  This is a possible place to add substitutions that should
+   be available in every file (another being :confval:`rst_prolog`).  An
+   example::
+
+      rst_epilog = """
+      .. |psf| replace:: Python Software Foundation
+      """
+
+   .. versionadded:: 0.6
+
+.. confval:: rst_prolog
+
+   .. index:: pair: global; substitutions
+
+   A string of reStructuredText that will be included at the beginning of every
+   source file that is read.  This is a possible place to add substitutions that
+   should be available in every file (another being :confval:`rst_epilog`).  An
+   example::
+
+      rst_prolog = """
+      .. |psf| replace:: Python Software Foundation
+      """
+
+   .. versionadded:: 1.0
+
+.. confval:: primary_domain
+
+   .. index:: default; domain
+              primary; domain
+
+   The name of the default :doc:`domain </usage/restructuredtext/domains>`.
+   Can also be ``None`` to disable a default domain.  The default is ``'py'``.
+   Those objects in other domains (whether the domain name is given explicitly,
+   or selected by a :rst:dir:`default-domain` directive) will have the domain
+   name explicitly prepended when named (e.g., when the default domain is C,
+   Python functions will be named "Python function", not just "function").
+
+   .. versionadded:: 1.0
+
+.. confval:: default_role
+
+   .. index:: default; role
+
+   The name of a reST role (builtin or Sphinx extension) to use as the default
+   role, that is, for text marked up ```like this```.  This can be set to
+   ``'py:obj'`` to make ```filter``` a cross-reference to the Python function
+   "filter".  The default is ``None``, which doesn't reassign the default role.
+
+   The default role can always be set within individual documents using the
+   standard reST :dudir:`default-role` directive.
+
+   .. versionadded:: 0.4
+
+.. confval:: keep_warnings
+
+   If true, keep warnings as "system message" paragraphs in the built
+   documents.  Regardless of this setting, warnings are always written to the
+   standard error stream when ``sphinx-build`` is run.
+
+   The default is ``False``, the pre-0.5 behavior was to always keep them.
+
+   .. versionadded:: 0.5
+
+.. confval:: suppress_warnings
+
+   A list of warning types to suppress arbitrary warning messages.
+
+   Sphinx supports following warning types:
+
+   * ``app.add_node``
+   * ``app.add_directive``
+   * ``app.add_role``
+   * ``app.add_generic_role``
+   * ``app.add_source_parser``
+   * ``autosectionlabel.*``
+   * ``download.not_readable``
+   * ``epub.unknown_project_files``
+   * ``epub.duplicated_toc_entry``
+   * ``i18n.inconsistent_references``
+   * ``index``
+   * ``image.not_readable``
+   * ``ref.term``
+   * ``ref.ref``
+   * ``ref.numref``
+   * ``ref.keyword``
+   * ``ref.option``
+   * ``ref.citation``
+   * ``ref.footnote``
+   * ``ref.doc``
+   * ``ref.python``
+   * ``misc.highlighting_failure``
+   * ``toc.circular``
+   * ``toc.excluded``
+   * ``toc.not_readable``
+   * ``toc.secnum``
+
+   You can choose from these types.  You can also give only the first
+   component to exclude all warnings attached to it.
+
+   Now, this option should be considered *experimental*.
+
+   .. versionadded:: 1.4
+
+   .. versionchanged:: 1.5
+
+      Added ``misc.highlighting_failure``
+
+   .. versionchanged:: 1.5.1
+
+      Added ``epub.unknown_project_files``
+
+   .. versionchanged:: 1.6
+
+      Added ``ref.footnote``
+
+   .. versionchanged:: 2.1
+
+      Added ``autosectionlabel.*``
+
+   .. versionchanged:: 3.3.0
+
+      Added ``epub.duplicated_toc_entry``
+
+   .. versionchanged:: 4.3
+
+      Added ``toc.excluded`` and ``toc.not_readable``
+
+   .. versionadded:: 4.5
+
+      Added ``i18n.inconsistent_references``
+
+    .. versionadded:: 7.1
+
+        Added ``index`` warning type.
+
+.. confval:: needs_sphinx
+
+   If set to a ``major.minor`` version string like ``'1.1'``, Sphinx will
+   compare it with its version and refuse to build if it is too old.  Default
+   is no requirement.
+
+   .. versionadded:: 1.0
+
+   .. versionchanged:: 1.4
+      also accepts micro version string
+
+.. confval:: needs_extensions
+
+   This value can be a dictionary specifying version requirements for
+   extensions in :confval:`extensions`, e.g. ``needs_extensions =
+   {'sphinxcontrib.something': '1.5'}``.  The version strings should be in the
+   form ``major.minor``.  Requirements do not have to be specified for all
+   extensions, only for those you want to check.
+
+   This requires that the extension specifies its version to Sphinx (see
+   :ref:`dev-extensions` for how to do that).
+
+   .. versionadded:: 1.3
+
+.. confval:: manpages_url
+
+   A URL to cross-reference :rst:role:`manpage` roles. If this is
+   defined to ``https://manpages.debian.org/{path}``, the
+   :literal:`:manpage:`man(1)`` role will link to
+   <https://manpages.debian.org/man(1)>. The patterns available are:
+
+   * ``page`` - the manual page (``man``)
+   * ``section`` - the manual section (``1``)
+   * ``path`` - the original manual page and section specified (``man(1)``)
+
+   This also supports manpages specified as ``man.1``.
+
+   .. note:: This currently affects only HTML writers but could be
+             expanded in the future.
+
+   .. versionadded:: 1.7
+
+.. confval:: nitpicky
+
+   If true, Sphinx will warn about *all* references where the target cannot be
+   found.  Default is ``False``.  You can activate this mode temporarily using
+   the :option:`-n <sphinx-build -n>` command-line switch.
+
+   .. versionadded:: 1.0
+
+.. confval:: nitpick_ignore
+
+   A set or list of ``(type, target)`` tuples (by default empty) that should be
+   ignored when generating warnings in "nitpicky mode".  Note that ``type``
+   should include the domain name if present.  Example entries would be
+   ``('py:func', 'int')`` or ``('envvar', 'LD_LIBRARY_PATH')``.
+
+   .. versionadded:: 1.1
+   .. versionchanged:: 6.2
+      Changed allowable container types to a set, list, or tuple
+
+.. confval:: nitpick_ignore_regex
+
+   An extended version of :confval:`nitpick_ignore`, which instead interprets
+   the ``type`` and ``target`` strings as regular expressions. Note, that the
+   regular expression must match the whole string (as if the ``^`` and ``$``
+   markers were inserted).
+
+   For example, ``(r'py:.*', r'foo.*bar\.B.*')`` will ignore nitpicky warnings
+   for all python entities that start with ``'foo'`` and have ``'bar.B'`` in
+   them, such as ``('py:const', 'foo_package.bar.BAZ_VALUE')`` or
+   ``('py:class', 'food.bar.Barman')``.
+
+   .. versionadded:: 4.1
+   .. versionchanged:: 6.2
+      Changed allowable container types to a set, list, or tuple
+
+.. confval:: numfig
+
+   If true, figures, tables and code-blocks are automatically numbered if they
+   have a caption.  The :rst:role:`numref` role is enabled.
+   Obeyed so far only by HTML and LaTeX builders. Default is ``False``.
+
+   .. note::
+
+      The LaTeX builder always assigns numbers whether this option is enabled
+      or not.
+
+   .. versionadded:: 1.3
+
+.. confval:: numfig_format
+
+   A dictionary mapping ``'figure'``, ``'table'``, ``'code-block'`` and
+   ``'section'`` to strings that are used for format of figure numbers.
+   As a special character, ``%s`` will be replaced to figure number.
+
+   Default is to use ``'Fig. %s'`` for ``'figure'``, ``'Table %s'`` for
+   ``'table'``, ``'Listing %s'`` for ``'code-block'`` and ``'Section %s'`` for
+   ``'section'``.
+
+   .. versionadded:: 1.3
+
+.. confval:: numfig_secnum_depth
+
+   - if set to ``0``, figures, tables and code-blocks are continuously numbered
+     starting at ``1``.
+   - if ``1`` (default) numbers will be ``x.1``, ``x.2``, ... with ``x``
+     the section number (top level sectioning; no ``x.`` if no section).
+     This naturally applies only if section numbering has been activated via
+     the ``:numbered:`` option of the :rst:dir:`toctree` directive.
+   - ``2`` means that numbers will be ``x.y.1``, ``x.y.2``, ... if located in
+     a sub-section (but still ``x.1``, ``x.2``, ... if located directly under a
+     section and ``1``, ``2``, ... if not in any top level section.)
+   - etc...
+
+   .. versionadded:: 1.3
+
+   .. versionchanged:: 1.7
+      The LaTeX builder obeys this setting (if :confval:`numfig` is set to
+      ``True``).
+
+.. confval:: smartquotes
+
+   If true, the `Docutils Smart Quotes transform`__, originally based on
+   `SmartyPants`__ (limited to English) and currently applying to many
+   languages, will be used to convert quotes and dashes to typographically
+   correct entities.  Default: ``True``.
+
+   __ https://docutils.sourceforge.io/docs/user/smartquotes.html
+   __ https://daringfireball.net/projects/smartypants/
+
+   .. versionadded:: 1.6.6
+      It replaces deprecated :confval:`html_use_smartypants`.
+      It applies by default to all builders except ``man`` and ``text``
+      (see :confval:`smartquotes_excludes`.)
+
+   A `docutils.conf`__ file located in the configuration directory (or a
+   global :file:`~/.docutils` file) is obeyed unconditionally if it
+   *deactivates* smart quotes via the corresponding `Docutils option`__.  But
+   if it *activates* them, then :confval:`smartquotes` does prevail.
+
+   __ https://docutils.sourceforge.io/docs/user/config.html
+   __ https://docutils.sourceforge.io/docs/user/config.html#smart-quotes
+
+.. confval:: smartquotes_action
+
+   This string customizes the Smart Quotes transform.  See the file
+   :file:`smartquotes.py` at the `Docutils repository`__ for details.  The
+   default ``'qDe'`` educates normal **q**\ uote characters ``"``, ``'``,
+   em- and en-**D**\ ashes ``---``, ``--``, and **e**\ llipses ``...``.
+
+   .. versionadded:: 1.6.6
+
+   __ https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
+
+.. confval:: smartquotes_excludes
+
+   This is a ``dict`` whose default is::
+
+     {'languages': ['ja'], 'builders': ['man', 'text']}
+
+   Each entry gives a sufficient condition to ignore the
+   :confval:`smartquotes` setting and deactivate the Smart Quotes transform.
+   Accepted keys are as above ``'builders'`` or ``'languages'``.
+   The values are lists.
+
+   .. note:: Currently, in case of invocation of :program:`make` with multiple
+      targets, the first target name is the only one which is tested against
+      the ``'builders'`` entry and it decides for all.  Also, a ``make text``
+      following ``make html`` needs to be issued in the form ``make text
+      O="-E"`` to force re-parsing of source files, as the cached ones are
+      already transformed.  On the other hand the issue does not arise with
+      direct usage of :program:`sphinx-build` as it caches
+      (in its default usage) the parsed source files in per builder locations.
+
+   .. hint:: An alternative way to effectively deactivate (or customize) the
+      smart quotes for a given builder, for example ``latex``, is to use
+      ``make`` this way:
+
+      .. code-block:: console
+
+         make latex O="-D smartquotes_action="
+
+      This can follow some ``make html`` with no problem, in contrast to the
+      situation from the prior note.
+
+   .. versionadded:: 1.6.6
+
+.. confval:: user_agent
+
+   A User-Agent of Sphinx.  It is used for a header on HTTP access (ex.
+   linkcheck, intersphinx and so on).  Default is ``"Sphinx/X.Y.Z
+   requests/X.Y.Z python/X.Y.Z"``.
+
+   .. versionadded:: 2.3
+
+.. confval:: tls_verify
+
+   If true, Sphinx verifies server certifications.  Default is ``True``.
+
+   .. versionadded:: 1.5
+
+.. confval:: tls_cacerts
+
+   A path to a certification file of CA or a path to directory which
+   contains the certificates.  This also allows a dictionary mapping
+   hostname to the path to certificate file.
+   The certificates are used to verify server certifications.
+
+   .. versionadded:: 1.5
+
+   .. tip:: Sphinx uses requests_ as a HTTP library internally.
+            Therefore, Sphinx refers a certification file on the
+            directory pointed ``REQUESTS_CA_BUNDLE`` environment
+            variable if ``tls_cacerts`` not set.
+
+            .. _requests: https://requests.readthedocs.io/en/master/
+
+.. confval:: today
+             today_fmt
+
+   These values determine how to format the current date, used as the
+   replacement for ``|today|``.
+
+   * If you set :confval:`today` to a non-empty value, it is used.
+   * Otherwise, the current time is formatted using :func:`time.strftime` and
+     the format given in :confval:`today_fmt`.
+
+   The default is now :confval:`today` and a :confval:`today_fmt` of ``'%b %d,
+   %Y'`` (or, if translation is enabled with :confval:`language`, an equivalent
+   format for the selected locale).
+
+.. confval:: highlight_language
+
+   The default language to highlight source code in.  The default is
+   ``'default'``.  It is similar to ``'python3'``; it is mostly a superset of
+   ``'python'`` but it fallbacks to ``'none'`` without warning if failed.
+   ``'python3'`` and other languages will emit warning if failed.
+
+   The value should be a valid Pygments lexer name, see
+   :ref:`code-examples` for more details.
+
+   .. versionadded:: 0.5
+
+   .. versionchanged:: 1.4
+      The default is now ``'default'``.  If you prefer Python 2 only
+      highlighting, you can set it back to ``'python'``.
+
+.. confval:: highlight_options
+
+   A dictionary that maps language names to options for the lexer modules of
+   Pygments.  These are lexer-specific; for the options understood by each,
+   see the `Pygments documentation <https://pygments.org/docs/lexers>`_.
+
+   Example::
+
+     highlight_options = {
+       'default': {'stripall': True},
+       'php': {'startinline': True},
+     }
+
+   A single dictionary of options are also allowed.  Then it is recognized
+   as options to the lexer specified by :confval:`highlight_language`::
+
+     # configuration for the ``highlight_language``
+     highlight_options = {'stripall': True}
+
+   .. versionadded:: 1.3
+   .. versionchanged:: 3.5
+
+      Allow to configure highlight options for multiple languages
+
+.. confval:: pygments_style
+
+   The style name to use for Pygments highlighting of source code.  If not set,
+   either the theme's default style or ``'sphinx'`` is selected for HTML
+   output.
+
+   .. versionchanged:: 0.3
+      If the value is a fully-qualified name of a custom Pygments style class,
+      this is then used as custom style.
+
+.. confval:: maximum_signature_line_length
+
+   If a signature's length in characters exceeds the number set, each
+   parameter within the signature will be displayed on an individual logical
+   line.
+
+   When ``None`` (the default), there is no maximum length and the entire
+   signature will be displayed on a single logical line.
+
+   A 'logical line' is similar to a hard line break---builders or themes may
+   choose to 'soft wrap' a single logical line, and this setting does not affect
+   that behaviour.
+
+   Domains may provide options to suppress any hard wrapping on an individual
+   object directive, such as seen in the C, C++, and Python domains (e.g.
+   :rst:dir:`py:function:single-line-parameter-list`).
+
+   .. versionadded:: 7.1
+
+.. confval:: add_function_parentheses
+
+   A boolean that decides whether parentheses are appended to function and
+   method role text (e.g. the content of ``:func:`input```) to signify that the
+   name is callable.  Default is ``True``.
+
+.. confval:: add_module_names
+
+   A boolean that decides whether module names are prepended to all
+   :term:`object` names (for object types where a "module" of some kind is
+   defined), e.g. for :rst:dir:`py:function` directives.  Default is ``True``.
+
+.. confval:: toc_object_entries
+
+  Create table of contents entries for domain objects (e.g. functions, classes,
+  attributes, etc.). Default is ``True``.
+
+.. confval:: toc_object_entries_show_parents
+
+   A string that determines how domain objects (e.g. functions, classes,
+   attributes, etc.) are displayed in their table of contents entry.
+
+   Use ``domain`` to allow the domain to determine the appropriate number of
+   parents to show. For example, the Python domain would show ``Class.method()``
+   and ``function()``, leaving out the ``module.`` level of parents.
+   This is the default setting.
+
+   Use ``hide`` to only show the name of the element without any parents
+   (i.e. ``method()``).
+
+   Use ``all`` to show the fully-qualified name for the object
+   (i.e. ``module.Class.method()``),  displaying all parents.
+
+   .. versionadded:: 5.2
+
+.. confval:: show_authors
+
+   A boolean that decides whether :rst:dir:`codeauthor` and
+   :rst:dir:`sectionauthor` directives produce any output in the built files.
+
+.. confval:: modindex_common_prefix
+
+   A list of prefixes that are ignored for sorting the Python module index
+   (e.g., if this is set to ``['foo.']``, then ``foo.bar`` is shown under ``B``,
+   not ``F``). This can be handy if you document a project that consists of a
+   single package.  Works only for the HTML builder currently.  Default is
+   ``[]``.
+
+   .. versionadded:: 0.6
+
+.. confval:: trim_footnote_reference_space
+
+   Trim spaces before footnote references that are necessary for the reST
+   parser to recognize the footnote, but do not look too nice in the output.
+
+   .. versionadded:: 0.6
+
+.. confval:: trim_doctest_flags
+
+   If true, doctest flags (comments looking like ``# doctest: FLAG, ...``) at
+   the ends of lines and ``<BLANKLINE>`` markers are removed for all code
+   blocks showing interactive Python sessions (i.e. doctests).  Default is
+   ``True``.  See the extension :mod:`~sphinx.ext.doctest` for more
+   possibilities of including doctests.
+
+   .. versionadded:: 1.0
+   .. versionchanged:: 1.1
+      Now also removes ``<BLANKLINE>``.
+
+.. confval:: strip_signature_backslash
+
+   Default is ``False``.
+   When backslash stripping is enabled then every occurrence of ``\\`` in a
+   domain directive will be changed to ``\``, even within string literals.
+   This was the behaviour before version 3.0, and setting this variable to
+   ``True`` will reinstate that behaviour.
+
+   .. versionadded:: 3.0
+
+.. confval:: option_emphasise_placeholders
+
+   Default is ``False``.
+   When enabled, emphasise placeholders in :rst:dir:`option` directives.
+   To display literal braces, escape with a backslash (``\{``). For example,
+   ``option_emphasise_placeholders=True`` and ``.. option:: -foption={TYPE}`` would
+   render with ``TYPE`` emphasised.
+
+   .. versionadded:: 5.1
+
+.. _intl-options:
+
+Options for internationalization
+--------------------------------
+
+These options influence Sphinx's *Native Language Support*.  See the
+documentation on :ref:`intl` for details.
+
+.. confval:: language
+
+   The code for the language the docs are written in.  Any text automatically
+   generated by Sphinx will be in that language.  Also, Sphinx will try to
+   substitute individual paragraphs from your documents with the translation
+   sets obtained from :confval:`locale_dirs`.  Sphinx will search
+   language-specific figures named by :confval:`figure_language_filename`
+   (e.g. the German version of ``myfigure.png`` will be ``myfigure.de.png``
+   by default setting) and substitute them for original figures.  In the LaTeX
+   builder, a suitable language will be selected as an option for the *Babel*
+   package.  Default is ``'en'``.
+
+   .. versionadded:: 0.5
+
+   .. versionchanged:: 1.4
+
+      Support figure substitution
+
+   .. versionchanged:: 5.0
+
+   Currently supported languages by Sphinx are:
+
+   * ``ar`` -- Arabic
+   * ``bg`` -- Bulgarian
+   * ``bn`` -- Bengali
+   * ``ca`` -- Catalan
+   * ``cak`` -- Kaqchikel
+   * ``cs`` -- Czech
+   * ``cy`` -- Welsh
+   * ``da`` -- Danish
+   * ``de`` -- German
+   * ``el`` -- Greek
+   * ``en`` -- English (default)
+   * ``eo`` -- Esperanto
+   * ``es`` -- Spanish
+   * ``et`` -- Estonian
+   * ``eu`` -- Basque
+   * ``fa`` -- Iranian
+   * ``fi`` -- Finnish
+   * ``fr`` -- French
+   * ``he`` -- Hebrew
+   * ``hi`` -- Hindi
+   * ``hi_IN`` -- Hindi (India)
+   * ``hr`` -- Croatian
+   * ``hu`` -- Hungarian
+   * ``id`` -- Indonesian
+   * ``it`` -- Italian
+   * ``ja`` -- Japanese
+   * ``ko`` -- Korean
+   * ``lt`` -- Lithuanian
+   * ``lv`` -- Latvian
+   * ``mk`` -- Macedonian
+   * ``nb_NO`` -- Norwegian Bokmal
+   * ``ne`` -- Nepali
+   * ``nl`` -- Dutch
+   * ``pl`` -- Polish
+   * ``pt`` -- Portuguese
+   * ``pt_BR`` -- Brazilian Portuguese
+   * ``pt_PT`` -- European Portuguese
+   * ``ro`` -- Romanian
+   * ``ru`` -- Russian
+   * ``si`` -- Sinhala
+   * ``sk`` -- Slovak
+   * ``sl`` -- Slovenian
+   * ``sq`` -- Albanian
+   * ``sr`` -- Serbian
+   * ``sr@latin`` -- Serbian (Latin)
+   * ``sr_RS`` -- Serbian (Cyrillic)
+   * ``sv`` -- Swedish
+   * ``ta`` -- Tamil
+   * ``te`` -- Telugu
+   * ``tr`` -- Turkish
+   * ``uk_UA`` -- Ukrainian
+   * ``ur`` -- Urdu
+   * ``vi`` -- Vietnamese
+   * ``zh_CN`` -- Simplified Chinese
+   * ``zh_TW`` -- Traditional Chinese
+
+.. confval:: locale_dirs
+
+   .. versionadded:: 0.5
+
+   Directories in which to search for additional message catalogs (see
+   :confval:`language`), relative to the source directory.  The directories on
+   this path are searched by the standard :mod:`gettext` module.
+
+   Internal messages are fetched from a text domain of ``sphinx``; so if you
+   add the directory :file:`./locale` to this setting, the message catalogs
+   (compiled from ``.po`` format using :program:`msgfmt`) must be in
+   :file:`./locale/{language}/LC_MESSAGES/sphinx.mo`.  The text domain of
+   individual documents depends on :confval:`gettext_compact`.
+
+   The default is ``['locales']``.
+
+   .. note:: The :option:`-v option for sphinx-build command <sphinx-build -v>`
+             is useful to check the locale_dirs config works as expected.  It
+             emits debug messages if message catalog directory not found.
+
+   .. versionchanged:: 1.5
+      Use ``locales`` directory as a default value
+
+.. confval:: gettext_allow_fuzzy_translations
+
+   If true, "fuzzy" messages in the message catalogs are used for translation.
+   The default is ``False``.
+
+   .. versionadded:: 4.3
+
+.. confval:: gettext_compact
+
+   .. versionadded:: 1.1
+
+   If true, a document's text domain is its docname if it is a top-level
+   project file and its very base directory otherwise.
+
+   If set to string, all document's text domain is this string, making all
+   documents use single text domain.
+
+   By default, the document ``markup/code.rst`` ends up in the ``markup`` text
+   domain.  With this option set to ``False``, it is ``markup/code``.
+
+   .. versionchanged:: 3.3
+      The string value is now accepted.
+
+.. confval:: gettext_uuid
+
+   If true, Sphinx generates uuid information for version tracking in message
+   catalogs. It is used for:
+
+   * Add uid line for each msgids in .pot files.
+   * Calculate similarity between new msgids and previously saved old msgids.
+     This calculation takes a long time.
+
+   If you want to accelerate the calculation, you can use
+   ``python-levenshtein`` 3rd-party package written in C by using
+   :command:`pip install python-levenshtein`.
+
+   The default is ``False``.
+
+   .. versionadded:: 1.3
+
+.. confval:: gettext_location
+
+   If true, Sphinx generates location information for messages in message
+   catalogs.
+
+   The default is ``True``.
+
+   .. versionadded:: 1.3
+
+.. confval:: gettext_auto_build
+
+   If true, Sphinx builds mo file for each translation catalog files.
+
+   The default is ``True``.
+
+   .. versionadded:: 1.3
+
+.. confval:: gettext_additional_targets
+
+   To specify names to enable gettext extracting and translation applying for
+   i18n additionally. You can specify below names:
+
+   :index: index terms
+   :literal-block: literal blocks (``::`` annotation and ``code-block`` directive)
+   :doctest-block: doctest block
+   :raw: raw content
+   :image: image/figure uri
+
+   For example: ``gettext_additional_targets = ['literal-block', 'image']``.
+
+   The default is ``[]``.
+
+   .. versionadded:: 1.3
+   .. versionchanged:: 4.0
+
+      The alt text for image is translated by default.
+
+.. confval:: figure_language_filename
+
+   The filename format for language-specific figures.  The default value is
+   ``{root}.{language}{ext}``.  It will be expanded to
+   ``dirname/filename.en.png`` from ``.. image:: dirname/filename.png``.
+   The available format tokens are:
+
+   * ``{root}`` - the filename, including any path component, without the file
+     extension, e.g. ``dirname/filename``
+   * ``{path}`` - the directory path component of the filename, with a trailing
+     slash if non-empty, e.g. ``dirname/``
+   * ``{docpath}`` - the directory path component for the current document, with
+     a trailing slash if non-empty.
+   * ``{basename}`` - the filename without the directory path or file extension
+     components, e.g. ``filename``
+   * ``{ext}`` - the file extension, e.g. ``.png``
+   * ``{language}`` - the translation language, e.g. ``en``
+
+   For example, setting this to ``{path}{language}/{basename}{ext}`` will
+   expand to ``dirname/en/filename.png`` instead.
+
+   .. versionadded:: 1.4
+
+   .. versionchanged:: 1.5
+      Added ``{path}`` and ``{basename}`` tokens.
+
+   .. versionchanged:: 3.2
+      Added ``{docpath}`` token.
+
+.. confval:: translation_progress_classes
+
+   Control which, if any, classes are added to indicate translation progress.
+   This setting would likely only be used by translators of documentation,
+   in order to quickly indicate translated and untranslated content.
+
+   * ``True``: add ``translated`` and ``untranslated`` classes
+     to all nodes with translatable content.
+   * ``translated``: only add the ``translated`` class.
+   * ``untranslated``: only add the ``untranslated`` class.
+   * ``False``: do not add any classes to indicate translation progress.
+
+   Defaults to ``False``.
+
+   .. versionadded:: 7.1
+
+.. _math-options:
+
+Options for Math
+----------------
+
+These options influence Math notations.
+
+.. confval:: math_number_all
+
+   Set this option to ``True`` if you want all displayed math to be numbered.
+   The default is ``False``.
+
+.. confval:: math_eqref_format
+
+   A string used for formatting the labels of references to equations.
+   The ``{number}`` place-holder stands for the equation number.
+
+   Example: ``'Eq.{number}'`` gets rendered as, for example, ``Eq.10``.
+
+.. confval:: math_numfig
+
+   If ``True``, displayed math equations are numbered across pages when
+   :confval:`numfig` is enabled.  The :confval:`numfig_secnum_depth` setting
+   is respected.  The :rst:role:`eq`, not :rst:role:`numref`, role
+   must be used to reference equation numbers.  Default is ``True``.
+
+   .. versionadded:: 1.7
+
+
+.. _html-options:
+
+Options for HTML output
+-----------------------
+
+These options influence HTML as well as HTML Help output, and other builders
+that use Sphinx's HTMLWriter class.
+
+.. confval:: html_theme
+
+   The "theme" that the HTML output should use.  See the :doc:`section about
+   theming </usage/theming>`.  The default is ``'alabaster'``.
+
+   .. versionadded:: 0.6
+
+.. confval:: html_theme_options
+
+   A dictionary of options that influence the look and feel of the selected
+   theme.  These are theme-specific.  For the options understood by the builtin
+   themes, see :ref:`this section <builtin-themes>`.
+
+   .. versionadded:: 0.6
+
+.. confval:: html_theme_path
+
+   A list of paths that contain custom themes, either as subdirectories or as
+   zip files.  Relative paths are taken as relative to the configuration
+   directory.
+
+   .. versionadded:: 0.6
+
+.. confval:: html_style
+
+   The style sheet to use for HTML pages.  A file of that name must exist
+   either in Sphinx's :file:`static/` path, or in one of the custom paths given
+   in :confval:`html_static_path`.  Default is the stylesheet given by the
+   selected theme.  If you only want to add or override a few things compared
+   to the theme's stylesheet, use CSS ``@import`` to import the theme's
+   stylesheet.
+
+.. confval:: html_title
+
+   The "title" for HTML documentation generated with Sphinx's own templates.
+   This is appended to the ``<title>`` tag of individual pages, and used in the
+   navigation bar as the "topmost" element.  It defaults to :samp:`'{<project>}
+   v{<revision>} documentation'`.
+
+.. confval:: html_short_title
+
+   A shorter "title" for the HTML docs.  This is used for links in the
+   header and in the HTML Help docs.  If not given, it defaults to the value of
+   :confval:`html_title`.
+
+   .. versionadded:: 0.4
+
+.. confval:: html_baseurl
+
+   The base URL which points to the root of the HTML documentation.  It is used
+   to indicate the location of document using `The Canonical Link Relation`_.
+   Default: ``''``.
+
+   .. _The Canonical Link Relation: https://datatracker.ietf.org/doc/html/rfc6596
+
+   .. versionadded:: 1.8
+
+.. confval:: html_codeblock_linenos_style
+
+   The style of line numbers for code-blocks.
+
+   * ``'table'`` -- display line numbers using ``<table>`` tag
+   * ``'inline'`` -- display line numbers using ``<span>`` tag (default)
+
+   .. versionadded:: 3.2
+   .. versionchanged:: 4.0
+
+      It defaults to ``'inline'``.
+
+   .. deprecated:: 4.0
+
+.. confval:: html_context
+
+   A dictionary of values to pass into the template engine's context for all
+   pages.  Single values can also be put in this dictionary using the
+   :option:`-A <sphinx-build -A>` command-line option of ``sphinx-build``.
+
+   .. versionadded:: 0.5
+
+.. confval:: html_logo
+
+   If given, this must be the name of an image file (path relative to the
+   :term:`configuration directory`) that is the logo of the docs, or URL that
+   points an image file for the logo.  It is placed at the top of the sidebar;
+   its width should therefore not exceed 200 pixels.  Default: ``None``.
+
+   .. versionadded:: 0.4.1
+      The image file will be copied to the ``_static`` directory of the output
+      HTML, but only if the file does not already exist there.
+
+   .. versionchanged:: 4.0
+      Also accepts the URL for the logo file.
+
+.. confval:: html_favicon
+
+   If given, this must be the name of an image file (path relative to the
+   :term:`configuration directory`) that is the favicon of the docs, or URL that
+   points an image file for the favicon.  Modern browsers use this as the icon
+   for tabs, windows and bookmarks.  It should be a Windows-style icon file
+   (``.ico``), which is 16x16 or 32x32 pixels large.  Default: ``None``.
+
+   .. versionadded:: 0.4
+      The image file will be copied to the ``_static`` directory of the output
+      HTML, but only if the file does not already exist there.
+
+   .. versionchanged:: 4.0
+      Also accepts the URL for the favicon.
+
+.. confval:: html_css_files
+
+   A list of CSS files.  The entry must be a *filename* string or a tuple
+   containing the *filename* string and the *attributes* dictionary.  The
+   *filename* must be relative to the :confval:`html_static_path`, or a full URI
+   with scheme like ``https://example.org/style.css``.  The *attributes* is used
+   for attributes of ``<link>`` tag.  It defaults to an empty list.
+
+   Example::
+
+       html_css_files = ['custom.css',
+                         'https://example.com/css/custom.css',
+                         ('print.css', {'media': 'print'})]
+
+   As a special attribute, *priority* can be set as an integer to load the CSS
+   file earlier or lazier step.  For more information, refer
+   :meth:`.Sphinx.add_css_file()`.
+
+   .. versionadded:: 1.8
+   .. versionchanged:: 3.5
+
+      Support priority attribute
+
+.. confval:: html_js_files
+
+   A list of JavaScript *filename*.  The entry must be a *filename* string or a
+   tuple containing the *filename* string and the *attributes* dictionary.  The
+   *filename* must be relative to the :confval:`html_static_path`, or a full
+   URI with scheme like ``https://example.org/script.js``.  The *attributes* is
+   used for attributes of ``<script>`` tag.  It defaults to an empty list.
+
+   Example::
+
+       html_js_files = ['script.js',
+                        'https://example.com/scripts/custom.js',
+                        ('custom.js', {'async': 'async'})]
+
+   As a special attribute, *priority* can be set as an integer to load the CSS
+   file earlier or lazier step.  For more information, refer
+   :meth:`.Sphinx.add_css_file()`.
+
+   .. versionadded:: 1.8
+   .. versionchanged:: 3.5
+
+      Support priority attribute
+
+.. confval:: html_static_path
+
+   A list of paths that contain custom static files (such as style
+   sheets or script files).  Relative paths are taken as relative to
+   the configuration directory.  They are copied to the output's
+   :file:`_static` directory after the theme's static files, so a file
+   named :file:`default.css` will overwrite the theme's
+   :file:`default.css`.
+
+   As these files are not meant to be built, they are automatically excluded
+   from source files.
+
+   .. note::
+
+      For security reasons, dotfiles under ``html_static_path`` will
+      not be copied.  If you would like to copy them intentionally, please
+      add each filepath to this setting::
+
+          html_static_path = ['_static', '_static/.htaccess']
+
+      Another way to do that, you can also use
+      :confval:`html_extra_path`.  It allows to copy dotfiles under
+      the directories.
+
+   .. versionchanged:: 0.4
+      The paths in :confval:`html_static_path` can now contain subdirectories.
+
+   .. versionchanged:: 1.0
+      The entries in :confval:`html_static_path` can now be single files.
+
+   .. versionchanged:: 1.8
+      The files under :confval:`html_static_path` are excluded from source
+      files.
+
+.. confval:: html_extra_path
+
+   A list of paths that contain extra files not directly related to
+   the documentation, such as :file:`robots.txt` or :file:`.htaccess`.
+   Relative paths are taken as relative to the configuration
+   directory.  They are copied to the output directory.  They will
+   overwrite any existing file of the same name.
+
+   As these files are not meant to be built, they are automatically excluded
+   from source files.
+
+   .. versionadded:: 1.2
+
+   .. versionchanged:: 1.4
+      The dotfiles in the extra directory will be copied to the output
+      directory.  And it refers :confval:`exclude_patterns` on copying extra
+      files and directories, and ignores if path matches to patterns.
+
+.. confval:: html_last_updated_fmt
+
+   If this is not None, a 'Last updated on:' timestamp is inserted
+   at every page bottom, using the given :func:`~time.strftime` format.
+   The empty string is equivalent to ``'%b %d, %Y'`` (or a
+   locale-dependent equivalent).
+
+.. confval:: html_use_smartypants
+
+   If true, quotes and dashes are converted to typographically correct
+   entities.  Default: ``True``.
+
+   .. deprecated:: 1.6
+      To disable smart quotes, use rather :confval:`smartquotes`.
+
+.. confval:: html_permalinks
+
+   Add link anchors for each heading and description environment.
+   Default: ``True``.
+
+   .. versionadded:: 3.5
+
+.. confval:: html_permalinks_icon
+
+   Text for link anchors for each heading and description environment.
+   HTML entities and Unicode are allowed.  Default: a paragraph sign; ``¶``
+
+   .. versionadded:: 3.5
+
+.. confval:: html_sidebars
+
+   Custom sidebar templates, must be a dictionary that maps document names to
+   template names.
+
+   The keys can contain glob-style patterns [1]_, in which case all matching
+   documents will get the specified sidebars.  (A warning is emitted when a
+   more than one glob-style pattern matches for any document.)
+
+   The values can be either lists or single strings.
+
+   * If a value is a list, it specifies the complete list of sidebar templates
+     to include.  If all or some of the default sidebars are to be included,
+     they must be put into this list as well.
+
+     The default sidebars (for documents that don't match any pattern) are
+     defined by theme itself.  Builtin themes are using these templates by
+     default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+     'searchbox.html']``.
+
+   * If a value is a single string, it specifies a custom sidebar to be added
+     between the ``'sourcelink.html'`` and ``'searchbox.html'`` entries.  This
+     is for compatibility with Sphinx versions before 1.0.
+
+   .. deprecated:: 1.7
+
+      a single string value for ``html_sidebars`` will be removed in 2.0
+
+   Builtin sidebar templates that can be rendered are:
+
+   * **localtoc.html** -- a fine-grained table of contents of the current
+     document
+   * **globaltoc.html** -- a coarse-grained table of contents for the whole
+     documentation set, collapsed
+   * **relations.html** -- two links to the previous and next documents
+   * **sourcelink.html** -- a link to the source of the current document, if
+     enabled in :confval:`html_show_sourcelink`
+   * **searchbox.html** -- the "quick search" box
+
+   Example::
+
+      html_sidebars = {
+         '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
+         'using/windows': ['windowssidebar.html', 'searchbox.html'],
+      }
+
+   This will render the custom template ``windowssidebar.html`` and the quick
+   search box within the sidebar of the given document, and render the default
+   sidebars for all other pages (except that the local TOC is replaced by the
+   global TOC).
+
+   .. versionadded:: 1.0
+      The ability to use globbing keys and to specify multiple sidebars.
+
+   Note that this value only has no effect if the chosen theme does not possess
+   a sidebar, like the builtin **scrolls** and **haiku** themes.
+
+.. confval:: html_additional_pages
+
+   Additional templates that should be rendered to HTML pages, must be a
+   dictionary that maps document names to template names.
+
+   Example::
+
+      html_additional_pages = {
+          'download': 'customdownload.html',
+      }
+
+   This will render the template ``customdownload.html`` as the page
+   ``download.html``.
+
+.. confval:: html_domain_indices
+
+   If true, generate domain-specific indices in addition to the general index.
+   For e.g. the Python domain, this is the global module index.  Default is
+   ``True``.
+
+   This value can be a bool or a list of index names that should be generated.
+   To find out the index name for a specific index, look at the HTML file name.
+   For example, the Python module index has the name ``'py-modindex'``.
+
+   .. versionadded:: 1.0
+
+.. confval:: html_use_index
+
+   If true, add an index to the HTML documents.  Default is ``True``.
+
+   .. versionadded:: 0.4
+
+.. confval:: html_split_index
+
+   If true, the index is generated twice: once as a single page with all the
+   entries, and once as one page per starting letter.  Default is ``False``.
+
+   .. versionadded:: 0.4
+
+.. confval:: html_copy_source
+
+   If true, the reST sources are included in the HTML build as
+   :file:`_sources/{name}`.  The default is ``True``.
+
+.. confval:: html_show_sourcelink
+
+   If true (and :confval:`html_copy_source` is true as well), links to the
+   reST sources will be added to the sidebar.  The default is ``True``.
+
+   .. versionadded:: 0.6
+
+.. confval:: html_sourcelink_suffix
+
+   Suffix to be appended to source links (see :confval:`html_show_sourcelink`),
+   unless they have this suffix already.  Default is ``'.txt'``.
+
+   .. versionadded:: 1.5
+
+.. confval:: html_use_opensearch
+
+   If nonempty, an `OpenSearch <https://github.com/dewitt/opensearch>`_
+   description file will be output, and all pages will contain a ``<link>``
+   tag referring to it.  Since OpenSearch doesn't support relative URLs for
+   its search page location, the value of this option must be the base URL
+   from which these documents are served (without trailing slash), e.g.
+   ``"https://docs.python.org"``.  The default is ``''``.
+
+.. confval:: html_file_suffix
+
+   This is the file name suffix for generated HTML files, if set to a :obj:`str`
+   value.  If left to the default ``None``, the suffix will be ``".html"``.
+
+   .. versionadded:: 0.4
+
+.. confval:: html_link_suffix
+
+   Suffix for generated links to HTML files.  The default is whatever
+   :confval:`html_file_suffix` is set to; it can be set differently (e.g. to
+   support different web server setups).
+
+   .. versionadded:: 0.6
+
+.. confval:: html_show_copyright
+
+   If true, "(C) Copyright ..." is shown in the HTML footer. Default is
+   ``True``.
+
+   .. versionadded:: 1.0
+
+.. confval:: html_show_search_summary
+
+   If true, the text around the keyword is shown as summary of each search result.
+   Default is ``True``.
+
+   .. versionadded:: 4.5
+
+.. confval:: html_show_sphinx
+
+   If true, "Created using Sphinx" is shown in the HTML footer.  Default is
+   ``True``.
+
+   .. versionadded:: 0.4
+
+.. confval:: html_output_encoding
+
+   Encoding of HTML output files. Default is ``'utf-8'``.  Note that this
+   encoding name must both be a valid Python encoding name and a valid HTML
+   ``charset`` value.
+
+   .. versionadded:: 1.0
+
+.. confval:: html_compact_lists
+
+   If true, a list all whose items consist of a single paragraph and/or a
+   sub-list all whose items etc... (recursive definition) will not use the
+   ``<p>`` element for any of its items. This is standard docutils behavior.
+   Default: ``True``.
+
+   .. versionadded:: 1.0
+
+.. confval:: html_secnumber_suffix
+
+   Suffix for section numbers.  Default: ``". "``.  Set to ``" "`` to suppress
+   the final dot on section numbers.
+
+   .. versionadded:: 1.0
+
+.. confval:: html_search_language
+
+   Language to be used for generating the HTML full-text search index.  This
+   defaults to the global language selected with :confval:`language`.  If there
+   is no support for this language, ``"en"`` is used which selects the English
+   language.
+
+   Support is present for these languages:
+
+   * ``da`` -- Danish
+   * ``nl`` -- Dutch
+   * ``en`` -- English
+   * ``fi`` -- Finnish
+   * ``fr`` -- French
+   * ``de`` -- German
+   * ``hu`` -- Hungarian
+   * ``it`` -- Italian
+   * ``ja`` -- Japanese
+   * ``no`` -- Norwegian
+   * ``pt`` -- Portuguese
+   * ``ro`` -- Romanian
+   * ``ru`` -- Russian
+   * ``es`` -- Spanish
+   * ``sv`` -- Swedish
+   * ``tr`` -- Turkish
+   * ``zh`` -- Chinese
+
+   .. admonition:: Accelerating build speed
+
+      Each language (except Japanese) provides its own stemming algorithm.
+      Sphinx uses a Python implementation by default.  You can use a C
+      implementation to accelerate building the index file.
+
+      * `PorterStemmer <https://pypi.org/project/PorterStemmer/>`_ (``en``)
+      * `PyStemmer <https://pypi.org/project/PyStemmer/>`_ (all languages)
+
+   .. versionadded:: 1.1
+      With support for ``en`` and ``ja``.
+
+   .. versionchanged:: 1.3
+      Added additional languages.
+
+.. confval:: html_search_options
+
+   A dictionary with options for the search language support, empty by default.
+   The meaning of these options depends on the language selected.
+
+   The English support has no options.
+
+   The Japanese support has these options:
+
+   :type:
+      _`type` is dotted module path string to specify Splitter implementation
+      which should be derived from :class:`!sphinx.search.ja.BaseSplitter`.  If
+      not specified or ``None`` is specified,
+      ``'sphinx.search.ja.DefaultSplitter'`` will be used.
+
+      You can choose from these modules:
+
+      :'sphinx.search.ja.DefaultSplitter':
+         TinySegmenter algorithm. This is default splitter.
+      :'sphinx.search.ja.MecabSplitter':
+         MeCab binding. To use this splitter, 'mecab' python binding or dynamic
+         link library ('libmecab.so' for linux, 'libmecab.dll' for windows) is
+         required.
+      :'sphinx.search.ja.JanomeSplitter':
+         Janome binding. To use this splitter,
+         `Janome <https://pypi.org/project/Janome/>`_ is required.
+
+      .. deprecated:: 1.6
+         ``'mecab'``, ``'janome'`` and ``'default'`` is deprecated.
+         To keep compatibility, ``'mecab'``, ``'janome'`` and ``'default'`` are
+         also acceptable.
+
+   Other option values depend on splitter value which you choose.
+
+   Options for ``'mecab'``:
+      :dic_enc:
+         _`dic_enc option` is the encoding for the MeCab algorithm.
+      :dict:
+         _`dict option` is the dictionary to use for the MeCab algorithm.
+      :lib:
+         _`lib option` is the library name for finding the MeCab library via
+         ctypes if the Python binding is not installed.
+
+      For example::
+
+          html_search_options = {
+              'type': 'mecab',
+              'dic_enc': 'utf-8',
+              'dict': '/path/to/mecab.dic',
+              'lib': '/path/to/libmecab.so',
+          }
+
+   Options for ``'janome'``:
+      :user_dic:
+         _`user_dic option` is the user dictionary file path for Janome.
+      :user_dic_enc:
+         _`user_dic_enc option` is the encoding for the user dictionary file
+         specified by ``user_dic`` option. Default is 'utf8'.
+
+   .. versionadded:: 1.1
+
+   .. versionchanged:: 1.4
+      html_search_options for Japanese is re-organized and any custom splitter
+      can be used by `type`_ settings.
+
+   The Chinese support has these options:
+
+   * ``dict``  -- the ``jieba`` dictionary path if want to use
+     custom dictionary.
+
+.. confval:: html_search_scorer
+
+   The name of a JavaScript file (relative to the configuration directory) that
+   implements a search results scorer.  If empty, the default will be used.
+
+   .. XXX describe interface for scorer here
+
+   .. versionadded:: 1.2
+
+.. confval:: html_scaled_image_link
+
+   If true, image itself links to the original image if it doesn't have
+   'target' option or scale related options: 'scale', 'width', 'height'.
+   The default is ``True``.
+
+   Document authors can disable this feature manually with giving
+   ``no-scaled-link`` class to the image:
+
+   .. code-block:: rst
+
+      .. image:: sphinx.png
+         :scale: 50%
+         :class: no-scaled-link
+
+   .. versionadded:: 1.3
+
+   .. versionchanged:: 3.0
+
+      It is disabled for images having ``no-scaled-link`` class
+
+.. confval:: html_math_renderer
+
+   The name of math_renderer extension for HTML output.  The default is
+   ``'mathjax'``.
+
+   .. versionadded:: 1.8
+
+.. confval:: html_experimental_html5_writer
+
+   Output is processed with HTML5 writer.  Default is ``False``.
+
+   .. versionadded:: 1.6
+
+   .. deprecated:: 2.0
+
+.. confval:: html4_writer
+
+   Output is processed with HTML4 writer.  Default is ``False``.
+
+Options for Single HTML output
+-------------------------------
+
+.. confval:: singlehtml_sidebars
+
+   Custom sidebar templates, must be a dictionary that maps document names to
+   template names.  And it only allows a key named `'index'`.  All other keys
+   are ignored.  For more information, refer to :confval:`html_sidebars`.  By
+   default, it is same as :confval:`html_sidebars`.
+
+
+.. _htmlhelp-options:
+
+Options for HTML help output
+-----------------------------
+
+.. confval:: htmlhelp_basename
+
+   Output file base name for HTML help builder.  Default is ``'pydoc'``.
+
+.. confval:: htmlhelp_file_suffix
+
+   This is the file name suffix for generated HTML help files.  The
+   default is ``".html"``.
+
+   .. versionadded:: 2.0
+
+.. confval:: htmlhelp_link_suffix
+
+   Suffix for generated links to HTML files.  The default is ``".html"``.
+
+   .. versionadded:: 2.0
+
+
+.. _applehelp-options:
+
+Options for Apple Help output
+-----------------------------
+
+.. versionadded:: 1.3
+
+These options influence the Apple Help output.  This builder derives from the
+HTML builder, so the HTML options also apply where appropriate.
+
+.. note::
+
+   Apple Help output will only work on Mac OS X 10.6 and higher, as it
+   requires the :program:`hiutil` and :program:`codesign` command line tools,
+   neither of which are Open Source.
+
+   You can disable the use of these tools using
+   :confval:`applehelp_disable_external_tools`, but the result will not be a
+   valid help book until the indexer is run over the ``.lproj`` folders within
+   the bundle.
+
+.. confval:: applehelp_bundle_name
+
+   The basename for the Apple Help Book.  Defaults to the :confval:`project`
+   name.
+
+.. confval:: applehelp_bundle_id
+
+   The bundle ID for the help book bundle.
+
+   .. warning::
+
+      You *must* set this value in order to generate Apple Help.
+
+.. confval:: applehelp_dev_region
+
+   The development region.  Defaults to ``'en-us'``, which is Apple’s
+   recommended setting.
+
+.. confval:: applehelp_bundle_version
+
+   The bundle version (as a string).  Defaults to ``'1'``.
+
+.. confval:: applehelp_icon
+
+   The help bundle icon file, or ``None`` for no icon.  According to Apple's
+   documentation, this should be a 16-by-16 pixel version of the application's
+   icon with a transparent background, saved as a PNG file.
+
+.. confval:: applehelp_kb_product
+
+   The product tag for use with :confval:`applehelp_kb_url`.  Defaults to
+   :samp:`'{<project>}-{<release>}'`.
+
+.. confval:: applehelp_kb_url
+
+   The URL for your knowledgebase server,
+   e.g. ``https://example.com/kbsearch.py?p='product'&q='query'&l='lang'``.
+   Help Viewer will replace the values ``'product'``, ``'query'`` and
+   ``'lang'`` at runtime with the contents of :confval:`applehelp_kb_product`,
+   the text entered by the user in the search box and the user's system
+   language respectively.
+
+   Defaults to ``None`` for no remote search.
+
+.. confval:: applehelp_remote_url
+
+   The URL for remote content.  You can place a copy of your Help Book's
+   ``Resources`` folder at this location and Help Viewer will attempt to use
+   it to fetch updated content.
+
+   e.g. if you set it to ``https://example.com/help/Foo/`` and Help Viewer
+   wants a copy of ``index.html`` for an English speaking customer, it will
+   look at ``https://example.com/help/Foo/en.lproj/index.html``.
+
+   Defaults to ``None`` for no remote content.
+
+.. confval:: applehelp_index_anchors
+
+   If ``True``, tell the help indexer to index anchors in the generated HTML.
+   This can be useful for jumping to a particular topic using the
+   ``AHLookupAnchor`` function or the ``openHelpAnchor:inBook:`` method in
+   your code.  It also allows you to use ``help:anchor`` URLs; see the Apple
+   documentation for more information on this topic.
+
+.. confval:: applehelp_min_term_length
+
+   Controls the minimum term length for the help indexer.  Defaults to
+   ``None``, which means the default will be used.
+
+.. confval:: applehelp_stopwords
+
+   Either a language specification (to use the built-in stopwords), or the
+   path to a stopwords plist, or ``None`` if you do not want to use stopwords.
+   The default stopwords plist can be found at
+   ``/usr/share/hiutil/Stopwords.plist`` and contains, at time of writing,
+   stopwords for the following languages:
+
+   =========  ====
+   Language   Code
+   =========  ====
+   English    en
+   German     de
+   Spanish    es
+   French     fr
+   Swedish    sv
+   Hungarian  hu
+   Italian    it
+   =========  ====
+
+   Defaults to :confval:`language`, or if that is not set, to ``'en'``.
+
+.. confval:: applehelp_locale
+
+   Specifies the locale to generate help for.  This is used to determine
+   the name of the ``.lproj`` folder inside the Help Book’s ``Resources``, and
+   is passed to the help indexer.
+
+   Defaults to :confval:`language`, or if that is not set, to ``'en'``.
+
+.. confval:: applehelp_title
+
+   Specifies the help book title.  Defaults to :samp:`'{<project>} Help'`.
+
+.. confval:: applehelp_codesign_identity
+
+   Specifies the identity to use for code signing, or ``None`` if code signing
+   is not to be performed.
+
+   Defaults to the value of the environment variable ``CODE_SIGN_IDENTITY``,
+   which is set by Xcode for script build phases, or ``None`` if that variable
+   is not set.
+
+.. confval:: applehelp_codesign_flags
+
+   A *list* of additional arguments to pass to :program:`codesign` when
+   signing the help book.
+
+   Defaults to a list based on the value of the environment variable
+   ``OTHER_CODE_SIGN_FLAGS``, which is set by Xcode for script build phases,
+   or the empty list if that variable is not set.
+
+.. confval:: applehelp_indexer_path
+
+   The path to the :program:`hiutil` program.  Defaults to
+   ``'/usr/bin/hiutil'``.
+
+.. confval:: applehelp_codesign_path
+
+   The path to the :program:`codesign` program.  Defaults to
+   ``'/usr/bin/codesign'``.
+
+.. confval:: applehelp_disable_external_tools
+
+   If ``True``, the builder will not run the indexer or the code signing tool,
+   no matter what other settings are specified.
+
+   This is mainly useful for testing, or where you want to run the Sphinx
+   build on a non-Mac OS X platform and then complete the final steps on OS X
+   for some reason.
+
+   Defaults to ``False``.
+
+
+.. _epub-options:
+
+Options for epub output
+-----------------------
+
+These options influence the epub output.  As this builder derives from the HTML
+builder, the HTML options also apply where appropriate.  The actual values for
+some of the options is not really important, they just have to be entered into
+the `Dublin Core metadata <https://dublincore.org/>`_.
+
+.. confval:: epub_basename
+
+   The basename for the epub file.  It defaults to the :confval:`project` name.
+
+.. confval:: epub_theme
+
+   The HTML theme for the epub output.  Since the default themes are not
+   optimized for small screen space, using the same theme for HTML and epub
+   output is usually not wise.  This defaults to ``'epub'``, a theme designed
+   to save visual space.
+
+.. confval:: epub_theme_options
+
+   A dictionary of options that influence the look and feel of the selected
+   theme.  These are theme-specific.  For the options understood by the builtin
+   themes, see :ref:`this section <builtin-themes>`.
+
+   .. versionadded:: 1.2
+
+.. confval:: epub_title
+
+   The title of the document.  It defaults to the :confval:`html_title` option
+   but can be set independently for epub creation.  It defaults to the
+   :confval:`project` option.
+
+   .. versionchanged:: 2.0
+      It defaults to the ``project`` option.
+
+.. confval:: epub_description
+
+   The description of the document. The default value is ``'unknown'``.
+
+   .. versionadded:: 1.4
+
+   .. versionchanged:: 1.5
+      Renamed from ``epub3_description``
+
+.. confval:: epub_author
+
+   The author of the document.  This is put in the Dublin Core metadata.  It
+   defaults to the :confval:`author` option.
+
+.. confval:: epub_contributor
+
+   The name of a person, organization, etc. that played a secondary role in
+   the creation of the content of an EPUB Publication. The default value is
+   ``'unknown'``.
+
+   .. versionadded:: 1.4
+
+   .. versionchanged:: 1.5
+      Renamed from ``epub3_contributor``
+
+.. confval:: epub_language
+
+   The language of the document.  This is put in the Dublin Core metadata.  The
+   default is the :confval:`language` option or ``'en'`` if unset.
+
+.. confval:: epub_publisher
+
+   The publisher of the document.  This is put in the Dublin Core metadata.
+   You may use any sensible string, e.g. the project homepage.  The defaults to
+   the :confval:`author` option.
+
+.. confval:: epub_copyright
+
+   The copyright of the document.  It defaults to the :confval:`copyright`
+   option but can be set independently for epub creation.
+
+.. confval:: epub_identifier
+
+   An identifier for the document.  This is put in the Dublin Core metadata.
+   For published documents this is the ISBN number, but you can also use an
+   alternative scheme, e.g. the project homepage.  The default value is
+   ``'unknown'``.
+
+.. confval:: epub_scheme
+
+   The publication scheme for the :confval:`epub_identifier`.  This is put in
+   the Dublin Core metadata.  For published books the scheme is ``'ISBN'``.  If
+   you use the project homepage, ``'URL'`` seems reasonable.  The default value
+   is ``'unknown'``.
+
+.. confval:: epub_uid
+
+   A unique identifier for the document.  This is put in the Dublin Core
+   metadata.  You may use a
+   `XML's Name format <https://www.w3.org/TR/REC-xml/#NT-NameStartChar>`_
+   string.  You can't use hyphen, period, numbers as a first character.  The
+   default value is ``'unknown'``.
+
+.. confval:: epub_cover
+
+   The cover page information.  This is a tuple containing the filenames of
+   the cover image and the html template.  The rendered html cover page is
+   inserted as the first item in the spine in :file:`content.opf`.  If the
+   template filename is empty, no html cover page is created.  No cover at all
+   is created if the tuple is empty.  Examples::
+
+      epub_cover = ('_static/cover.png', 'epub-cover.html')
+      epub_cover = ('_static/cover.png', '')
+      epub_cover = ()
+
+   The default value is ``()``.
+
+   .. versionadded:: 1.1
+
+.. confval:: epub_css_files
+
+   A list of CSS files.  The entry must be a *filename* string or a tuple
+   containing the *filename* string and the *attributes* dictionary.  For more
+   information, see :confval:`html_css_files`.
+
+   .. versionadded:: 1.8
+
+.. confval:: epub_guide
+
+   Meta data for the guide element of :file:`content.opf`. This is a
+   sequence of tuples containing the *type*, the *uri* and the *title* of
+   the optional guide information. See the OPF documentation
+   at `<http://idpf.org/epub>`_ for details. If possible, default entries
+   for the *cover* and *toc* types are automatically inserted. However,
+   the types can be explicitly overwritten if the default entries are not
+   appropriate. Example::
+
+      epub_guide = (('cover', 'cover.html', 'Cover Page'),)
+
+   The default value is ``()``.
+
+.. confval:: epub_pre_files
+
+   Additional files that should be inserted before the text generated by
+   Sphinx. It is a list of tuples containing the file name and the title.
+   If the title is empty, no entry is added to :file:`toc.ncx`.  Example::
+
+      epub_pre_files = [
+          ('index.html', 'Welcome'),
+      ]
+
+   The default value is ``[]``.
+
+.. confval:: epub_post_files
+
+   Additional files that should be inserted after the text generated by Sphinx.
+   It is a list of tuples containing the file name and the title.  This option
+   can be used to add an appendix.  If the title is empty, no entry is added
+   to :file:`toc.ncx`.  The default value is ``[]``.
+
+.. confval:: epub_exclude_files
+
+   A list of files that are generated/copied in the build directory but should
+   not be included in the epub file.  The default value is ``[]``.
+
+.. confval:: epub_tocdepth
+
+   The depth of the table of contents in the file :file:`toc.ncx`.  It should
+   be an integer greater than zero.  The default value is 3.  Note: A deeply
+   nested table of contents may be difficult to navigate.
+
+.. confval:: epub_tocdup
+
+   This flag determines if a toc entry is inserted again at the beginning of
+   its nested toc listing.  This allows easier navigation to the top of
+   a chapter, but can be confusing because it mixes entries of different
+   depth in one list.  The default value is ``True``.
+
+.. confval:: epub_tocscope
+
+   This setting control the scope of the epub table of contents.  The setting
+   can have the following values:
+
+   * ``'default'`` -- include all toc entries that are not hidden (default)
+   * ``'includehidden'`` -- include all toc entries
+
+   .. versionadded:: 1.2
+
+.. confval:: epub_fix_images
+
+   This flag determines if sphinx should try to fix image formats that are not
+   supported by some epub readers.  At the moment palette images with a small
+   color table are upgraded.  You need Pillow, the Python Image Library,
+   installed to use this option.  The default value is ``False`` because the
+   automatic conversion may lose information.
+
+   .. versionadded:: 1.2
+
+.. confval:: epub_max_image_width
+
+   This option specifies the maximum width of images.  If it is set to a value
+   greater than zero, images with a width larger than the given value are
+   scaled accordingly.  If it is zero, no scaling is performed. The default
+   value is ``0``.  You need the Python Image Library (Pillow) installed to use
+   this option.
+
+   .. versionadded:: 1.2
+
+.. confval:: epub_show_urls
+
+   Control whether to display URL addresses. This is very useful for
+   readers that have no other means to display the linked URL. The
+   settings can have the following values:
+
+   * ``'inline'`` -- display URLs inline in parentheses (default)
+   * ``'footnote'`` -- display URLs in footnotes
+   * ``'no'`` -- do not display URLs
+
+   The display of inline URLs can be customized by adding CSS rules for the
+   class ``link-target``.
+
+   .. versionadded:: 1.2
+
+.. confval:: epub_use_index
+
+   If true, add an index to the epub document.  It defaults to the
+   :confval:`html_use_index` option but can be set independently for epub
+   creation.
+
+   .. versionadded:: 1.2
+
+.. confval:: epub_writing_mode
+
+   It specifies writing direction. It can accept ``'horizontal'`` (default) and
+   ``'vertical'``
+
+   .. list-table::
+      :header-rows: 1
+      :stub-columns: 1
+
+      - * ``epub_writing_mode``
+        * ``'horizontal'``
+        * ``'vertical'``
+      - * writing-mode [#]_
+        * ``horizontal-tb``
+        * ``vertical-rl``
+      - * page progression
+        * left to right
+        * right to left
+      - * iBook's Scroll Theme support
+        * scroll-axis is vertical.
+        * scroll-axis is horizontal.
+
+   .. [#] https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode
+
+
+.. _latex-options:
+
+Options for LaTeX output
+------------------------
+
+These options influence LaTeX output.
+
+.. confval:: latex_engine
+
+   The LaTeX engine to build the docs.  The setting can have the following
+   values:
+
+   * ``'pdflatex'`` -- PDFLaTeX (default)
+   * ``'xelatex'`` -- XeLaTeX
+   * ``'lualatex'`` -- LuaLaTeX
+   * ``'platex'`` -- pLaTeX
+   * ``'uplatex'`` -- upLaTeX (default if :confval:`language` is ``'ja'``)
+
+   ``'pdflatex'``\ 's support for Unicode characters is limited.
+
+   .. note::
+
+      2.0 adds to ``'pdflatex'`` support in Latin language document of
+      occasional Cyrillic or Greek letters or words.  This is not automatic,
+      see the discussion of the :confval:`latex_elements` ``'fontenc'`` key.
+
+   If your project uses Unicode characters, setting the engine to
+   ``'xelatex'`` or ``'lualatex'`` and making sure to use an OpenType font
+   with wide-enough glyph coverage is often easier than trying to make
+   ``'pdflatex'`` work with the extra Unicode characters.  Since Sphinx 2.0
+   the default is the GNU FreeFont which covers well Latin, Cyrillic and
+   Greek.
+
+   .. versionchanged:: 2.1.0
+
+      Use ``xelatex`` (and LaTeX package ``xeCJK``) by default for Chinese
+      documents.
+
+   .. versionchanged:: 2.2.1
+
+      Use ``xelatex`` by default for Greek documents.
+
+   .. versionchanged:: 2.3
+
+      Add ``uplatex`` support.
+
+   .. versionchanged:: 4.0
+
+      ``uplatex`` becomes the default setting of Japanese documents.
+
+   Contrarily to :ref:`MathJaX math rendering in HTML output <math-support>`,
+   LaTeX requires some extra configuration to support Unicode literals in
+   :rst:dir:`math`: the only comprehensive solution (as far as we know) is to
+   use ``'xelatex'`` or ``'lualatex'`` *and* to add
+   ``r'\usepackage{unicode-math}'`` (e.g. via the :confval:`latex_elements`
+   ``'preamble'`` key).  You may prefer
+   ``r'\usepackage[math-style=literal]{unicode-math}'`` to keep a Unicode
+   literal such as ``α`` (U+03B1) for example as is in output, rather than
+   being rendered as :math:`\alpha`.
+
+.. confval:: latex_documents
+
+   This value determines how to group the document tree into LaTeX source files.
+   It must be a list of tuples ``(startdocname, targetname, title, author,
+   theme, toctree_only)``, where the items are:
+
+   *startdocname*
+     String that specifies the :term:`document name` of the LaTeX file's master
+     document.  All documents referenced by the *startdoc* document in TOC trees
+     will be included in the LaTeX file.  (If you want to use the default root
+     document for your LaTeX build, provide your :confval:`root_doc` here.)
+
+   *targetname*
+     File name of the LaTeX file in the output directory.
+
+   *title*
+     LaTeX document title.  Can be empty to use the title of the *startdoc*
+     document.  This is inserted as LaTeX markup, so special characters like a
+     backslash or ampersand must be represented by the proper LaTeX commands if
+     they are to be inserted literally.
+
+   *author*
+     Author for the LaTeX document.  The same LaTeX markup caveat as for *title*
+     applies.  Use ``\\and`` to separate multiple authors, as in:
+     ``'John \\and Sarah'`` (backslashes must be Python-escaped to reach LaTeX).
+
+   *theme*
+     LaTeX theme.  See :confval:`latex_theme`.
+
+   *toctree_only*
+     Must be ``True`` or ``False``.  If true, the *startdoc* document itself is
+     not included in the output, only the documents referenced by it via TOC
+     trees.  With this option, you can put extra stuff in the master document
+     that shows up in the HTML, but not the LaTeX output.
+
+   .. versionadded:: 1.2
+      In the past including your own document class required you to prepend the
+      document class name with the string "sphinx". This is not necessary
+      anymore.
+
+   .. versionadded:: 0.3
+      The 6th item ``toctree_only``.  Tuples with 5 items are still accepted.
+
+.. confval:: latex_logo
+
+   If given, this must be the name of an image file (relative to the
+   configuration directory) that is the logo of the docs.  It is placed at the
+   top of the title page.  Default: ``None``.
+
+.. confval:: latex_toplevel_sectioning
+
+   This value determines the topmost sectioning unit. It should be chosen from
+   ``'part'``, ``'chapter'`` or ``'section'``. The default is ``None``;
+   the topmost
+   sectioning unit is switched by documentclass: ``section`` is used if
+   documentclass will be ``howto``, otherwise ``chapter`` will be used.
+
+   Note that if LaTeX uses ``\part`` command, then the numbering of sectioning
+   units one level deep gets off-sync with HTML numbering, because LaTeX
+   numbers continuously ``\chapter`` (or ``\section`` for ``howto``.)
+
+   .. versionadded:: 1.4
+
+.. confval:: latex_appendices
+
+   A list of document names to append as an appendix to all manuals.
+
+.. confval:: latex_domain_indices
+
+   If true, generate domain-specific indices in addition to the general index.
+   For e.g. the Python domain, this is the global module index.  Default is
+   ``True``.
+
+   This value can be a bool or a list of index names that should be generated,
+   like for :confval:`html_domain_indices`.
+
+   .. versionadded:: 1.0
+
+.. confval:: latex_show_pagerefs
+
+   If true, add page references after internal references.  This is very useful
+   for printed copies of the manual.  Default is ``False``.
+
+   .. versionadded:: 1.0
+
+.. confval:: latex_show_urls
+
+   Control whether to display URL addresses.  This is very useful for printed
+   copies of the manual.  The setting can have the following values:
+
+   * ``'no'`` -- do not display URLs (default)
+   * ``'footnote'`` -- display URLs in footnotes
+   * ``'inline'`` -- display URLs inline in parentheses
+
+   .. versionadded:: 1.0
+   .. versionchanged:: 1.1
+      This value is now a string; previously it was a boolean value, and a true
+      value selected the ``'inline'`` display.  For backwards compatibility,
+      ``True`` is still accepted.
+
+.. confval:: latex_use_latex_multicolumn
+
+   The default is ``False``: it means that Sphinx's own macros are used for
+   merged cells from grid tables. They allow general contents (literal blocks,
+   lists, blockquotes, ...) but may have problems if the
+   :rst:dir:`tabularcolumns` directive was used to inject LaTeX mark-up of the
+   type ``>{..}``, ``<{..}``, ``@{..}`` as column specification.
+
+   Setting to ``True`` means to use LaTeX's standard ``\multicolumn``; this is
+   incompatible with literal blocks in the horizontally merged cell, and also
+   with multiple paragraphs in such cell if the table is rendered using
+   ``tabulary``.
+
+   .. versionadded:: 1.6
+
+.. confval:: latex_table_style
+
+   A list of styling classes (strings).  Currently supported:
+
+   - ``'booktabs'``: no vertical lines, and only 2 or 3 horizontal lines (the
+     latter if there is a header), using the booktabs_ package.
+
+   - ``'borderless'``: no lines whatsoever.
+
+   - ``'colorrows'``: the table rows are rendered with alternating background
+     colours.  The interface to customize them is via :ref:`dedicated keys
+     <tablecolors>` of :ref:`latexsphinxsetup`.
+
+     .. important::
+
+        With the ``'colorrows'`` style, the ``\rowcolors`` LaTeX command
+        becomes a no-op (this command has limitations and has never correctly
+        supported all types of tables Sphinx produces in LaTeX).  Please
+        update your project to use instead
+        the :ref:`latex table color configuration <tablecolors>` keys.
+
+   Default: ``['booktabs', 'colorrows']``
+
+   .. versionadded:: 5.3.0
+
+   .. versionchanged:: 6.0.0
+
+      Modify default from ``[]`` to ``['booktabs', 'colorrows']``.
+
+   Each table can override the global style via ``:class:`` option, or
+   ``.. rst-class::`` for no-directive tables (cf.  :ref:`table-directives`).
+   Currently recognized classes are ``booktabs``, ``borderless``,
+   ``standard``, ``colorrows``, ``nocolorrows``.  The latter two can be
+   combined with any of the first three.  The ``standard`` class produces
+   tables with both horizontal and vertical lines (as has been the default so
+   far with Sphinx).
+
+   A single-row multi-column merged cell will obey the row colour, if it is
+   set.  See also ``TableMergeColor{Header,Odd,Even}`` in the
+   :ref:`latexsphinxsetup` section.
+
+   .. note::
+
+      - It is hard-coded in LaTeX that a single cell will obey the row colour
+        even if there is a column colour set via ``\columncolor`` from a
+        column specification (see :rst:dir:`tabularcolumns`).  Sphinx provides
+        ``\sphinxnorowcolor`` which can be used like this:
+
+        .. code-block:: latex
+
+           >{\columncolor{blue}\sphinxnorowcolor}
+
+        in a table column specification.
+
+      - Sphinx also provides ``\sphinxcolorblend`` which however requires the
+        xcolor_ package.  Here is an example:
+
+        .. code-block:: latex
+
+           >{\sphinxcolorblend{!95!red}}
+
+        It means that in this column, the row colours will be slightly tinted
+        by red; refer to xcolor_ documentation for more on the syntax of its
+        ``\blendcolors`` command (a ``\blendcolors`` in place of
+        ``\sphinxcolorblend`` would modify colours of the cell *contents*, not
+        of the cell *background colour panel*...).  You can find an example of
+        usage in the :ref:`dev-deprecated-apis` section of this document in
+        PDF format.
+
+        .. hint::
+
+           If you want to use a special colour for the *contents* of the
+           cells of a given column use ``>{\noindent\color{<color>}}``,
+           possibly in addition to the above.
+
+      - Multi-row merged cells, whether single column or multi-column
+        currently ignore any set column, row, or cell colour.
+
+      - It is possible for a simple cell to set a custom colour via the
+        :dudir:`raw` directive and the ``\cellcolor`` LaTeX command used
+        anywhere in the cell contents.  This currently is without effect
+        in a merged cell, whatever its kind.
+
+   .. hint::
+
+      In a document not using ``'booktabs'`` globally, it is possible to style
+      an individual table via the ``booktabs`` class, but it will be necessary
+      to add ``r'\usepackage{booktabs}'`` to the LaTeX preamble.
+
+      On the other hand one can use ``colorrows`` class for individual tables
+      with no extra package (as Sphinx since 5.3.0 always loads colortbl_).
+
+   .. _booktabs: https://ctan.org/pkg/booktabs
+   .. _colortbl: https://ctan.org/pkg/colortbl
+   .. _xcolor: https://ctan.org/pkg/xcolor
+
+.. confval:: latex_use_xindy
+
+   If ``True``, the PDF build from the LaTeX files created by Sphinx
+   will use :program:`xindy` (doc__) rather than :program:`makeindex`
+   for preparing the index of general terms (from :rst:dir:`index`
+   usage).  This means that words with UTF-8 characters will get
+   ordered correctly for the :confval:`language`.
+
+   __ http://xindy.sourceforge.net/
+
+   - This option is ignored if :confval:`latex_engine` is ``'platex'``
+     (Japanese documents; :program:`mendex` replaces :program:`makeindex`
+     then).
+
+   - The default is ``True`` for ``'xelatex'`` or ``'lualatex'`` as
+     :program:`makeindex`, if any indexed term starts with a non-ascii
+     character, creates ``.ind`` files containing invalid bytes for
+     UTF-8 encoding. With ``'lualatex'`` this then breaks the PDF
+     build.
+
+   - The default is ``False`` for ``'pdflatex'`` but ``True`` is
+     recommended for non-English documents as soon as some indexed
+     terms use non-ascii characters from the language script.
+
+   Sphinx adds to :program:`xindy` base distribution some dedicated support
+   for using ``'pdflatex'`` engine with Cyrillic scripts.  And whether with
+   ``'pdflatex'`` or Unicode engines, Cyrillic documents handle correctly the
+   indexing of Latin names, even with diacritics.
+
+   .. versionadded:: 1.8
+
+.. confval:: latex_elements
+
+   .. versionadded:: 0.5
+
+   Its :ref:`documentation <latex_elements_confval>` has moved to :doc:`/latex`.
+
+.. confval:: latex_docclass
+
+   A dictionary mapping ``'howto'`` and ``'manual'`` to names of real document
+   classes that will be used as the base for the two Sphinx classes.  Default
+   is to use ``'article'`` for ``'howto'`` and ``'report'`` for ``'manual'``.
+
+   .. versionadded:: 1.0
+
+   .. versionchanged:: 1.5
+
+      In Japanese docs (:confval:`language` is ``'ja'``), by default
+      ``'jreport'`` is used for ``'howto'`` and ``'jsbook'`` for ``'manual'``.
+
+.. confval:: latex_additional_files
+
+   A list of file names, relative to the configuration directory, to copy to
+   the build directory when building LaTeX output.  This is useful to copy
+   files that Sphinx doesn't copy automatically, e.g. if they are referenced in
+   custom LaTeX added in ``latex_elements``.  Image files that are referenced
+   in source files (e.g. via ``.. image::``) are copied automatically.
+
+   You have to make sure yourself that the filenames don't collide with those
+   of any automatically copied files.
+
+   .. attention::
+
+      Filenames with extension ``.tex`` will automatically be handed over to
+      the PDF build process triggered by :option:`sphinx-build -M`
+      ``latexpdf`` or by :program:`make latexpdf`.  If the file was added only
+      to be ``\input{}`` from a modified preamble, you must add a further
+      suffix such as ``.txt`` to the filename and adjust accordingly the
+      ``\input{}`` command added to the LaTeX document preamble.
+
+   .. versionadded:: 0.6
+
+   .. versionchanged:: 1.2
+      This overrides the files which is provided from Sphinx such as
+      ``sphinx.sty``.
+
+.. confval:: latex_theme
+
+   The "theme" that the LaTeX output should use.  It is a collection of settings
+   for LaTeX output (ex. document class, top level sectioning unit and so on).
+
+   As a built-in LaTeX themes, ``manual`` and ``howto`` are bundled.
+
+   ``manual``
+     A LaTeX theme for writing a manual.  It imports the ``report`` document
+     class (Japanese documents use ``jsbook``).
+
+   ``howto``
+     A LaTeX theme for writing an article.  It imports the ``article`` document
+     class (Japanese documents use ``jreport`` rather).  :confval:`latex_appendices`
+     is available only for this theme.
+
+   It defaults to ``'manual'``.
+
+   .. versionadded:: 3.0
+
+.. confval:: latex_theme_options
+
+   A dictionary of options that influence the look and feel of the selected
+   theme.
+
+   .. versionadded:: 3.1
+
+.. confval:: latex_theme_path
+
+   A list of paths that contain custom LaTeX themes as subdirectories.  Relative
+   paths are taken as relative to the configuration directory.
+
+   .. versionadded:: 3.0
+
+
+.. _text-options:
+
+Options for text output
+-----------------------
+
+These options influence text output.
+
+.. confval:: text_newlines
+
+   Determines which end-of-line character(s) are used in text output.
+
+   * ``'unix'``: use Unix-style line endings (``\n``)
+   * ``'windows'``: use Windows-style line endings (``\r\n``)
+   * ``'native'``: use the line ending style of the platform the documentation
+     is built on
+
+   Default: ``'unix'``.
+
+   .. versionadded:: 1.1
+
+.. confval:: text_sectionchars
+
+   A string of 7 characters that should be used for underlining sections.
+   The first character is used for first-level headings, the second for
+   second-level headings and so on.
+
+   The default is ``'*=-~"+`'``.
+
+   .. versionadded:: 1.1
+
+.. confval:: text_add_secnumbers
+
+   A boolean that decides whether section numbers are included in text output.
+   Default is ``True``.
+
+   .. versionadded:: 1.7
+
+.. confval:: text_secnumber_suffix
+
+   Suffix for section numbers in text output.  Default: ``". "``. Set to
+   ``" "`` to suppress the final dot on section numbers.
+
+   .. versionadded:: 1.7
+
+
+.. _man-options:
+
+Options for manual page output
+------------------------------
+
+These options influence manual page output.
+
+.. confval:: man_pages
+
+   This value determines how to group the document tree into manual pages.  It
+   must be a list of tuples ``(startdocname, name, description, authors,
+   section)``, where the items are:
+
+   *startdocname*
+     String that specifies the :term:`document name` of the manual page's master
+     document. All documents referenced by the *startdoc* document in TOC trees
+     will be included in the manual file.  (If you want to use the default
+     root document for your manual pages build, use your :confval:`root_doc`
+     here.)
+
+   *name*
+     Name of the manual page.  This should be a short string without spaces or
+     special characters.  It is used to determine the file name as well as the
+     name of the manual page (in the NAME section).
+
+   *description*
+     Description of the manual page.  This is used in the NAME section.
+     Can be an empty string if you do not want to automatically generate
+     the NAME section.
+
+   *authors*
+     A list of strings with authors, or a single string.  Can be an empty
+     string or list if you do not want to automatically generate an AUTHORS
+     section in the manual page.
+
+   *section*
+     The manual page section.  Used for the output file name as well as in the
+     manual page header.
+
+   .. versionadded:: 1.0
+
+.. confval:: man_show_urls
+
+   If true, add URL addresses after links.  Default is ``False``.
+
+   .. versionadded:: 1.1
+
+.. confval:: man_make_section_directory
+
+   If true, make a section directory on build man page.  Default is True.
+
+   .. versionadded:: 3.3
+   .. versionchanged:: 4.0
+
+      The default is changed to ``False`` from ``True``.
+
+   .. versionchanged:: 4.0.2
+
+      The default is changed to ``True`` from ``False`` again.
+
+.. _texinfo-options:
+
+Options for Texinfo output
+--------------------------
+
+These options influence Texinfo output.
+
+.. confval:: texinfo_documents
+
+   This value determines how to group the document tree into Texinfo source
+   files.  It must be a list of tuples ``(startdocname, targetname, title,
+   author, dir_entry, description, category, toctree_only)``, where the items
+   are:
+
+   *startdocname*
+     String that specifies the :term:`document name` of the the Texinfo file's
+     master document.  All documents referenced by the *startdoc* document in
+     TOC trees will be included in the Texinfo file.  (If you want to use the
+     default master document for your Texinfo build, provide your
+     :confval:`root_doc` here.)
+
+   *targetname*
+     File name (no extension) of the Texinfo file in the output directory.
+
+   *title*
+     Texinfo document title.  Can be empty to use the title of the *startdoc*
+     document.  Inserted as Texinfo markup, so special characters like ``@`` and
+     ``{}`` will need to be escaped to be inserted literally.
+
+   *author*
+     Author for the Texinfo document.  Inserted as Texinfo markup.  Use ``@*``
+     to separate multiple authors, as in: ``'John@*Sarah'``.
+
+   *dir_entry*
+     The name that will appear in the top-level ``DIR`` menu file.
+
+   *description*
+     Descriptive text to appear in the top-level ``DIR`` menu file.
+
+   *category*
+     Specifies the section which this entry will appear in the top-level
+     ``DIR`` menu file.
+
+   *toctree_only*
+     Must be ``True`` or ``False``.  If true, the *startdoc* document itself is
+     not included in the output, only the documents referenced by it via TOC
+     trees.  With this option, you can put extra stuff in the master document
+     that shows up in the HTML, but not the Texinfo output.
+
+   .. versionadded:: 1.1
+
+.. confval:: texinfo_appendices
+
+   A list of document names to append as an appendix to all manuals.
+
+   .. versionadded:: 1.1
+
+.. confval:: texinfo_domain_indices
+
+   If true, generate domain-specific indices in addition to the general index.
+   For e.g. the Python domain, this is the global module index.  Default is
+   ``True``.
+
+   This value can be a bool or a list of index names that should be generated,
+   like for :confval:`html_domain_indices`.
+
+   .. versionadded:: 1.1
+
+.. confval:: texinfo_show_urls
+
+   Control how to display URL addresses.
+
+   * ``'footnote'`` -- display URLs in footnotes (default)
+   * ``'no'`` -- do not display URLs
+   * ``'inline'`` -- display URLs inline in parentheses
+
+   .. versionadded:: 1.1
+
+.. confval:: texinfo_no_detailmenu
+
+   If true, do not generate a ``@detailmenu`` in the "Top" node's menu
+   containing entries for each sub-node in the document.  Default is ``False``.
+
+   .. versionadded:: 1.2
+
+.. confval:: texinfo_elements
+
+   A dictionary that contains Texinfo snippets that override those Sphinx
+   usually puts into the generated ``.texi`` files.
+
+   * Keys that you may want to override include:
+
+     ``'paragraphindent'``
+        Number of spaces to indent the first line of each paragraph, default
+        ``2``.  Specify ``0`` for no indentation.
+
+     ``'exampleindent'``
+        Number of spaces to indent the lines for examples or literal blocks,
+        default ``4``.  Specify ``0`` for no indentation.
+
+     ``'preamble'``
+        Texinfo markup inserted near the beginning of the file.
+
+     ``'copying'``
+        Texinfo markup inserted within the ``@copying`` block and displayed
+        after the title.  The default value consists of a simple title page
+        identifying the project.
+
+   * Keys that are set by other options and therefore should not be overridden
+     are:
+
+     ``'author'``
+     ``'body'``
+     ``'date'``
+     ``'direntry'``
+     ``'filename'``
+     ``'project'``
+     ``'release'``
+     ``'title'``
+
+   .. versionadded:: 1.1
+
+.. confval:: texinfo_cross_references
+
+  If false, do not generate inline references in a document.  That makes
+  an info file more readable with stand-alone reader (``info``).
+  Default is ``True``.
+
+  .. versionadded:: 4.4
+
+.. _qthelp-options:
+
+Options for QtHelp output
+--------------------------
+
+These options influence qthelp output.  As this builder derives from the HTML
+builder, the HTML options also apply where appropriate.
+
+.. confval:: qthelp_basename
+
+   The basename for the qthelp file.  It defaults to the :confval:`project`
+   name.
+
+.. confval:: qthelp_namespace
+
+   The namespace for the qthelp file.  It defaults to
+   ``org.sphinx.<project_name>.<project_version>``.
+
+.. confval:: qthelp_theme
+
+   The HTML theme for the qthelp output.
+   This defaults to ``'nonav'``.
+
+.. confval:: qthelp_theme_options
+
+   A dictionary of options that influence the look and feel of the selected
+   theme.  These are theme-specific.  For the options understood by the builtin
+   themes, see :ref:`this section <builtin-themes>`.
+
+
+Options for the linkcheck builder
+---------------------------------
+
+.. confval:: linkcheck_ignore
+
+   A list of regular expressions that match URIs that should not be checked
+   when doing a ``linkcheck`` build.  Example::
+
+      linkcheck_ignore = [r'http://localhost:\d+/']
+
+   .. versionadded:: 1.1
+
+.. confval:: linkcheck_allowed_redirects
+
+   A dictionary that maps a pattern of the source URI to a pattern of the canonical
+   URI. The linkcheck builder treats the redirected link as "working" when:
+
+   - the link in the document matches the source URI pattern, and
+   - the redirect location matches the canonical URI pattern.
+
+   Example:
+
+   .. code-block:: python
+
+      linkcheck_allowed_redirects = {
+          # All HTTP redirections from the source URI to the canonical URI will be treated as "working".
+          r'https://sphinx-doc\.org/.*': r'https://sphinx-doc\.org/en/master/.*'
+      }
+
+   If set, linkcheck builder will emit a warning when disallowed redirection
+   found.  It's useful to detect unexpected redirects under :option:`the
+   warn-is-error mode <sphinx-build -W>`.
+
+   .. versionadded:: 4.1
+
+.. confval:: linkcheck_request_headers
+
+   A dictionary that maps baseurls to HTTP request headers.
+
+   The key is a URL base string like ``"https://www.sphinx-doc.org/"``.  To specify
+   headers for other hosts, ``"*"`` can be used.  It matches all hosts only when
+   the URL does not match other settings.
+
+   The value is a dictionary that maps header name to its value.
+
+   Example:
+
+   .. code-block:: python
+
+      linkcheck_request_headers = {
+          "https://www.sphinx-doc.org/": {
+              "Accept": "text/html",
+              "Accept-Encoding": "utf-8",
+          },
+          "*": {
+              "Accept": "text/html,application/xhtml+xml",
+          }
+      }
+
+   .. versionadded:: 3.1
+
+.. confval:: linkcheck_retries
+
+   The number of times the linkcheck builder will attempt to check a URL before
+   declaring it broken. Defaults to 1 attempt.
+
+   .. versionadded:: 1.4
+
+.. confval:: linkcheck_timeout
+
+   A timeout value, in seconds, for the linkcheck builder.  The default is to
+   use Python's global socket timeout.
+
+   .. versionadded:: 1.1
+
+.. confval:: linkcheck_workers
+
+   The number of worker threads to use when checking links.  Default is 5
+   threads.
+
+   .. versionadded:: 1.1
+
+.. confval:: linkcheck_anchors
+
+   If true, check the validity of ``#anchor``\ s in links. Since this requires
+   downloading the whole document, it's considerably slower when enabled.
+   Default is ``True``.
+
+   .. versionadded:: 1.2
+
+.. confval:: linkcheck_anchors_ignore
+
+   A list of regular expressions that match anchors Sphinx should skip when
+   checking the validity of anchors in links. This allows skipping anchors that
+   a website's JavaScript adds to control dynamic pages or when triggering an
+   internal REST request. Default is ``["^!"]``.
+
+   .. tip::
+
+      Use :confval:`linkcheck_anchors_ignore_for_url` to check a URL,
+      but skip verifying that the anchors exist.
+
+   .. note::
+
+      If you want to ignore anchors of a specific page or of pages that match a
+      specific pattern (but still check occurrences of the same page(s) that
+      don't have anchors), use :confval:`linkcheck_ignore` instead, for example
+      as follows::
+
+         linkcheck_ignore = [
+            'https://www.sphinx-doc.org/en/1.7/intro.html#',
+         ]
+
+   .. versionadded:: 1.5
+
+.. confval:: linkcheck_anchors_ignore_for_url
+
+   A list or tuple of regular expressions matching URLs
+   for which Sphinx should not check the validity of anchors.
+   This allows skipping anchor checks on a per-page basis
+   while still checking the validity of the page itself.
+   Default is an empty tuple ``()``.
+
+   .. versionadded:: 7.1
+
+.. confval:: linkcheck_auth
+
+   Pass authentication information when doing a ``linkcheck`` build.
+
+   A list of ``(regex_pattern, auth_info)`` tuples where the items are:
+
+   *regex_pattern*
+     A regular expression that matches a URI.
+   *auth_info*
+     Authentication information to use for that URI. The value can be anything
+     that is understood by the ``requests`` library (see :ref:`requests
+     Authentication <requests:authentication>` for details).
+
+   The ``linkcheck`` builder will use the first matching ``auth_info`` value
+   it can find in the :confval:`linkcheck_auth` list, so values earlier in the
+   list have higher priority.
+
+   Example::
+
+      linkcheck_auth = [
+        ('https://foo\.yourcompany\.com/.+', ('johndoe', 'secret')),
+        ('https://.+\.yourcompany\.com/.+', HTTPDigestAuth(...)),
+      ]
+
+   .. versionadded:: 2.3
+
+.. confval:: linkcheck_rate_limit_timeout
+
+   The ``linkcheck`` builder may issue a large number of requests to the same
+   site over a short period of time. This setting controls the builder behavior
+   when servers indicate that requests are rate-limited.
+
+   If a server indicates when to retry (using the `Retry-After`_ header),
+   ``linkcheck`` always follows the server indication.
+
+   Otherwise, ``linkcheck`` waits for a minute before to retry and keeps
+   doubling the wait time between attempts until it succeeds or exceeds the
+   ``linkcheck_rate_limit_timeout``. By default, the timeout is 5 minutes.
+
+   .. _Retry-After: https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.3
+
+   .. versionadded:: 3.4
+
+.. confval:: linkcheck_exclude_documents
+
+   A list of regular expressions that match documents in which Sphinx should
+   not check the validity of links. This can be used for permitting link decay
+   in legacy or historical sections of the documentation.
+
+   Example::
+
+      # ignore all links in documents located in a subfolder named 'legacy'
+      linkcheck_exclude_documents = [r'.*/legacy/.*']
+
+   .. versionadded:: 4.4
+
+
+Options for the XML builder
+---------------------------
+
+.. confval:: xml_pretty
+
+   If true, pretty-print the XML.  Default is ``True``.
+
+   .. versionadded:: 1.2
+
+
+.. rubric:: Footnotes
+
+.. [1] A note on available globbing syntax: you can use the standard shell
+       constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that
+       these all don't match slashes.  A double star ``**`` can be used to
+       match any sequence of characters *including* slashes.
+
+
+.. _c-config:
+
+Options for the C domain
+------------------------
+
+.. confval:: c_id_attributes
+
+   A list of strings that the parser additionally should accept as attributes.
+   This can for example be used when attributes have been ``#define`` d for
+   portability.
+
+   .. versionadded:: 3.0
+
+.. confval:: c_paren_attributes
+
+   A list of strings that the parser additionally should accept as attributes
+   with one argument.  That is, if ``my_align_as`` is in the list, then
+   ``my_align_as(X)`` is parsed as an attribute for all strings ``X`` that have
+   balanced braces (``()``, ``[]``, and ``{}``).  This can for example be used
+   when attributes have been ``#define`` d for portability.
+
+   .. versionadded:: 3.0
+
+.. confval:: c_extra_keywords
+
+  A list of identifiers to be recognized as keywords by the C parser.
+  It defaults to ``['alignas', 'alignof', 'bool', 'complex', 'imaginary',
+  'noreturn', 'static_assert', 'thread_local']``.
+
+  .. versionadded:: 4.0.3
+
+.. confval:: c_maximum_signature_line_length
+
+   If a signature's length in characters exceeds the number set, each
+   parameter will be displayed on an individual logical line. This is a
+   domain-specific setting, overriding :confval:`maximum_signature_line_length`.
+
+   .. versionadded:: 7.1
+
+.. _cpp-config:
+
+Options for the C++ domain
+--------------------------
+
+.. confval:: cpp_index_common_prefix
+
+   A list of prefixes that will be ignored when sorting C++ objects in the
+   global index.  For example ``['awesome_lib::']``.
+
+   .. versionadded:: 1.5
+
+.. confval:: cpp_id_attributes
+
+   A list of strings that the parser additionally should accept as attributes.
+   This can for example be used when attributes have been ``#define`` d for
+   portability.
+
+   .. versionadded:: 1.5
+
+.. confval:: cpp_paren_attributes
+
+   A list of strings that the parser additionally should accept as attributes
+   with one argument.  That is, if ``my_align_as`` is in the list, then
+   ``my_align_as(X)`` is parsed as an attribute for all strings ``X`` that have
+   balanced braces (``()``, ``[]``, and ``{}``).  This can for example be used
+   when attributes have been ``#define`` d for portability.
+
+   .. versionadded:: 1.5
+
+.. confval:: cpp_maximum_signature_line_length
+
+   If a signature's length in characters exceeds the number set, each
+   parameter will be displayed on an individual logical line. This is a
+   domain-specific setting, overriding :confval:`maximum_signature_line_length`.
+
+   .. versionadded:: 7.1
+
+Options for the Python domain
+-----------------------------
+
+.. confval:: python_display_short_literal_types
+
+   This value controls how :py:data:`~typing.Literal` types are displayed.
+   The setting is a boolean, default ``False``.
+
+   Examples
+   ~~~~~~~~
+
+   The examples below use the following :rst:dir:`py:function` directive:
+
+   .. code:: reStructuredText
+
+      .. py:function:: serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None
+
+   When ``False``, :py:data:`~typing.Literal` types display as per standard
+   Python syntax, i.e.:
+
+      .. code:: python
+
+         serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None
+
+   When ``True``, :py:data:`~typing.Literal` types display with a short,
+   :PEP:`604`-inspired syntax, i.e.:
+
+      .. code:: python
+
+         serve_food(item: "egg" | "spam" | "lobster thermidor") -> None
+
+   .. versionadded:: 6.2
+
+.. confval:: python_use_unqualified_type_names
+
+   If true, suppress the module name of the python reference if it can be
+   resolved.  The default is ``False``.
+
+   .. versionadded:: 4.0
+
+   .. note:: This configuration is still in experimental
+
+.. confval:: python_maximum_signature_line_length
+
+   If a signature's length in characters exceeds the number set,
+   each argument or type parameter will be displayed on an individual logical line.
+   This is a domain-specific setting,
+   overriding :confval:`maximum_signature_line_length`.
+
+   For the Python domain, the signature length depends on whether
+   the type parameters or the list of arguments are being formatted.
+   For the former, the signature length ignores the length of the arguments list;
+   for the latter, the signature length ignores the length of
+   the type parameters list.
+
+   For instance, with `python_maximum_signature_line_length = 20`,
+   only the list of type parameters will be wrapped
+   while the arguments list will be rendered on a single line
+
+   .. code:: rst
+
+      .. py:function:: add[T: VERY_LONG_SUPER_TYPE, U: VERY_LONG_SUPER_TYPE](a: T, b: U)
+
+   .. versionadded:: 7.1
+
+Options for the Javascript domain
+---------------------------------
+
+.. confval:: javascript_maximum_signature_line_length
+
+   If a signature's length in characters exceeds the number set, each
+   parameter will be displayed on an individual logical line. This is a
+   domain-specific setting, overriding :confval:`maximum_signature_line_length`.
+
+   .. versionadded:: 7.1
+
+Example of configuration file
+-----------------------------
+
+.. literalinclude:: /_static/conf.py.txt
+   :language: python
diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst
new file mode 100644
index 0000000..1498ae9
--- /dev/null
+++ b/doc/usage/extensions/autodoc.rst
@@ -0,0 +1,853 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.autodoc` -- Include documentation from docstrings
+==================================================================
+
+.. module:: sphinx.ext.autodoc
+   :synopsis: Include documentation from docstrings.
+
+.. index:: pair: automatic; documentation
+           single: docstring
+
+This extension can import the modules you are documenting, and pull in
+documentation from docstrings in a semi-automatic way.
+
+.. note::
+
+   For Sphinx (actually, the Python interpreter that executes Sphinx) to find
+   your module, it must be importable.  That means that the module or the
+   package must be in one of the directories on :data:`sys.path` -- adapt your
+   :data:`sys.path` in the configuration file accordingly.
+
+.. warning::
+
+   :mod:`~sphinx.ext.autodoc` **imports** the modules to be documented.  If any
+   modules have side effects on import, these will be executed by ``autodoc``
+   when ``sphinx-build`` is run.
+
+   If you document scripts (as opposed to library modules), make sure their main
+   routine is protected by a ``if __name__ == '__main__'`` condition.
+
+For this to work, the docstrings must of course be written in correct
+reStructuredText.  You can then use all of the usual Sphinx markup in the
+docstrings, and it will end up correctly in the documentation.  Together with
+hand-written documentation, this technique eases the pain of having to maintain
+two locations for documentation, while at the same time avoiding
+auto-generated-looking pure API documentation.
+
+If you prefer `NumPy`_ or `Google`_ style docstrings over reStructuredText,
+you can also enable the :mod:`napoleon <sphinx.ext.napoleon>` extension.
+:mod:`napoleon <sphinx.ext.napoleon>` is a preprocessor that converts your
+docstrings to correct reStructuredText before :mod:`autodoc` processes them.
+
+.. _Google: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings
+.. _NumPy: https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
+
+
+Directives
+----------
+
+:mod:`autodoc` provides several directives that are versions of the usual
+:rst:dir:`py:module`, :rst:dir:`py:class` and so forth.  On parsing time, they
+import the corresponding module and extract the docstring of the given objects,
+inserting them into the page source under a suitable :rst:dir:`py:module`,
+:rst:dir:`py:class` etc.  directive.
+
+.. note::
+
+   Just as :rst:dir:`py:class` respects the current :rst:dir:`py:module`,
+   :rst:dir:`autoclass` will also do so.  Likewise, :rst:dir:`automethod` will
+   respect the current :rst:dir:`py:class`.
+
+
+.. rst:directive:: automodule
+                   autoclass
+                   autoexception
+
+   Document a module, class or exception.  All three directives will by default
+   only insert the docstring of the object itself::
+
+      .. autoclass:: Noodle
+
+   will produce source like this::
+
+      .. class:: Noodle
+
+         Noodle's docstring.
+
+   The "auto" directives can also contain content of their own, it will be
+   inserted into the resulting non-auto directive source after the docstring
+   (but before any automatic member documentation).
+
+   Therefore, you can also mix automatic and non-automatic member documentation,
+   like so::
+
+      .. autoclass:: Noodle
+         :members: eat, slurp
+
+         .. method:: boil(time=10)
+
+            Boil the noodle *time* minutes.
+
+   .. rubric:: Options
+
+   .. rst:directive:option:: members
+      :type: no value or comma separated list
+
+      If set, autodoc will generate document for the members of the target
+      module, class or exception.
+
+      For example::
+
+        .. automodule:: noodle
+           :members:
+
+      will document all module members (recursively), and ::
+
+        .. autoclass:: Noodle
+           :members:
+
+      will document all class member methods and properties.
+
+      By default, autodoc will not generate document for the members that are
+      private, not having docstrings, inherited from super class, or special
+      members.
+
+      For modules, ``__all__`` will be respected when looking for members unless
+      you give the ``ignore-module-all`` flag option.  Without
+      ``ignore-module-all``, the order of the members will also be the order in
+      ``__all__``.
+
+      You can also give an explicit list of members; only these will then be
+      documented::
+
+        .. autoclass:: Noodle
+           :members: eat, slurp
+
+   .. rst:directive:option:: undoc-members
+      :type: no value
+
+      If set, autodoc will also generate document for the members not having
+      docstrings::
+
+        .. automodule:: noodle
+           :members:
+           :undoc-members:
+
+   .. rst:directive:option:: private-members
+      :type: no value or comma separated list
+
+      If set, autodoc will also generate document for the private members
+      (that is, those named like ``_private`` or ``__private``)::
+
+        .. automodule:: noodle
+           :members:
+           :private-members:
+
+      It can also take an explicit list of member names to be documented as
+      arguments::
+
+        .. automodule:: noodle
+           :members:
+           :private-members: _spicy, _garlickly
+
+      .. versionadded:: 1.1
+      .. versionchanged:: 3.2
+         The option can now take arguments.
+
+   .. rst:directive:option:: special-members
+      :type: no value or comma separated list
+
+      If set, autodoc will also generate document for the special members
+      (that is, those named like ``__special__``)::
+
+        .. autoclass:: my.Class
+           :members:
+           :special-members:
+
+      It can also take an explicit list of member names to be documented as
+      arguments::
+
+        .. autoclass:: my.Class
+           :members:
+           :special-members: __init__, __name__
+
+      .. versionadded:: 1.1
+
+      .. versionchanged:: 1.2
+         The option can now take arguments
+
+   **Options and advanced usage**
+
+   * If you want to make the ``members`` option (or other options described
+     below) the default, see :confval:`autodoc_default_options`.
+
+     .. tip::
+
+        You can use a negated form, :samp:`'no-{flag}'`, as an option of
+        autodoc directive, to disable it temporarily.  For example::
+
+           .. automodule:: foo
+              :no-undoc-members:
+
+     .. tip::
+
+        You can use autodoc directive options to temporarily override or
+        extend default options which takes list as an input. For example::
+
+           .. autoclass:: Noodle
+              :members: eat
+              :private-members: +_spicy, _garlickly
+
+     .. versionchanged:: 3.5
+        The default options can be overridden or extended temporarily.
+
+   * autodoc considers a member private if its docstring contains
+     ``:meta private:`` in its :ref:`info-field-lists`.
+     For example:
+
+     .. code-block:: python
+
+        def my_function(my_arg, my_other_arg):
+            """blah blah blah
+
+            :meta private:
+            """
+
+     .. versionadded:: 3.0
+
+   * autodoc considers a member public if its docstring contains
+     ``:meta public:`` in its :ref:`info-field-lists`, even if it starts with
+     an underscore.
+     For example:
+
+     .. code-block:: python
+
+        def _my_function(my_arg, my_other_arg):
+            """blah blah blah
+
+            :meta public:
+            """
+
+     .. versionadded:: 3.1
+
+   * autodoc considers a variable member does not have any default value if its
+     docstring contains ``:meta hide-value:`` in its :ref:`info-field-lists`.
+     Example:
+
+     .. code-block:: python
+
+        var1 = None  #: :meta hide-value:
+
+     .. versionadded:: 3.5
+
+   * For classes and exceptions, members inherited from base classes will be
+     left out when documenting all members, unless you give the
+     ``inherited-members`` option, in addition to ``members``::
+
+        .. autoclass:: Noodle
+           :members:
+           :inherited-members:
+
+     This can be combined with ``undoc-members`` to document *all* available
+     members of the class or module.
+
+     It can take an ancestor class not to document inherited members from it.
+     By default, members of ``object`` class are not documented.  To show them
+     all, give ``None`` to the option.
+
+     For example; If your class ``Foo`` is derived from ``list`` class and
+     you don't want to document ``list.__len__()``, you should specify a
+     option ``:inherited-members: list`` to avoid special members of list
+     class.
+
+     Another example; If your class Foo has ``__str__`` special method and
+     autodoc directive has both ``inherited-members`` and ``special-members``,
+     ``__str__`` will be documented as in the past, but other special method
+     that are not implemented in your class ``Foo``.
+
+     Since v5.0, it can take a comma separated list of ancestor classes.  It
+     allows to suppress inherited members of several classes on the module at
+     once by specifying the option to :rst:dir:`automodule` directive.
+
+     Note: this will lead to markup errors if the inherited members come from a
+     module whose docstrings are not reST formatted.
+
+     .. versionadded:: 0.3
+
+     .. versionchanged:: 3.0
+
+        It takes an ancestor class name as an argument.
+
+     .. versionchanged:: 5.0
+
+        It takes a comma separated list of ancestor class names.
+
+   * It's possible to override the signature for explicitly documented callable
+     objects (functions, methods, classes) with the regular syntax that will
+     override the signature gained from introspection::
+
+        .. autoclass:: Noodle(type)
+
+           .. automethod:: eat(persona)
+
+     This is useful if the signature from the method is hidden by a decorator.
+
+     .. versionadded:: 0.4
+
+   * The :rst:dir:`automodule`, :rst:dir:`autoclass` and
+     :rst:dir:`autoexception` directives also support a flag option called
+     ``show-inheritance``.  When given, a list of base classes will be inserted
+     just below the class signature (when used with :rst:dir:`automodule`, this
+     will be inserted for every class that is documented in the module).
+
+     .. versionadded:: 0.4
+
+   * All autodoc directives support the ``no-index`` flag option that has the
+     same effect as for standard :rst:dir:`py:function` etc. directives: no
+     index entries are generated for the documented object (and all
+     autodocumented members).
+
+     .. versionadded:: 0.4
+
+   * :rst:dir:`automodule` also recognizes the ``synopsis``, ``platform`` and
+     ``deprecated`` options that the standard :rst:dir:`py:module` directive
+     supports.
+
+     .. versionadded:: 0.5
+
+   * :rst:dir:`automodule` and :rst:dir:`autoclass` also has an ``member-order``
+     option that can be used to override the global value of
+     :confval:`autodoc_member_order` for one directive.
+
+     .. versionadded:: 0.6
+
+   * The directives supporting member documentation also have a
+     ``exclude-members`` option that can be used to exclude single member names
+     from documentation, if all members are to be documented.
+
+     .. versionadded:: 0.6
+
+   * In an :rst:dir:`automodule` directive with the ``members`` option set, only
+     module members whose ``__module__`` attribute is equal to the module name
+     as given to ``automodule`` will be documented.  This is to prevent
+     documentation of imported classes or functions.  Set the
+     ``imported-members`` option if you want to prevent this behavior and
+     document all available members.  Note that attributes from imported modules
+     will not be documented, because attribute documentation is discovered by
+     parsing the source file of the current module.
+
+     .. versionadded:: 1.2
+
+   * Add a list of modules in the :confval:`autodoc_mock_imports` to prevent
+     import errors to halt the building process when some external dependencies
+     are not importable at build time.
+
+     .. versionadded:: 1.3
+
+   * As a hint to autodoc extension, you can put a ``::`` separator in between
+     module name and object name to let autodoc know the correct module name if
+     it is ambiguous. ::
+
+        .. autoclass:: module.name::Noodle
+
+   * :rst:dir:`autoclass` also recognizes the ``class-doc-from`` option that
+     can be used to override the global value of :confval:`autoclass_content`.
+
+     .. versionadded:: 4.1
+
+.. rst:directive:: autofunction
+                   autodecorator
+                   autodata
+                   automethod
+                   autoattribute
+                   autoproperty
+
+   These work exactly like :rst:dir:`autoclass` etc.,
+   but do not offer the options used for automatic member documentation.
+
+   :rst:dir:`autodata` and :rst:dir:`autoattribute` support the ``annotation``
+   option.  The option controls how the value of variable is shown.  If specified
+   without arguments, only the name of the variable will be printed, and its value
+   is not shown::
+
+      .. autodata:: CD_DRIVE
+         :annotation:
+
+   If the option specified with arguments, it is printed after the name as a value
+   of the variable::
+
+      .. autodata:: CD_DRIVE
+         :annotation: = your CD device name
+
+   By default, without ``annotation`` option, Sphinx tries to obtain the value of
+   the variable and print it after the name.
+
+   The ``no-value`` option can be used instead of a blank ``annotation`` to show the
+   type hint but not the value::
+
+      .. autodata:: CD_DRIVE
+         :no-value:
+
+   If both the ``annotation`` and ``no-value`` options are used, ``no-value`` has no
+   effect.
+
+   For module data members and class attributes, documentation can either be put
+   into a comment with special formatting (using a ``#:`` to start the comment
+   instead of just ``#``), or in a docstring *after* the definition.  Comments
+   need to be either on a line of their own *before* the definition, or
+   immediately after the assignment *on the same line*.  The latter form is
+   restricted to one line only.
+
+   This means that in the following class definition, all attributes can be
+   autodocumented::
+
+      class Foo:
+          """Docstring for class Foo."""
+
+          #: Doc comment for class attribute Foo.bar.
+          #: It can have multiple lines.
+          bar = 1
+
+          flox = 1.5   #: Doc comment for Foo.flox. One line only.
+
+          baz = 2
+          """Docstring for class attribute Foo.baz."""
+
+          def __init__(self):
+              #: Doc comment for instance attribute qux.
+              self.qux = 3
+
+              self.spam = 4
+              """Docstring for instance attribute spam."""
+
+   .. versionchanged:: 0.6
+      :rst:dir:`autodata` and :rst:dir:`autoattribute` can now extract
+      docstrings.
+   .. versionchanged:: 1.1
+      Comment docs are now allowed on the same line after an assignment.
+   .. versionchanged:: 1.2
+      :rst:dir:`autodata` and :rst:dir:`autoattribute` have an ``annotation``
+      option.
+   .. versionchanged:: 2.0
+      :rst:dir:`autodecorator` added.
+   .. versionchanged:: 2.1
+      :rst:dir:`autoproperty` added.
+   .. versionchanged:: 3.4
+      :rst:dir:`autodata` and :rst:dir:`autoattribute` now have a ``no-value``
+      option.
+
+   .. note::
+
+      If you document decorated functions or methods, keep in mind that autodoc
+      retrieves its docstrings by importing the module and inspecting the
+      ``__doc__`` attribute of the given function or method.  That means that if
+      a decorator replaces the decorated function with another, it must copy the
+      original ``__doc__`` to the new function.
+
+
+Configuration
+-------------
+
+There are also config values that you can set:
+
+.. confval:: autoclass_content
+
+   This value selects what content will be inserted into the main body of an
+   :rst:dir:`autoclass` directive.  The possible values are:
+
+   ``"class"``
+      Only the class' docstring is inserted.  This is the default.  You can
+      still document ``__init__`` as a separate method using
+      :rst:dir:`automethod` or the ``members`` option to :rst:dir:`autoclass`.
+   ``"both"``
+      Both the class' and the ``__init__`` method's docstring are concatenated
+      and inserted.
+   ``"init"``
+      Only the ``__init__`` method's docstring is inserted.
+
+   .. versionadded:: 0.3
+
+   If the class has no ``__init__`` method or if the ``__init__`` method's
+   docstring is empty, but the class has a ``__new__`` method's docstring,
+   it is used instead.
+
+   .. versionadded:: 1.4
+
+.. confval:: autodoc_class_signature
+
+   This value selects how the signature will be displayed for the class defined
+   by :rst:dir:`autoclass` directive.  The possible values are:
+
+   ``"mixed"``
+      Display the signature with the class name.
+   ``"separated"``
+      Display the signature as a method.
+
+   The default is ``"mixed"``.
+
+   .. versionadded:: 4.1
+
+.. confval:: autodoc_member_order
+
+   This value selects if automatically documented members are sorted
+   alphabetical (value ``'alphabetical'``), by member type (value
+   ``'groupwise'``) or by source order (value ``'bysource'``).  The default is
+   alphabetical.
+
+   Note that for source order, the module must be a Python module with the
+   source code available.
+
+   .. versionadded:: 0.6
+   .. versionchanged:: 1.0
+      Support for ``'bysource'``.
+
+.. confval:: autodoc_default_flags
+
+   This value is a list of autodoc directive flags that should be automatically
+   applied to all autodoc directives.  The supported flags are ``'members'``,
+   ``'undoc-members'``, ``'private-members'``, ``'special-members'``,
+   ``'inherited-members'``, ``'show-inheritance'``, ``'ignore-module-all'``
+   and ``'exclude-members'``.
+
+   .. versionadded:: 1.0
+
+   .. deprecated:: 1.8
+
+      Integrated into :confval:`autodoc_default_options`.
+
+.. confval:: autodoc_default_options
+
+   The default options for autodoc directives.  They are applied to all autodoc
+   directives automatically.  It must be a dictionary which maps option names
+   to the values.  For example::
+
+       autodoc_default_options = {
+           'members': 'var1, var2',
+           'member-order': 'bysource',
+           'special-members': '__init__',
+           'undoc-members': True,
+           'exclude-members': '__weakref__'
+       }
+
+   Setting ``None`` or ``True`` to the value is equivalent to giving only the
+   option name to the directives.
+
+   The supported options are ``'members'``, ``'member-order'``,
+   ``'undoc-members'``, ``'private-members'``, ``'special-members'``,
+   ``'inherited-members'``, ``'show-inheritance'``, ``'ignore-module-all'``,
+   ``'imported-members'``, ``'exclude-members'``, ``'class-doc-from'`` and
+   ``'no-value'``.
+
+   .. versionadded:: 1.8
+
+   .. versionchanged:: 2.0
+      Accepts ``True`` as a value.
+
+   .. versionchanged:: 2.1
+      Added ``'imported-members'``.
+
+   .. versionchanged:: 4.1
+      Added ``'class-doc-from'``.
+
+   .. versionchanged:: 4.5
+      Added ``'no-value'``.
+
+.. confval:: autodoc_docstring_signature
+
+   Functions imported from C modules cannot be introspected, and therefore the
+   signature for such functions cannot be automatically determined.  However, it
+   is an often-used convention to put the signature into the first line of the
+   function's docstring.
+
+   If this boolean value is set to ``True`` (which is the default), autodoc will
+   look at the first line of the docstring for functions and methods, and if it
+   looks like a signature, use the line as the signature and remove it from the
+   docstring content.
+
+   autodoc will continue to look for multiple signature lines,
+   stopping at the first line that does not look like a signature.
+   This is useful for declaring overloaded function signatures.
+
+   .. versionadded:: 1.1
+   .. versionchanged:: 3.1
+
+      Support overloaded signatures
+
+   .. versionchanged:: 4.0
+
+      Overloaded signatures do not need to be separated by a backslash
+
+.. confval:: autodoc_mock_imports
+
+   This value contains a list of modules to be mocked up. This is useful when
+   some external dependencies are not met at build time and break the building
+   process. You may only specify the root package of the dependencies
+   themselves and omit the sub-modules:
+
+   .. code-block:: python
+
+      autodoc_mock_imports = ["django"]
+
+   Will mock all imports under the ``django`` package.
+
+   .. versionadded:: 1.3
+
+   .. versionchanged:: 1.6
+      This config value only requires to declare the top-level modules that
+      should be mocked.
+
+.. confval:: autodoc_typehints
+
+   This value controls how to represent typehints.  The setting takes the
+   following values:
+
+   * ``'signature'`` -- Show typehints in the signature (default)
+   * ``'description'`` -- Show typehints as content of the function or method
+     The typehints of overloaded functions or methods will still be represented
+     in the signature.
+   * ``'none'`` -- Do not show typehints
+   * ``'both'`` -- Show typehints in the signature and as content of
+     the function or method
+
+   Overloaded functions or methods will not have typehints included in the
+   description because it is impossible to accurately represent all possible
+   overloads as a list of parameters.
+
+   .. versionadded:: 2.1
+   .. versionadded:: 3.0
+
+      New option ``'description'`` is added.
+
+   .. versionadded:: 4.1
+
+      New option ``'both'`` is added.
+
+.. confval:: autodoc_typehints_description_target
+
+   This value controls whether the types of undocumented parameters and return
+   values are documented when ``autodoc_typehints`` is set to ``description``.
+
+   The default value is ``"all"``, meaning that types are documented for all
+   parameters and return values, whether they are documented or not.
+
+   When set to ``"documented"``, types will only be documented for a parameter
+   or a return value that is already documented by the docstring.
+
+   With ``"documented_params"``, parameter types will only be annotated if the
+   parameter is documented in the docstring. The return type is always
+   annotated (except if it is ``None``).
+
+   .. versionadded:: 4.0
+
+   .. versionadded:: 5.0
+
+      New option ``'documented_params'`` is added.
+
+.. confval:: autodoc_type_aliases
+
+   A dictionary for users defined `type aliases`__ that maps a type name to the
+   full-qualified object name.  It is used to keep type aliases not evaluated in
+   the document.  Defaults to empty (``{}``).
+
+   The type aliases are only available if your program enables :pep:`Postponed
+   Evaluation of Annotations (PEP 563) <563>` feature via ``from __future__ import
+   annotations``.
+
+   For example, there is code using a type alias::
+
+     from __future__ import annotations
+
+     AliasType = Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]
+
+     def f() -> AliasType:
+         ...
+
+   If ``autodoc_type_aliases`` is not set, autodoc will generate internal mark-up
+   from this code as following::
+
+     .. py:function:: f() -> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]
+
+        ...
+
+   If you set ``autodoc_type_aliases`` as
+   ``{'AliasType': 'your.module.AliasType'}``, it generates the following document
+   internally::
+
+     .. py:function:: f() -> your.module.AliasType:
+
+        ...
+
+   .. __: https://mypy.readthedocs.io/en/latest/kinds_of_types.html#type-aliases
+   .. versionadded:: 3.3
+
+.. confval:: autodoc_typehints_format
+
+   This value controls the format of typehints.  The setting takes the
+   following values:
+
+   * ``'fully-qualified'`` -- Show the module name and its name of typehints
+   * ``'short'`` -- Suppress the leading module names of the typehints
+     (ex. ``io.StringIO`` -> ``StringIO``)  (default)
+
+   .. versionadded:: 4.4
+
+   .. versionchanged:: 5.0
+
+      The default setting was changed to ``'short'``
+
+.. confval:: autodoc_preserve_defaults
+
+   If True, the default argument values of functions will be not evaluated on
+   generating document.  It preserves them as is in the source code.
+
+   .. versionadded:: 4.0
+
+      Added as an experimental feature.  This will be integrated into autodoc core
+      in the future.
+
+.. confval:: autodoc_warningiserror
+
+   This value controls the behavior of :option:`sphinx-build -W` during
+   importing modules.
+   If ``False`` is given, autodoc forcedly suppresses the error if the imported
+   module emits warnings.  By default, ``True``.
+
+.. confval:: autodoc_inherit_docstrings
+
+   This value controls the docstrings inheritance.
+   If set to True the docstring for classes or methods, if not explicitly set,
+   is inherited from parents.
+
+   The default is ``True``.
+
+   .. versionadded:: 1.7
+
+.. confval:: suppress_warnings
+   :no-index:
+
+   :mod:`autodoc` supports to suppress warning messages via
+   :confval:`suppress_warnings`.  It allows following warnings types in
+   addition:
+
+   * autodoc
+   * autodoc.import_object
+
+
+Docstring preprocessing
+-----------------------
+
+autodoc provides the following additional events:
+
+.. event:: autodoc-process-docstring (app, what, name, obj, options, lines)
+
+   .. versionadded:: 0.4
+
+   Emitted when autodoc has read and processed a docstring.  *lines* is a list
+   of strings -- the lines of the processed docstring -- that the event handler
+   can modify **in place** to change what Sphinx puts into the output.
+
+   :param app: the Sphinx application object
+   :param what: the type of the object which the docstring belongs to (one of
+      ``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``,
+      ``"attribute"``)
+   :param name: the fully qualified name of the object
+   :param obj: the object itself
+   :param options: the options given to the directive: an object with attributes
+      ``inherited_members``, ``undoc_members``, ``show_inheritance`` and
+      ``no-index`` that are true if the flag option of same name was given to the
+      auto directive
+   :param lines: the lines of the docstring, see above
+
+.. event:: autodoc-before-process-signature (app, obj, bound_method)
+
+   .. versionadded:: 2.4
+
+   Emitted before autodoc formats a signature for an object. The event handler
+   can modify an object to change its signature.
+
+   :param app: the Sphinx application object
+   :param obj: the object itself
+   :param bound_method: a boolean indicates an object is bound method or not
+
+.. event:: autodoc-process-signature (app, what, name, obj, options, signature, return_annotation)
+
+   .. versionadded:: 0.5
+
+   Emitted when autodoc has formatted a signature for an object. The event
+   handler can return a new tuple ``(signature, return_annotation)`` to change
+   what Sphinx puts into the output.
+
+   :param app: the Sphinx application object
+   :param what: the type of the object which the docstring belongs to (one of
+      ``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``,
+      ``"attribute"``)
+   :param name: the fully qualified name of the object
+   :param obj: the object itself
+   :param options: the options given to the directive: an object with attributes
+      ``inherited_members``, ``undoc_members``, ``show_inheritance`` and
+      ``no-index`` that are true if the flag option of same name was given to the
+      auto directive
+   :param signature: function signature, as a string of the form
+      ``"(parameter_1, parameter_2)"``, or ``None`` if introspection didn't
+      succeed and signature wasn't specified in the directive.
+   :param return_annotation: function return annotation as a string of the form
+      ``" -> annotation"``, or ``None`` if there is no return annotation
+
+The :mod:`sphinx.ext.autodoc` module provides factory functions for commonly
+needed docstring processing in event :event:`autodoc-process-docstring`:
+
+.. autofunction:: cut_lines
+.. autofunction:: between
+
+.. event:: autodoc-process-bases (app, name, obj, options, bases)
+
+   Emitted when autodoc has read and processed a class to determine the
+   base-classes.  *bases* is a list of classes that the event handler can
+   modify **in place** to change what Sphinx puts into the output.  It's
+   emitted only if ``show-inheritance`` option given.
+
+   :param app: the Sphinx application object
+   :param name: the fully qualified name of the object
+   :param obj: the object itself
+   :param options: the options given to the class directive
+   :param bases: the list of base classes signature. see above.
+
+   .. versionadded:: 4.1
+   .. versionchanged:: 4.3
+
+      ``bases`` can contain a string as a base class name.  It will be processed
+      as reST mark-up'ed text.
+
+
+Skipping members
+----------------
+
+autodoc allows the user to define a custom method for determining whether a
+member should be included in the documentation by using the following event:
+
+.. event:: autodoc-skip-member (app, what, name, obj, skip, options)
+
+   .. versionadded:: 0.5
+
+   Emitted when autodoc has to decide whether a member should be included in the
+   documentation.  The member is excluded if a handler returns ``True``.  It is
+   included if the handler returns ``False``.
+
+   If more than one enabled extension handles the ``autodoc-skip-member``
+   event, autodoc will use the first non-``None`` value returned by a handler.
+   Handlers should return ``None`` to fall back to the skipping behavior of
+   autodoc and other enabled extensions.
+
+   :param app: the Sphinx application object
+   :param what: the type of the object which the docstring belongs to (one of
+      ``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``,
+      ``"attribute"``)
+   :param name: the fully qualified name of the object
+   :param obj: the object itself
+   :param skip: a boolean indicating if autodoc will skip this member if the
+      user handler does not override the decision
+   :param options: the options given to the directive: an object with attributes
+      ``inherited_members``, ``undoc_members``, ``show_inheritance`` and
+      ``no-index`` that are true if the flag option of same name was given to the
+      auto directive
diff --git a/doc/usage/extensions/autosectionlabel.rst b/doc/usage/extensions/autosectionlabel.rst
new file mode 100644
index 0000000..b5b9b51
--- /dev/null
+++ b/doc/usage/extensions/autosectionlabel.rst
@@ -0,0 +1,56 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.autosectionlabel` -- Allow reference sections using its title
+==============================================================================
+
+.. module:: sphinx.ext.autosectionlabel
+   :synopsis: Allow reference section its title.
+
+.. versionadded:: 1.4
+
+This extension allows you to refer sections its title.  This affects to the
+reference role (:rst:role:`ref`).
+
+For example::
+
+    A Plain Title
+    -------------
+
+    This is the text of the section.
+
+    It refers to the section title, see :ref:`A Plain Title`.
+
+
+Internally, this extension generates the labels for each section.  If same
+section names are used in whole of document, any one is used for a target by
+default. The ``autosectionlabel_prefix_document`` configuration variable can be
+used to make headings which appear multiple times but in different documents
+unique.
+
+
+Configuration
+-------------
+
+.. confval:: autosectionlabel_prefix_document
+
+   True to prefix each section label with the name of the document it is in,
+   followed by a colon. For example, ``index:Introduction`` for a section
+   called ``Introduction`` that appears in document ``index.rst``.  Useful for
+   avoiding ambiguity when the same section heading appears in different
+   documents.
+
+.. confval:: autosectionlabel_maxdepth
+
+   If set, autosectionlabel chooses the sections for labeling by its depth. For
+   example, when set 1 to ``autosectionlabel_maxdepth``, labels are generated
+   only for top level sections, and deeper sections are not labeled.  It
+   defaults to ``None`` (disabled).
+
+
+Debugging
+---------
+
+The ``WARNING: undefined label`` indicates that your reference in
+:rst:role:`ref` is mis-spelled. Invoking :program:`sphinx-build` with ``-vv``
+(see :option:`-v`) will print all section names and the labels that have been
+generated for them. This output can help finding the right reference label.
diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst
new file mode 100644
index 0000000..a18460b
--- /dev/null
+++ b/doc/usage/extensions/autosummary.rst
@@ -0,0 +1,364 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.autosummary` -- Generate autodoc summaries
+===========================================================
+
+.. module:: sphinx.ext.autosummary
+   :synopsis: Generate autodoc summaries
+
+.. versionadded:: 0.6
+
+This extension generates function/method/attribute summary lists, similar to
+those output e.g. by Epydoc and other API doc generation tools.  This is
+especially useful when your docstrings are long and detailed, and putting each
+one of them on a separate page makes them easier to read.
+
+The :mod:`sphinx.ext.autosummary` extension does this in two parts:
+
+1. There is an :rst:dir:`autosummary` directive for generating summary listings
+   that contain links to the documented items, and short summary blurbs
+   extracted from their docstrings.
+
+2. A :rst:dir:`autosummary` directive also generates short "stub" files for the
+   entries listed in its content.  These files by default contain only the
+   corresponding :mod:`sphinx.ext.autodoc` directive, but can be customized with
+   templates.
+
+   The :program:`sphinx-autogen` script is also able to generate "stub" files
+   from command line.
+
+.. rst:directive:: autosummary
+
+   Insert a table that contains links to documented items, and a short summary
+   blurb (the first sentence of the docstring) for each of them.
+
+   The :rst:dir:`autosummary` directive can also optionally serve as a
+   :rst:dir:`toctree` entry for the included items. Optionally, stub
+   ``.rst`` files for these items can also be automatically generated
+   when :confval:`autosummary_generate` is `True`.
+
+   For example, ::
+
+       .. currentmodule:: sphinx
+
+       .. autosummary::
+
+          environment.BuildEnvironment
+          util.relative_uri
+
+   produces a table like this:
+
+   .. currentmodule:: sphinx
+
+   .. autosummary::
+
+      environment.BuildEnvironment
+      util.relative_uri
+
+   .. currentmodule:: sphinx.ext.autosummary
+
+   Autosummary preprocesses the docstrings and signatures with the same
+   :event:`autodoc-process-docstring` and :event:`autodoc-process-signature`
+   hooks as :mod:`~sphinx.ext.autodoc`.
+
+   **Options**
+
+   * If you want the :rst:dir:`autosummary` table to also serve as a
+     :rst:dir:`toctree` entry, use the ``toctree`` option, for example::
+
+         .. autosummary::
+            :toctree: DIRNAME
+
+            sphinx.environment.BuildEnvironment
+            sphinx.util.relative_uri
+
+     The ``toctree`` option also signals to the :program:`sphinx-autogen` script
+     that stub pages should be generated for the entries listed in this
+     directive.  The option accepts a directory name as an argument;
+     :program:`sphinx-autogen` will by default place its output in this
+     directory. If no argument is given, output is placed in the same directory
+     as the file that contains the directive.
+
+     You can also use ``caption`` option to give a caption to the toctree.
+
+     .. versionadded:: 3.1
+
+        caption option added.
+
+   * If you don't want the :rst:dir:`autosummary` to show function signatures in
+     the listing, include the ``nosignatures`` option::
+
+         .. autosummary::
+            :nosignatures:
+
+            sphinx.environment.BuildEnvironment
+            sphinx.util.relative_uri
+
+   * You can specify a custom template with the ``template`` option.
+     For example, ::
+
+         .. autosummary::
+            :template: mytemplate.rst
+
+            sphinx.environment.BuildEnvironment
+
+     would use the template :file:`mytemplate.rst` in your
+     :confval:`templates_path` to generate the pages for all entries
+     listed. See `Customizing templates`_ below.
+
+     .. versionadded:: 1.0
+
+   * You can specify the ``recursive`` option to generate documents for
+     modules and sub-packages recursively.  It defaults to disabled.
+     For example, ::
+
+         .. autosummary::
+            :recursive:
+
+            sphinx.environment.BuildEnvironment
+
+     .. versionadded:: 3.1
+
+
+:program:`sphinx-autogen` -- generate autodoc stub pages
+--------------------------------------------------------
+
+The :program:`sphinx-autogen` script can be used to conveniently generate stub
+documentation pages for items included in :rst:dir:`autosummary` listings.
+
+For example, the command ::
+
+    $ sphinx-autogen -o generated *.rst
+
+will read all :rst:dir:`autosummary` tables in the :file:`*.rst` files that have
+the ``:toctree:`` option set, and output corresponding stub pages in directory
+``generated`` for all documented items.  The generated pages by default contain
+text of the form::
+
+    sphinx.util.relative_uri
+    ========================
+
+    .. autofunction:: sphinx.util.relative_uri
+
+If the ``-o`` option is not given, the script will place the output files in the
+directories specified in the ``:toctree:`` options.
+
+For more information, refer to the :doc:`sphinx-autogen documentation
+</man/sphinx-autogen>`
+
+
+Generating stub pages automatically
+-----------------------------------
+
+If you do not want to create stub pages with :program:`sphinx-autogen`, you can
+also use these config values:
+
+.. confval:: autosummary_context
+
+   A dictionary of values to pass into the template engine's context for
+   autosummary stubs files.
+
+   .. versionadded:: 3.1
+
+.. confval:: autosummary_generate
+
+   Boolean indicating whether to scan all found documents for autosummary
+   directives, and to generate stub pages for each. It is enabled by default.
+
+   Can also be a list of documents for which stub pages should be generated.
+
+   The new files will be placed in the directories specified in the
+   ``:toctree:`` options of the directives.
+
+   .. versionchanged:: 2.3
+
+      Emits :event:`autodoc-skip-member` event as :mod:`~sphinx.ext.autodoc`
+      does.
+
+   .. versionchanged:: 4.0
+
+      Enabled by default.
+
+.. confval:: autosummary_generate_overwrite
+
+   If true, autosummary overwrites existing files by generated stub pages.
+   Defaults to true (enabled).
+
+   .. versionadded:: 3.0
+
+.. confval:: autosummary_mock_imports
+
+   This value contains a list of modules to be mocked up.  See
+   :confval:`autodoc_mock_imports` for more details.  It defaults to
+   :confval:`autodoc_mock_imports`.
+
+   .. versionadded:: 2.0
+
+.. confval:: autosummary_imported_members
+
+   A boolean flag indicating whether to document classes and functions imported
+   in modules. Default is ``False``
+
+   .. versionadded:: 2.1
+
+   .. versionchanged:: 4.4
+
+      If ``autosummary_ignore_module_all`` is ``False``, this configuration
+      value is ignored for members listed in ``__all__``.
+
+.. confval:: autosummary_ignore_module_all
+
+   If ``False`` and a module has the ``__all__`` attribute set, autosummary
+   documents every member listed in ``__all__`` and no others. Default is
+   ``True``
+
+   Note that if an imported member is listed in ``__all__``, it will be
+   documented regardless of the value of ``autosummary_imported_members``. To
+   match the behaviour of ``from module import *``, set
+   ``autosummary_ignore_module_all`` to False and
+   ``autosummary_imported_members`` to True.
+
+   .. versionadded:: 4.4
+
+.. confval:: autosummary_filename_map
+
+   A dict mapping object names to filenames. This is necessary to avoid
+   filename conflicts where multiple objects have names that are
+   indistinguishable when case is ignored, on file systems where filenames
+   are case-insensitive.
+
+   .. versionadded:: 3.2
+
+.. _autosummary-customizing-templates:
+
+Customizing templates
+---------------------
+
+.. versionadded:: 1.0
+
+You can customize the stub page templates, in a similar way as the HTML Jinja
+templates, see :ref:`templating`. (:class:`~sphinx.application.TemplateBridge`
+is not supported.)
+
+.. note::
+
+   If you find yourself spending much time tailoring the stub templates, this
+   may indicate that it's a better idea to write custom narrative documentation
+   instead.
+
+Autosummary uses the following Jinja template files:
+
+- :file:`autosummary/base.rst` -- fallback template
+- :file:`autosummary/module.rst` -- template for modules
+- :file:`autosummary/class.rst` -- template for classes
+- :file:`autosummary/function.rst` -- template for functions
+- :file:`autosummary/attribute.rst` -- template for class attributes
+- :file:`autosummary/method.rst` -- template for class methods
+
+The following variables are available in the templates:
+
+.. currentmodule:: None
+
+.. data:: name
+
+   Name of the documented object, excluding the module and class parts.
+
+.. data:: objname
+
+   Name of the documented object, excluding the module parts.
+
+.. data:: fullname
+
+   Full name of the documented object, including module and class parts.
+
+.. data:: objtype
+
+   Type of the documented object, one of ``"module"``, ``"function"``,
+   ``"class"``, ``"method"``, ``"attribute"``, ``"data"``, ``"object"``,
+   ``"exception"``, ``"newvarattribute"``, ``"newtypedata"``, ``"property"``.
+
+.. data:: module
+
+   Name of the module the documented object belongs to.
+
+.. data:: class
+
+   Name of the class the documented object belongs to.  Only available for
+   methods and attributes.
+
+.. data:: underline
+
+   A string containing ``len(full_name) * '='``. Use the ``underline`` filter
+   instead.
+
+.. data:: members
+
+   List containing names of all members of the module or class.  Only available
+   for modules and classes.
+
+.. data:: inherited_members
+
+   List containing names of all inherited members of class.  Only available for
+   classes.
+
+   .. versionadded:: 1.8.0
+
+.. data:: functions
+
+   List containing names of "public" functions in the module.  Here, "public"
+   means that the name does not start with an underscore. Only available
+   for modules.
+
+.. data:: classes
+
+   List containing names of "public" classes in the module.  Only available for
+   modules.
+
+.. data:: exceptions
+
+   List containing names of "public" exceptions in the module.  Only available
+   for modules.
+
+.. data:: methods
+
+   List containing names of "public" methods in the class.  Only available for
+   classes.
+
+.. data:: attributes
+
+   List containing names of "public" attributes in the class/module.  Only
+   available for classes and modules.
+
+   .. versionchanged:: 3.1
+
+      Attributes of modules are supported.
+
+.. data:: modules
+
+   List containing names of "public" modules in the package.  Only available for
+   modules that are packages and the ``recursive`` option is on.
+
+   .. versionadded:: 3.1
+
+Additionally, the following filters are available
+
+.. function:: escape(s)
+
+   Escape any special characters in the text to be used in formatting RST
+   contexts. For instance, this prevents asterisks making things bold. This
+   replaces the builtin Jinja `escape filter`_ that does html-escaping.
+
+.. function:: underline(s, line='=')
+   :no-index:
+
+   Add a title underline to a piece of text.
+
+For instance, ``{{ fullname | escape | underline }}`` should be used to produce
+the title of a page.
+
+.. note::
+
+   You can use the :rst:dir:`autosummary` directive in the stub pages.
+   Stub pages are generated also based on these directives.
+
+.. _`escape filter`: https://jinja.palletsprojects.com/en/3.0.x/templates/#jinja-filters.escape
diff --git a/doc/usage/extensions/coverage.rst b/doc/usage/extensions/coverage.rst
new file mode 100644
index 0000000..1390ebf
--- /dev/null
+++ b/doc/usage/extensions/coverage.rst
@@ -0,0 +1,99 @@
+:mod:`sphinx.ext.coverage` -- Collect doc coverage stats
+========================================================
+
+.. module:: sphinx.ext.coverage
+   :synopsis: Check Python modules and C API for coverage in the documentation.
+
+This extension features one additional builder, the :class:`CoverageBuilder`.
+
+.. class:: CoverageBuilder
+
+   To use this builder, activate the coverage extension in your configuration
+   file and give ``-b coverage`` on the command line.
+
+.. todo:: Write this section.
+
+Several configuration values can be used to specify what the builder
+should check:
+
+.. confval:: coverage_ignore_modules
+
+.. confval:: coverage_ignore_functions
+
+.. confval:: coverage_ignore_classes
+
+.. confval:: coverage_ignore_pyobjects
+
+   List of `Python regular expressions`_.
+
+   If any of these regular expressions matches any part of the full import path
+   of a Python object, that Python object is excluded from the documentation
+   coverage report.
+
+   .. _Python regular expressions: https://docs.python.org/library/re
+
+   .. versionadded:: 2.1
+
+.. confval:: coverage_c_path
+
+.. confval:: coverage_c_regexes
+
+.. confval:: coverage_ignore_c_items
+
+.. confval:: coverage_write_headline
+
+   Set to ``False`` to not write headlines.
+
+   .. versionadded:: 1.1
+
+.. confval:: coverage_skip_undoc_in_source
+
+   Skip objects that are not documented in the source with a docstring.
+   ``False`` by default.
+
+   .. versionadded:: 1.1
+
+.. confval:: coverage_show_missing_items
+
+   Print objects that are missing to standard output also.
+   ``False`` by default.
+
+   .. versionadded:: 3.1
+
+.. confval:: coverage_statistics_to_report
+
+   Print a tabluar report of the coverage statistics to the coverage report.
+   ``True`` by default.
+
+   Example output:
+
+   .. code-block:: text
+
+      +-----------------------+----------+--------------+
+      | Module                | Coverage | Undocumented |
+      +=======================+==========+==============+
+      | package.foo_module    | 100.00%  | 0            |
+      +-----------------------+----------+--------------+
+      | package.bar_module    | 83.33%   | 1            |
+      +-----------------------+----------+--------------+
+
+   .. versionadded:: 7.2
+
+.. confval:: coverage_statistics_to_stdout
+
+   Print a tabluar report of the coverage statistics to standard output.
+   ``False`` by default.
+
+   Example output:
+
+   .. code-block:: text
+
+      +-----------------------+----------+--------------+
+      | Module                | Coverage | Undocumented |
+      +=======================+==========+==============+
+      | package.foo_module    | 100.00%  | 0            |
+      +-----------------------+----------+--------------+
+      | package.bar_module    | 83.33%   | 1            |
+      +-----------------------+----------+--------------+
+
+   .. versionadded:: 7.2
diff --git a/doc/usage/extensions/doctest.rst b/doc/usage/extensions/doctest.rst
new file mode 100644
index 0000000..1848e1f
--- /dev/null
+++ b/doc/usage/extensions/doctest.rst
@@ -0,0 +1,385 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.doctest` -- Test snippets in the documentation
+===============================================================
+
+.. module:: sphinx.ext.doctest
+   :synopsis: Test snippets in the documentation.
+
+.. index:: pair: automatic; testing
+           single: doctest
+           pair: testing; snippets
+
+
+It is often helpful to include snippets of code in your documentation and
+demonstrate the results of executing them. But it is important to ensure that
+the documentation stays up-to-date with the code.
+
+This extension allows you to test such code snippets in the documentation in
+a natural way.  If you mark the code blocks as shown here, the ``doctest``
+builder will collect them and run them as doctest tests.
+
+Within each document, you can assign each snippet to a *group*. Each group
+consists of:
+
+* zero or more *setup code* blocks (e.g. importing the module to test)
+* one or more *test* blocks
+
+When building the docs with the ``doctest`` builder, groups are collected for
+each document and run one after the other, first executing setup code blocks,
+then the test blocks in the order they appear in the file.
+
+There are two kinds of test blocks:
+
+* *doctest-style* blocks mimic interactive sessions by interleaving Python code
+  (including the interpreter prompt) and output.
+
+* *code-output-style* blocks consist of an ordinary piece of Python code, and
+  optionally, a piece of output for that code.
+
+
+Directives
+----------
+
+The *group* argument below is interpreted as follows: if it is empty, the block
+is assigned to the group named ``default``.  If it is ``*``, the block is
+assigned to all groups (including the ``default`` group).  Otherwise, it must be
+a comma-separated list of group names.
+
+.. rst:directive:: .. testsetup:: [group]
+
+   A setup code block.  This code is not shown in the output for other builders,
+   but executed before the doctests of the group(s) it belongs to.
+
+
+.. rst:directive:: .. testcleanup:: [group]
+
+   A cleanup code block.  This code is not shown in the output for other
+   builders, but executed after the doctests of the group(s) it belongs to.
+
+   .. versionadded:: 1.1
+
+
+.. rst:directive:: .. doctest:: [group]
+
+   A doctest-style code block.  You can use standard :mod:`doctest` flags for
+   controlling how actual output is compared with what you give as output.  The
+   default set of flags is specified by the :confval:`doctest_default_flags`
+   configuration variable.
+
+   This directive supports five options:
+
+   * ``hide``, a flag option, hides the doctest block in other builders.  By
+     default it is shown as a highlighted doctest block.
+
+   * ``options``, a string option, can be used to give a comma-separated list of
+     doctest flags that apply to each example in the tests.  (You still can give
+     explicit flags per example, with doctest comments, but they will show up in
+     other builders too.)
+
+   * ``pyversion``, a string option, can be used to specify the required Python
+     version for the example to be tested. For instance, in the following case
+     the example will be tested only for Python versions greater than 3.10::
+
+         .. doctest::
+            :pyversion: > 3.10
+
+     The following operands are supported:
+
+     * ``~=``: Compatible release clause
+     * ``==``: Version matching clause
+     * ``!=``: Version exclusion clause
+     * ``<=``, ``>=``: Inclusive ordered comparison clause
+     * ``<``, ``>``: Exclusive ordered comparison clause
+     * ``===``: Arbitrary equality clause.
+
+     ``pyversion`` option is followed :pep:`PEP-440: Version Specifiers
+     <440#version-specifiers>`.
+
+     .. versionadded:: 1.6
+
+     .. versionchanged:: 1.7
+
+        Supported PEP-440 operands and notations
+
+   * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option,
+     doctest flags (comments looking like ``# doctest: FLAG, ...``) at the
+     ends of lines and ``<BLANKLINE>`` markers are removed (or not removed)
+     individually.  Default is ``trim-doctest-flags``.
+
+   Note that like with standard doctests, you have to use ``<BLANKLINE>`` to
+   signal a blank line in the expected output.  The ``<BLANKLINE>`` is removed
+   when building presentation output (HTML, LaTeX etc.).
+
+   Also, you can give inline doctest options, like in doctest::
+
+      >>> datetime.date.now()   # doctest: +SKIP
+      datetime.date(2008, 1, 1)
+
+   They will be respected when the test is run, but stripped from presentation
+   output.
+
+
+.. rst:directive:: .. testcode:: [group]
+
+   A code block for a code-output-style test.
+
+   This directive supports three options:
+
+   * ``hide``, a flag option, hides the code block in other builders.  By
+     default it is shown as a highlighted code block.
+
+   * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option,
+     doctest flags (comments looking like ``# doctest: FLAG, ...``) at the
+     ends of lines and ``<BLANKLINE>`` markers are removed (or not removed)
+     individually.  Default is ``trim-doctest-flags``.
+
+   .. note::
+
+      Code in a ``testcode`` block is always executed all at once, no matter how
+      many statements it contains.  Therefore, output will *not* be generated
+      for bare expressions -- use ``print``.  Example::
+
+          .. testcode::
+
+             1+1         # this will give no output!
+             print(2+2)  # this will give output
+
+          .. testoutput::
+
+             4
+
+      Also, please be aware that since the doctest module does not support
+      mixing regular output and an exception message in the same snippet, this
+      applies to testcode/testoutput as well.
+
+
+.. rst:directive:: .. testoutput:: [group]
+
+   The corresponding output, or the exception message, for the last
+   :rst:dir:`testcode` block.
+
+   This directive supports four options:
+
+   * ``hide``, a flag option, hides the output block in other builders.  By
+     default it is shown as a literal block without highlighting.
+
+   * ``options``, a string option, can be used to give doctest flags
+     (comma-separated) just like in normal doctest blocks.
+
+   * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option,
+     doctest flags (comments looking like ``# doctest: FLAG, ...``) at the
+     ends of lines and ``<BLANKLINE>`` markers are removed (or not removed)
+     individually.  Default is ``trim-doctest-flags``.
+
+   Example::
+
+      .. testcode::
+
+         print('Output     text.')
+
+      .. testoutput::
+         :hide:
+         :options: -ELLIPSIS, +NORMALIZE_WHITESPACE
+
+         Output text.
+
+The following is an example for the usage of the directives.  The test via
+:rst:dir:`doctest` and the test via :rst:dir:`testcode` and
+:rst:dir:`testoutput` are equivalent. ::
+
+   The parrot module
+   =================
+
+   .. testsetup:: *
+
+      import parrot
+
+   The parrot module is a module about parrots.
+
+   Doctest example:
+
+   .. doctest::
+
+      >>> parrot.voom(3000)
+      This parrot wouldn't voom if you put 3000 volts through it!
+
+   Test-Output example:
+
+   .. testcode::
+
+      parrot.voom(3000)
+
+   This would output:
+
+   .. testoutput::
+
+      This parrot wouldn't voom if you put 3000 volts through it!
+
+
+Skipping tests conditionally
+----------------------------
+
+``skipif``, a string option, can be used to skip directives conditionally. This
+may be useful e.g. when a different set of tests should be run depending on the
+environment (hardware, network/VPN, optional dependencies or different versions
+of dependencies). The ``skipif`` option is supported by all of the doctest
+directives. Below are typical use cases for ``skipif`` when used for different
+directives:
+
+- :rst:dir:`testsetup` and :rst:dir:`testcleanup`
+
+  - conditionally skip test setup and/or cleanup
+  - customize setup/cleanup code per environment
+
+- :rst:dir:`doctest`
+
+  - conditionally skip both a test and its output verification
+
+- :rst:dir:`testcode`
+
+  - conditionally skip a test
+  - customize test code per environment
+
+- :rst:dir:`testoutput`
+
+  - conditionally skip output assertion for a skipped test
+  - expect different output depending on the environment
+
+The value of the ``skipif`` option is evaluated as a Python expression. If the
+result is a true value, the directive is omitted from the test run just as if
+it wasn't present in the file at all.
+
+Instead of repeating an expression, the :confval:`doctest_global_setup`
+configuration option can be used to assign it to a variable which can then be
+used instead.
+
+Here's an example which skips some tests if Pandas is not installed:
+
+.. code-block:: py
+   :caption: conf.py
+
+   extensions = ['sphinx.ext.doctest']
+   doctest_global_setup = '''
+   try:
+       import pandas as pd
+   except ImportError:
+       pd = None
+   '''
+
+.. code-block:: rst
+   :caption: contents.rst
+
+   .. testsetup::
+      :skipif: pd is None
+
+      data = pd.Series([42])
+
+   .. doctest::
+      :skipif: pd is None
+
+      >>> data.iloc[0]
+      42
+
+   .. testcode::
+      :skipif: pd is None
+
+      print(data.iloc[-1])
+
+   .. testoutput::
+      :skipif: pd is None
+
+      42
+
+
+Configuration
+-------------
+
+The doctest extension uses the following configuration values:
+
+.. confval:: doctest_default_flags
+
+   By default, these options are enabled:
+
+   - ``ELLIPSIS``, allowing you to put ellipses in the expected output that
+     match anything in the actual output;
+   - ``IGNORE_EXCEPTION_DETAIL``, causing everything following the leftmost
+     colon and any module information in the exception name to be ignored;
+   - ``DONT_ACCEPT_TRUE_FOR_1``, rejecting "True" in the output where "1" is
+     given -- the default behavior of accepting this substitution is a relic of
+     pre-Python 2.2 times.
+
+   .. versionadded:: 1.5
+
+.. confval:: doctest_show_successes
+
+   Defaults to ``True``.
+   Controls whether successes are reported.
+
+   For a project with many doctests,
+   it may be useful to set this to ``False`` to only highlight failures.
+
+   .. versionadded:: 7.2
+
+.. confval:: doctest_path
+
+   A list of directories that will be added to :data:`sys.path` when the doctest
+   builder is used.  (Make sure it contains absolute paths.)
+
+.. confval:: doctest_global_setup
+
+   Python code that is treated like it were put in a ``testsetup`` directive for
+   *every* file that is tested, and for every group.  You can use this to
+   e.g. import modules you will always need in your doctests.
+
+   .. versionadded:: 0.6
+
+.. confval:: doctest_global_cleanup
+
+   Python code that is treated like it were put in a ``testcleanup`` directive
+   for *every* file that is tested, and for every group.  You can use this to
+   e.g. remove any temporary files that the tests leave behind.
+
+   .. versionadded:: 1.1
+
+.. confval:: doctest_test_doctest_blocks
+
+   If this is a nonempty string (the default is ``'default'``), standard reST
+   doctest blocks will be tested too.  They will be assigned to the group name
+   given.
+
+   reST doctest blocks are simply doctests put into a paragraph of their own,
+   like so::
+
+      Some documentation text.
+
+      >>> print(1)
+      1
+
+      Some more documentation text.
+
+   (Note that no special ``::`` is used to introduce a doctest block; docutils
+   recognizes them from the leading ``>>>``.  Also, no additional indentation is
+   used, though it doesn't hurt.)
+
+   If this value is left at its default value, the above snippet is interpreted
+   by the doctest builder exactly like the following::
+
+      Some documentation text.
+
+      .. doctest::
+
+         >>> print(1)
+         1
+
+      Some more documentation text.
+
+   This feature makes it easy for you to test doctests in docstrings included
+   with the :mod:`~sphinx.ext.autodoc` extension without marking them up with a
+   special directive.
+
+   Note though that you can't have blank lines in reST doctest blocks.  They
+   will be interpreted as one block ending and another one starting.  Also,
+   removal of ``<BLANKLINE>`` and ``# doctest:`` options only works in
+   :rst:dir:`doctest` blocks, though you may set :confval:`trim_doctest_flags`
+   to achieve that in all code blocks with Python console content.
diff --git a/doc/usage/extensions/duration.rst b/doc/usage/extensions/duration.rst
new file mode 100644
index 0000000..1213811
--- /dev/null
+++ b/doc/usage/extensions/duration.rst
@@ -0,0 +1,11 @@
+:mod:`sphinx.ext.duration` -- Measure durations of Sphinx processing
+====================================================================
+
+.. module:: sphinx.ext.duration
+   :synopsis: Measure durations of Sphinx processing
+
+.. versionadded:: 2.4
+
+This extension measures durations of Sphinx processing and show its
+result at end of the build.  It is useful for inspecting what document
+is slowly built.
diff --git a/doc/usage/extensions/example_google.py b/doc/usage/extensions/example_google.py
new file mode 100644
index 0000000..434fa3b
--- /dev/null
+++ b/doc/usage/extensions/example_google.py
@@ -0,0 +1,309 @@
+"""Example Google style docstrings.
+
+This module demonstrates documentation as specified by the `Google Python
+Style Guide`_. Docstrings may extend over multiple lines. Sections are created
+with a section header and a colon followed by a block of indented text.
+
+Example:
+    Examples can be given using either the ``Example`` or ``Examples``
+    sections. Sections support any reStructuredText formatting, including
+    literal blocks::
+
+        $ python example_google.py
+
+Section breaks are created by resuming unindented text. Section breaks
+are also implicitly created anytime a new section starts.
+
+Attributes:
+    module_level_variable1 (int): Module level variables may be documented in
+        either the ``Attributes`` section of the module docstring, or in an
+        inline docstring immediately following the variable.
+
+        Either form is acceptable, but the two should not be mixed. Choose
+        one convention to document module level variables and be consistent
+        with it.
+
+Todo:
+    * For module TODOs
+    * You have to also use ``sphinx.ext.todo`` extension
+
+.. _Google Python Style Guide:
+   https://google.github.io/styleguide/pyguide.html
+
+"""
+
+module_level_variable1 = 12345
+
+module_level_variable2 = 98765
+"""int: Module level variable documented inline.
+
+The docstring may span multiple lines. The type may optionally be specified
+on the first line, separated by a colon.
+"""
+
+
+def function_with_types_in_docstring(param1, param2):
+    """Example function with types documented in the docstring.
+
+    :pep:`484` type annotations are supported. If attribute, parameter, and
+    return types are annotated according to `PEP 484`_, they do not need to be
+    included in the docstring:
+
+    Args:
+        param1 (int): The first parameter.
+        param2 (str): The second parameter.
+
+    Returns:
+        bool: The return value. True for success, False otherwise.
+    """
+
+
+def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
+    """Example function with PEP 484 type annotations.
+
+    Args:
+        param1: The first parameter.
+        param2: The second parameter.
+
+    Returns:
+        The return value. True for success, False otherwise.
+
+    """
+
+
+def module_level_function(param1, param2=None, *args, **kwargs):
+    """This is an example of a module level function.
+
+    Function parameters should be documented in the ``Args`` section. The name
+    of each parameter is required. The type and description of each parameter
+    is optional, but should be included if not obvious.
+
+    If ``*args`` or ``**kwargs`` are accepted,
+    they should be listed as ``*args`` and ``**kwargs``.
+
+    The format for a parameter is::
+
+        name (type): description
+            The description may span multiple lines. Following
+            lines should be indented. The "(type)" is optional.
+
+            Multiple paragraphs are supported in parameter
+            descriptions.
+
+    Args:
+        param1 (int): The first parameter.
+        param2 (:obj:`str`, optional): The second parameter. Defaults to None.
+            Second line of description should be indented.
+        *args: Variable length argument list.
+        **kwargs: Arbitrary keyword arguments.
+
+    Returns:
+        bool: True if successful, False otherwise.
+
+        The return type is optional and may be specified at the beginning of
+        the ``Returns`` section followed by a colon.
+
+        The ``Returns`` section may span multiple lines and paragraphs.
+        Following lines should be indented to match the first line.
+
+        The ``Returns`` section supports any reStructuredText formatting,
+        including literal blocks::
+
+            {
+                'param1': param1,
+                'param2': param2
+            }
+
+    Raises:
+        AttributeError: The ``Raises`` section is a list of all exceptions
+            that are relevant to the interface.
+        ValueError: If `param2` is equal to `param1`.
+
+    """
+    if param1 == param2:
+        raise ValueError('param1 may not be equal to param2')
+    return True
+
+
+def example_generator(n):
+    """Generators have a ``Yields`` section instead of a ``Returns`` section.
+
+    Args:
+        n (int): The upper limit of the range to generate, from 0 to `n` - 1.
+
+    Yields:
+        int: The next number in the range of 0 to `n` - 1.
+
+    Examples:
+        Examples should be written in doctest format, and should illustrate how
+        to use the function.
+
+        >>> print([i for i in example_generator(4)])
+        [0, 1, 2, 3]
+
+    """
+    yield from range(n)
+
+
+class ExampleError(Exception):
+    """Exceptions are documented in the same way as classes.
+
+    The __init__ method may be documented in either the class level
+    docstring, or as a docstring on the __init__ method itself.
+
+    Either form is acceptable, but the two should not be mixed. Choose one
+    convention to document the __init__ method and be consistent with it.
+
+    Note:
+        Do not include the `self` parameter in the ``Args`` section.
+
+    Args:
+        msg (str): Human readable string describing the exception.
+        code (:obj:`int`, optional): Error code.
+
+    Attributes:
+        msg (str): Human readable string describing the exception.
+        code (int): Exception error code.
+
+    """
+
+    def __init__(self, msg, code):
+        self.msg = msg
+        self.code = code
+
+
+class ExampleClass:
+    """The summary line for a class docstring should fit on one line.
+
+    If the class has public attributes, they may be documented here
+    in an ``Attributes`` section and follow the same formatting as a
+    function's ``Args`` section. Alternatively, attributes may be documented
+    inline with the attribute's declaration (see __init__ method below).
+
+    Properties created with the ``@property`` decorator should be documented
+    in the property's getter method.
+
+    Attributes:
+        attr1 (str): Description of `attr1`.
+        attr2 (:obj:`int`, optional): Description of `attr2`.
+
+    """
+
+    def __init__(self, param1, param2, param3):
+        """Example of docstring on the __init__ method.
+
+        The __init__ method may be documented in either the class level
+        docstring, or as a docstring on the __init__ method itself.
+
+        Either form is acceptable, but the two should not be mixed. Choose one
+        convention to document the __init__ method and be consistent with it.
+
+        Note:
+            Do not include the `self` parameter in the ``Args`` section.
+
+        Args:
+            param1 (str): Description of `param1`.
+            param2 (:obj:`int`, optional): Description of `param2`. Multiple
+                lines are supported.
+            param3 (list(str)): Description of `param3`.
+
+        """
+        self.attr1 = param1
+        self.attr2 = param2
+        self.attr3 = param3  #: Doc comment *inline* with attribute
+
+        #: list(str): Doc comment *before* attribute, with type specified
+        self.attr4 = ['attr4']
+
+        self.attr5 = None
+        """str: Docstring *after* attribute, with type specified."""
+
+    @property
+    def readonly_property(self):
+        """str: Properties should be documented in their getter method."""
+        return 'readonly_property'
+
+    @property
+    def readwrite_property(self):
+        """list(str): Properties with both a getter and setter
+        should only be documented in their getter method.
+
+        If the setter method contains notable behavior, it should be
+        mentioned here.
+        """
+        return ['readwrite_property']
+
+    @readwrite_property.setter
+    def readwrite_property(self, value):
+        value
+
+    def example_method(self, param1, param2):
+        """Class methods are similar to regular functions.
+
+        Note:
+            Do not include the `self` parameter in the ``Args`` section.
+
+        Args:
+            param1: The first parameter.
+            param2: The second parameter.
+
+        Returns:
+            True if successful, False otherwise.
+
+        """
+        return True
+
+    def __special__(self):
+        """By default special members with docstrings are not included.
+
+        Special members are any methods or attributes that start with and
+        end with a double underscore. Any special member with a docstring
+        will be included in the output, if
+        ``napoleon_include_special_with_doc`` is set to True.
+
+        This behavior can be enabled by changing the following setting in
+        Sphinx's conf.py::
+
+            napoleon_include_special_with_doc = True
+
+        """
+        pass
+
+    def __special_without_docstring__(self):
+        pass
+
+    def _private(self):
+        """By default private members are not included.
+
+        Private members are any methods or attributes that start with an
+        underscore and are *not* special. By default they are not included
+        in the output.
+
+        This behavior can be changed such that private members *are* included
+        by changing the following setting in Sphinx's conf.py::
+
+            napoleon_include_private_with_doc = True
+
+        """
+        pass
+
+    def _private_without_docstring(self):
+        pass
+
+class ExamplePEP526Class:
+    """The summary line for a class docstring should fit on one line.
+
+    If the class has public attributes, they may be documented here
+    in an ``Attributes`` section and follow the same formatting as a
+    function's ``Args`` section. If ``napoleon_attr_annotations``
+    is True, types can be specified in the class body using ``PEP 526``
+    annotations.
+
+    Attributes:
+        attr1: Description of `attr1`.
+        attr2: Description of `attr2`.
+
+    """
+
+    attr1: str
+    attr2: int
diff --git a/doc/usage/extensions/example_google.rst b/doc/usage/extensions/example_google.rst
new file mode 100644
index 0000000..a06f161
--- /dev/null
+++ b/doc/usage/extensions/example_google.rst
@@ -0,0 +1,17 @@
+:orphan:
+
+.. _example_google:
+
+Example Google Style Python Docstrings
+======================================
+
+.. seealso::
+
+   :ref:`example_numpy`
+
+.. only:: builder_html
+
+   Download: :download:`example_google.py <example_google.py>`
+
+.. literalinclude:: example_google.py
+   :language: python
diff --git a/doc/usage/extensions/example_numpy.py b/doc/usage/extensions/example_numpy.py
new file mode 100644
index 0000000..2346b1e
--- /dev/null
+++ b/doc/usage/extensions/example_numpy.py
@@ -0,0 +1,350 @@
+"""Example NumPy style docstrings.
+
+This module demonstrates documentation as specified by the `NumPy
+Documentation HOWTO`_. Docstrings may extend over multiple lines. Sections
+are created with a section header followed by an underline of equal length.
+
+Example
+-------
+Examples can be given using either the ``Example`` or ``Examples``
+sections. Sections support any reStructuredText formatting, including
+literal blocks::
+
+    $ python example_numpy.py
+
+
+Section breaks are created with two blank lines. Section breaks are also
+implicitly created anytime a new section starts. Section bodies *may* be
+indented:
+
+Notes
+-----
+    This is an example of an indented section. It's like any other section,
+    but the body is indented to help it stand out from surrounding text.
+
+If a section is indented, then a section break is created by
+resuming unindented text.
+
+Attributes
+----------
+module_level_variable1 : int
+    Module level variables may be documented in either the ``Attributes``
+    section of the module docstring, or in an inline docstring immediately
+    following the variable.
+
+    Either form is acceptable, but the two should not be mixed. Choose
+    one convention to document module level variables and be consistent
+    with it.
+
+
+.. _NumPy docstring standard:
+   https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
+
+"""
+
+module_level_variable1 = 12345
+
+module_level_variable2 = 98765
+"""int: Module level variable documented inline.
+
+The docstring may span multiple lines. The type may optionally be specified
+on the first line, separated by a colon.
+"""
+
+
+def function_with_types_in_docstring(param1, param2):
+    """Example function with types documented in the docstring.
+
+    :pep:`484` type annotations are supported. If attribute, parameter, and
+    return types are annotated according to `PEP 484`_, they do not need to be
+    included in the docstring:
+
+    Parameters
+    ----------
+    param1 : int
+        The first parameter.
+    param2 : str
+        The second parameter.
+
+    Returns
+    -------
+    bool
+        True if successful, False otherwise.
+    """
+
+
+def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
+    """Example function with PEP 484 type annotations.
+
+    The return type must be duplicated in the docstring to comply
+    with the NumPy docstring style.
+
+    Parameters
+    ----------
+    param1
+        The first parameter.
+    param2
+        The second parameter.
+
+    Returns
+    -------
+    bool
+        True if successful, False otherwise.
+
+    """
+
+
+def module_level_function(param1, param2=None, *args, **kwargs):
+    """This is an example of a module level function.
+
+    Function parameters should be documented in the ``Parameters`` section.
+    The name of each parameter is required. The type and description of each
+    parameter is optional, but should be included if not obvious.
+
+    If ``*args`` or ``**kwargs`` are accepted,
+    they should be listed as ``*args`` and ``**kwargs``.
+
+    The format for a parameter is::
+
+        name : type
+            description
+
+            The description may span multiple lines. Following lines
+            should be indented to match the first line of the description.
+            The ": type" is optional.
+
+            Multiple paragraphs are supported in parameter
+            descriptions.
+
+    Parameters
+    ----------
+    param1 : int
+        The first parameter.
+    param2 : :obj:`str`, optional
+        The second parameter.
+    *args
+        Variable length argument list.
+    **kwargs
+        Arbitrary keyword arguments.
+
+    Returns
+    -------
+    bool
+        True if successful, False otherwise.
+
+        The return type is not optional. The ``Returns`` section may span
+        multiple lines and paragraphs. Following lines should be indented to
+        match the first line of the description.
+
+        The ``Returns`` section supports any reStructuredText formatting,
+        including literal blocks::
+
+            {
+                'param1': param1,
+                'param2': param2
+            }
+
+    Raises
+    ------
+    AttributeError
+        The ``Raises`` section is a list of all exceptions
+        that are relevant to the interface.
+    ValueError
+        If `param2` is equal to `param1`.
+
+    """
+    if param1 == param2:
+        raise ValueError('param1 may not be equal to param2')
+    return True
+
+
+def example_generator(n):
+    """Generators have a ``Yields`` section instead of a ``Returns`` section.
+
+    Parameters
+    ----------
+    n : int
+        The upper limit of the range to generate, from 0 to `n` - 1.
+
+    Yields
+    ------
+    int
+        The next number in the range of 0 to `n` - 1.
+
+    Examples
+    --------
+    Examples should be written in doctest format, and should illustrate how
+    to use the function.
+
+    >>> print([i for i in example_generator(4)])
+    [0, 1, 2, 3]
+
+    """
+    yield from range(n)
+
+
+class ExampleError(Exception):
+    """Exceptions are documented in the same way as classes.
+
+    The __init__ method may be documented in either the class level
+    docstring, or as a docstring on the __init__ method itself.
+
+    Either form is acceptable, but the two should not be mixed. Choose one
+    convention to document the __init__ method and be consistent with it.
+
+    Note
+    ----
+    Do not include the `self` parameter in the ``Parameters`` section.
+
+    Parameters
+    ----------
+    msg : str
+        Human readable string describing the exception.
+    code : :obj:`int`, optional
+        Numeric error code.
+
+    Attributes
+    ----------
+    msg : str
+        Human readable string describing the exception.
+    code : int
+        Numeric error code.
+
+    """
+
+    def __init__(self, msg, code):
+        self.msg = msg
+        self.code = code
+
+
+class ExampleClass:
+    """The summary line for a class docstring should fit on one line.
+
+    If the class has public attributes, they may be documented here
+    in an ``Attributes`` section and follow the same formatting as a
+    function's ``Args`` section. Alternatively, attributes may be documented
+    inline with the attribute's declaration (see __init__ method below).
+
+    Properties created with the ``@property`` decorator should be documented
+    in the property's getter method.
+
+    Attributes
+    ----------
+    attr1 : str
+        Description of `attr1`.
+    attr2 : :obj:`int`, optional
+        Description of `attr2`.
+
+    """
+
+    def __init__(self, param1, param2, param3):
+        """Example of docstring on the __init__ method.
+
+        The __init__ method may be documented in either the class level
+        docstring, or as a docstring on the __init__ method itself.
+
+        Either form is acceptable, but the two should not be mixed. Choose one
+        convention to document the __init__ method and be consistent with it.
+
+        Note
+        ----
+        Do not include the `self` parameter in the ``Parameters`` section.
+
+        Parameters
+        ----------
+        param1 : str
+            Description of `param1`.
+        param2 : list(str)
+            Description of `param2`. Multiple
+            lines are supported.
+        param3 : :obj:`int`, optional
+            Description of `param3`.
+
+        """
+        self.attr1 = param1
+        self.attr2 = param2
+        self.attr3 = param3  #: Doc comment *inline* with attribute
+
+        #: list(str): Doc comment *before* attribute, with type specified
+        self.attr4 = ["attr4"]
+
+        self.attr5 = None
+        """str: Docstring *after* attribute, with type specified."""
+
+    @property
+    def readonly_property(self):
+        """str: Properties should be documented in their getter method."""
+        return "readonly_property"
+
+    @property
+    def readwrite_property(self):
+        """list(str): Properties with both a getter and setter
+        should only be documented in their getter method.
+
+        If the setter method contains notable behavior, it should be
+        mentioned here.
+        """
+        return ["readwrite_property"]
+
+    @readwrite_property.setter
+    def readwrite_property(self, value):
+        value
+
+    def example_method(self, param1, param2):
+        """Class methods are similar to regular functions.
+
+        Note
+        ----
+        Do not include the `self` parameter in the ``Parameters`` section.
+
+        Parameters
+        ----------
+        param1
+            The first parameter.
+        param2
+            The second parameter.
+
+        Returns
+        -------
+        bool
+            True if successful, False otherwise.
+
+        """
+        return True
+
+    def __special__(self):
+        """By default special members with docstrings are not included.
+
+        Special members are any methods or attributes that start with and
+        end with a double underscore. Any special member with a docstring
+        will be included in the output, if
+        ``napoleon_include_special_with_doc`` is set to True.
+
+        This behavior can be enabled by changing the following setting in
+        Sphinx's conf.py::
+
+            napoleon_include_special_with_doc = True
+
+        """
+        pass
+
+    def __special_without_docstring__(self):
+        pass
+
+    def _private(self):
+        """By default private members are not included.
+
+        Private members are any methods or attributes that start with an
+        underscore and are *not* special. By default they are not included
+        in the output.
+
+        This behavior can be changed such that private members *are* included
+        by changing the following setting in Sphinx's conf.py::
+
+            napoleon_include_private_with_doc = True
+
+        """
+        pass
+
+    def _private_without_docstring(self):
+        pass
diff --git a/doc/usage/extensions/example_numpy.rst b/doc/usage/extensions/example_numpy.rst
new file mode 100644
index 0000000..38d3439
--- /dev/null
+++ b/doc/usage/extensions/example_numpy.rst
@@ -0,0 +1,17 @@
+:orphan:
+
+.. _example_numpy:
+
+Example NumPy Style Python Docstrings
+======================================
+
+.. seealso::
+
+   :ref:`example_google`
+
+.. only:: builder_html
+
+   Download: :download:`example_numpy.py <example_numpy.py>`
+
+.. literalinclude:: example_numpy.py
+   :language: python
diff --git a/doc/usage/extensions/extlinks.rst b/doc/usage/extensions/extlinks.rst
new file mode 100644
index 0000000..97359ab
--- /dev/null
+++ b/doc/usage/extensions/extlinks.rst
@@ -0,0 +1,69 @@
+:mod:`sphinx.ext.extlinks` -- Markup to shorten external links
+==============================================================
+
+.. module:: sphinx.ext.extlinks
+   :synopsis: Allow inserting external links with common base URLs easily.
+.. moduleauthor:: Georg Brandl
+
+.. versionadded:: 1.0
+
+This extension is meant to help with the common pattern of having many external
+links that point to URLs on one and the same site, e.g. links to bug trackers,
+version control web interfaces, or simply subpages in other websites.  It does
+so by providing aliases to base URLs, so that you only need to give the subpage
+name when creating a link.
+
+Let's assume that you want to include many links to issues at the Sphinx
+tracker, at :samp:`https://github.com/sphinx-doc/sphinx/issues/{num}`.  Typing
+this URL again and again is tedious, so you can use :mod:`~sphinx.ext.extlinks`
+to avoid repeating yourself.
+
+The extension adds a config value:
+
+.. confval:: extlinks
+
+   This config value must be a dictionary of external sites, mapping unique
+   short alias names to a *base URL* and a *caption*.  For example, to create an
+   alias for the above mentioned issues, you would add ::
+
+      extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
+                            'issue %s')}
+
+   Now, you can use the alias name as a new role, e.g. ``:issue:`123```.  This
+   then inserts a link to https://github.com/sphinx-doc/sphinx/issues/123.
+   As you can see, the target given in the role is substituted in the *base URL*
+   in the place of ``%s``.
+
+   The link caption depends on the second item in the tuple, the *caption*:
+
+   - If *caption* is ``None``, the link caption is the full URL.
+   - If *caption* is a string, then it must contain ``%s`` exactly once.  In
+     this case the link caption is *caption* with the partial URL substituted
+     for ``%s`` -- in the above example, the link caption would be
+     ``issue 123``.
+
+   To produce a literal ``%`` in either *base URL* or *caption*, use ``%%``::
+
+      extlinks = {'KnR': ('https://example.org/K%%26R/page/%s',
+                            '[K&R; page %s]')}
+
+   You can also use the usual "explicit title" syntax supported by other roles
+   that generate links, i.e. ``:issue:`this issue <123>```.  In this case, the
+   *caption* is not relevant.
+
+   .. versionchanged:: 4.0
+
+      Support to substitute by '%s' in the caption.
+
+.. note::
+
+   Since links are generated from the role in the reading stage, they appear as
+   ordinary links to e.g. the ``linkcheck`` builder.
+
+.. confval:: extlinks_detect_hardcoded_links
+
+   If enabled, extlinks emits a warning if a hardcoded link is replaceable
+   by an extlink, and suggests a replacement via warning.  It defaults to
+   ``False``.
+
+   .. versionadded:: 4.5
diff --git a/doc/usage/extensions/githubpages.rst b/doc/usage/extensions/githubpages.rst
new file mode 100644
index 0000000..6d56a30
--- /dev/null
+++ b/doc/usage/extensions/githubpages.rst
@@ -0,0 +1,16 @@
+:mod:`sphinx.ext.githubpages` -- Publish HTML docs in GitHub Pages
+==================================================================
+
+.. module:: sphinx.ext.githubpages
+   :synopsis: Publish HTML docs in GitHub Pages
+
+.. versionadded:: 1.4
+
+.. versionchanged:: 2.0
+   Support ``CNAME`` file
+
+This extension creates ``.nojekyll`` file on generated HTML directory to publish
+the document on GitHub Pages.
+
+It also creates a ``CNAME`` file for custom domains when :confval:`html_baseurl`
+set.
diff --git a/doc/usage/extensions/graphviz.rst b/doc/usage/extensions/graphviz.rst
new file mode 100644
index 0000000..c134f6d
--- /dev/null
+++ b/doc/usage/extensions/graphviz.rst
@@ -0,0 +1,239 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.graphviz` -- Add Graphviz graphs
+=================================================
+
+.. module:: sphinx.ext.graphviz
+   :synopsis: Support for Graphviz graphs.
+
+.. versionadded:: 0.6
+
+This extension allows you to embed `Graphviz <https://graphviz.org/>`_ graphs in
+your documents.
+
+It adds these directives:
+
+.. rst:directive:: graphviz
+
+   Directive to embed graphviz code.  The input code for ``dot`` is given as the
+   content.  For example::
+
+      .. graphviz::
+
+         digraph foo {
+            "bar" -> "baz";
+         }
+
+   In HTML output, the code will be rendered to a PNG or SVG image (see
+   :confval:`graphviz_output_format`).  In LaTeX output, the code will be
+   rendered to an embeddable PDF file.
+
+   You can also embed external dot files, by giving the file name as an
+   argument to :rst:dir:`graphviz` and no additional content::
+
+      .. graphviz:: external.dot
+
+   As for all file references in Sphinx, if the filename is absolute, it is
+   taken as relative to the source directory.
+
+   .. versionchanged:: 1.1
+      Added support for external files.
+
+   .. rubric:: options
+
+   .. rst:directive:option:: alt: alternate text
+      :type: text
+
+      The alternate text of the graph.  By default, the graph code is used to
+      the alternate text.
+
+      .. versionadded:: 1.0
+
+   .. rst:directive:option:: align: alignment of the graph
+      :type: left, center or right
+
+      The horizontal alignment of the graph.
+
+      .. versionadded:: 1.5
+
+   .. rst:directive:option:: caption: caption of the graph
+      :type: text
+
+      The caption of the graph.
+
+      .. versionadded:: 1.1
+
+   .. rst:directive:option:: layout: layout type of the graph
+      :type: text
+
+      The layout of the graph (ex. ``dot``, ``neato`` and so on).  A path to the
+      graphviz commands are also allowed.  By default, :confval:`graphviz_dot`
+      is used.
+
+      .. versionadded:: 1.4
+      .. versionchanged:: 2.2
+
+         Renamed from ``graphviz_dot``
+
+   .. rst:directive:option:: name: label
+      :type: text
+
+      The label of the graph.
+
+      .. versionadded:: 1.6
+
+   .. rst:directive:option:: class: class names
+      :type: a list of class names separated by spaces
+
+      The class name of the graph.
+
+      .. versionadded:: 2.4
+
+
+.. rst:directive:: graph
+
+   Directive for embedding a single undirected graph.  The name is given as a
+   directive argument, the contents of the graph are the directive content.
+   This is a convenience directive to generate ``graph <name> { <content> }``.
+
+   For example::
+
+      .. graph:: foo
+
+         "bar" -- "baz";
+
+   .. note:: The graph name is passed unchanged to Graphviz.  If it contains
+      non-alphanumeric characters (e.g. a dash), you will have to double-quote
+      it.
+
+   .. rubric:: options
+
+   Same as :rst:dir:`graphviz`.
+
+   .. rst:directive:option:: alt: alternate text
+      :type: text
+
+      .. versionadded:: 1.0
+
+   .. rst:directive:option:: align: alignment of the graph
+      :type: left, center or right
+
+      .. versionadded:: 1.5
+
+   .. rst:directive:option:: caption: caption of the graph
+      :type: text
+
+      .. versionadded:: 1.1
+
+   .. rst:directive:option:: layout: layout type of the graph
+      :type: text
+
+      .. versionadded:: 1.4
+      .. versionchanged:: 2.2
+
+         Renamed from ``graphviz_dot``
+
+   .. rst:directive:option:: name: label
+      :type: text
+
+      .. versionadded:: 1.6
+
+   .. rst:directive:option:: class: class names
+      :type: a list of class names separated by spaces
+
+      The class name of the graph.
+
+      .. versionadded:: 2.4
+
+
+.. rst:directive:: digraph
+
+   Directive for embedding a single directed graph.  The name is given as a
+   directive argument, the contents of the graph are the directive content.
+   This is a convenience directive to generate ``digraph <name> { <content> }``.
+
+   For example::
+
+      .. digraph:: foo
+
+         "bar" -> "baz" -> "quux";
+
+   .. rubric:: options
+
+   Same as :rst:dir:`graphviz`.
+
+   .. rst:directive:option:: alt: alternate text
+      :type: text
+
+      .. versionadded:: 1.0
+
+   .. rst:directive:option:: align: alignment of the graph
+      :type: left, center or right
+
+      .. versionadded:: 1.5
+
+   .. rst:directive:option:: caption: caption of the graph
+      :type: text
+
+      .. versionadded:: 1.1
+
+   .. rst:directive:option:: layout: layout type of the graph
+      :type: text
+
+      .. versionadded:: 1.4
+      .. versionchanged:: 2.2
+
+         Renamed from ``graphviz_dot``
+
+   .. rst:directive:option:: name: label
+      :type: text
+
+      .. versionadded:: 1.6
+
+   .. rst:directive:option:: class: class names
+      :type: a list of class names separated by spaces
+
+      The class name of the graph.
+
+      .. versionadded:: 2.4
+
+
+There are also these config values:
+
+.. confval:: graphviz_dot
+
+   The command name with which to invoke ``dot``.  The default is ``'dot'``; you
+   may need to set this to a full path if ``dot`` is not in the executable
+   search path.
+
+   Since this setting is not portable from system to system, it is normally not
+   useful to set it in ``conf.py``; rather, giving it on the
+   :program:`sphinx-build` command line via the :option:`-D <sphinx-build -D>`
+   option should be preferable, like this::
+
+      sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html
+
+.. confval:: graphviz_dot_args
+
+   Additional command-line arguments to give to dot, as a list.  The default is
+   an empty list.  This is the right place to set global graph, node or edge
+   attributes via dot's ``-G``, ``-N`` and ``-E`` options.
+
+.. confval:: graphviz_output_format
+
+   The output format for Graphviz when building HTML files.  This must be either
+   ``'png'`` or ``'svg'``; the default is ``'png'``. If ``'svg'`` is used, in
+   order to make the URL links work properly, an appropriate ``target``
+   attribute must be set, such as ``"_top"`` and ``"_blank"``. For example, the
+   link in the following graph should work in the svg output: ::
+
+     .. graphviz::
+
+          digraph example {
+              a [label="sphinx", href="https://www.sphinx-doc.org/", target="_top"];
+              b [label="other"];
+              a -> b;
+          }
+
+   .. versionadded:: 1.0
+      Previously, output always was PNG.
diff --git a/doc/usage/extensions/ifconfig.rst b/doc/usage/extensions/ifconfig.rst
new file mode 100644
index 0000000..837c0b3
--- /dev/null
+++ b/doc/usage/extensions/ifconfig.rst
@@ -0,0 +1,38 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.ifconfig` -- Include content based on configuration
+====================================================================
+
+.. module:: sphinx.ext.ifconfig
+   :synopsis: Include documentation content based on configuration values.
+
+This extension is quite simple, and features only one directive:
+
+.. warning::
+
+   This directive is designed to control only content of document.  It could
+   not control sections, labels and so on.
+
+.. rst:directive:: ifconfig
+
+   Include content of the directive only if the Python expression given as an
+   argument is ``True``, evaluated in the namespace of the project's
+   configuration (that is, all registered variables from :file:`conf.py` are
+   available).
+
+   For example, one could write ::
+
+      .. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
+
+         This stuff is only included in the built docs for unstable versions.
+
+   To make a custom config value known to Sphinx, use
+   :func:`~sphinx.application.Sphinx.add_config_value` in the setup function in
+   :file:`conf.py`, e.g.::
+
+      def setup(app):
+          app.add_config_value('releaselevel', '', 'env')
+
+   The second argument is the default value, the third should always be
+   ``'env'`` for such values (it selects if Sphinx re-reads the documents if the
+   value changes).
diff --git a/doc/usage/extensions/imgconverter.rst b/doc/usage/extensions/imgconverter.rst
new file mode 100644
index 0000000..b9af22d
--- /dev/null
+++ b/doc/usage/extensions/imgconverter.rst
@@ -0,0 +1,55 @@
+.. _sphinx.ext.imgconverter:
+
+:mod:`sphinx.ext.imgconverter` -- A reference image converter using Imagemagick
+===============================================================================
+
+.. module:: sphinx.ext.imgconverter
+   :synopsis: Convert images to appropriate format for builders
+
+.. versionadded:: 1.6
+
+This extension converts images in your document to appropriate format for
+builders.  For example, it allows you to use SVG images with LaTeX builder.
+As a result, you don't mind what image format the builder supports.
+
+By default the extension uses ImageMagick_ to perform conversions,
+and will not work if ImageMagick is not installed.
+
+.. _ImageMagick: https://www.imagemagick.org
+
+.. note::
+
+   ImageMagick rasterizes a SVG image on conversion.  As a result, the image
+   becomes not scalable.  To avoid that, please use other image converters like
+   `sphinxcontrib-svg2pdfconverter`__ (which uses Inkscape or
+   ``rsvg-convert``).
+
+.. __: https://github.com/missinglinkelectronics/sphinxcontrib-svg2pdfconverter
+
+
+Configuration
+-------------
+
+.. confval:: image_converter
+
+   A path to a conversion command.  By default, the imgconverter finds
+   the command from search paths.
+
+   On Unix platforms, the command :command:`convert` is used by default.
+
+   On Windows, the command :command:`magick` is used by default.
+
+   .. versionchanged:: 3.1
+
+      Use :command:`magick` command by default on windows
+
+.. confval:: image_converter_args
+
+   Additional command-line arguments to give to :command:`convert`, as a list.
+   The default is an empty list ``[]``.
+
+   On Windows, it defaults to ``["convert"]``.
+
+   .. versionchanged:: 3.1
+
+      Use ``["convert"]`` by default on Windows
diff --git a/doc/usage/extensions/index.rst b/doc/usage/extensions/index.rst
new file mode 100644
index 0000000..929f2b6
--- /dev/null
+++ b/doc/usage/extensions/index.rst
@@ -0,0 +1,81 @@
+==========
+Extensions
+==========
+
+Since many projects will need special features in their documentation, Sphinx
+allows adding "extensions" to the build process, each of which can modify
+almost any aspect of document processing.
+
+This chapter describes the extensions bundled with Sphinx.  For the API
+documentation on writing your own extension, refer to :ref:`dev-extensions`.
+
+
+.. _builtin-extensions:
+
+Built-in extensions
+-------------------
+
+These extensions are built in and can be activated by respective entries in the
+:confval:`extensions` configuration value:
+
+.. toctree::
+   :maxdepth: 1
+
+   autodoc
+   autosectionlabel
+   autosummary
+   coverage
+   doctest
+   duration
+   extlinks
+   githubpages
+   graphviz
+   ifconfig
+   imgconverter
+   inheritance
+   intersphinx
+   linkcode
+   math
+   napoleon
+   todo
+   viewcode
+
+
+.. _third-party-extensions:
+
+Third-party extensions
+----------------------
+
+You can find several extensions contributed by users in the `sphinx-contrib`__
+organization. If you wish to include your extension in this organization,
+simply follow the instructions provided in the `github-administration`__
+project. This is optional and there are several extensions hosted elsewhere.
+The `awesome-sphinxdoc`__ and `sphinx-extensions`__ projects are both curated
+lists of Sphinx packages, and many packages use the
+`Framework :: Sphinx :: Extension`__ and
+`Framework :: Sphinx :: Theme`__ trove classifiers for Sphinx extensions and
+themes, respectively.
+
+.. __: https://github.com/sphinx-contrib/
+.. __: https://github.com/sphinx-contrib/github-administration
+.. __: https://github.com/yoloseem/awesome-sphinxdoc
+.. __: https://sphinx-extensions.readthedocs.io/en/latest/
+.. __: https://pypi.org/search/?c=Framework+%3A%3A+Sphinx+%3A%3A+Extension
+.. __: https://pypi.org/search/?c=Framework+%3A%3A+Sphinx+%3A%3A+Theme
+
+Where to put your own extensions?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Extensions local to a project should be put within the project's directory
+structure.  Set Python's module search path, ``sys.path``, accordingly so that
+Sphinx can find them.  For example, if your extension ``foo.py`` lies in the
+``exts`` subdirectory of the project root, put into :file:`conf.py`::
+
+   import sys, os
+
+   sys.path.append(os.path.abspath('exts'))
+
+   extensions = ['foo']
+
+You can also install extensions anywhere else on ``sys.path``, e.g. in the
+``site-packages`` directory.
diff --git a/doc/usage/extensions/inheritance.rst b/doc/usage/extensions/inheritance.rst
new file mode 100644
index 0000000..33284b5
--- /dev/null
+++ b/doc/usage/extensions/inheritance.rst
@@ -0,0 +1,174 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.inheritance_diagram` -- Include inheritance diagrams
+=====================================================================
+
+.. module:: sphinx.ext.inheritance_diagram
+   :synopsis: Support for displaying inheritance diagrams via graphviz.
+
+.. versionadded:: 0.6
+
+This extension allows you to include inheritance diagrams, rendered via the
+:mod:`Graphviz extension <sphinx.ext.graphviz>`.
+
+It adds this directive:
+
+.. rst:directive:: inheritance-diagram
+
+   This directive has one or more arguments, each giving a module or class
+   name.  Class names can be unqualified; in that case they are taken to exist
+   in the currently described module (see :rst:dir:`py:module`).
+
+   For each given class, and each class in each given module, the base classes
+   are determined.  Then, from all classes and their base classes, a graph is
+   generated which is then rendered via the graphviz extension to a directed
+   graph.
+
+   This directive supports an option called ``parts`` that, if given, must be an
+   integer, advising the directive to keep that many dot-separated parts
+   in the displayed names (from right to left). For example, ``parts=1`` will
+   only display class names, without the names of the modules that contain
+   them.
+
+   .. versionchanged:: 2.0
+      The value of for ``parts`` can also be negative, indicating how many
+      parts to drop from the left.  For example, if all your class names start
+      with ``lib.``, you can give ``:parts: -1`` to remove that prefix from the
+      displayed node names.
+
+   The directive also supports a ``private-bases`` flag option; if given,
+   private base classes (those whose name starts with ``_``) will be included.
+
+   You can use ``caption`` option to give a caption to the diagram.
+
+   .. versionchanged:: 1.1
+      Added ``private-bases`` option; previously, all bases were always
+      included.
+
+   .. versionchanged:: 1.5
+      Added ``caption`` option
+
+   It also supports a ``top-classes`` option which requires one or more class
+   names separated by comma. If specified inheritance traversal will stop at the
+   specified class names. Given the following Python module::
+
+        """
+               A
+              / \
+             B   C
+            / \ / \
+           E   D   F
+        """
+
+        class A:
+            pass
+
+        class B(A):
+            pass
+
+        class C(A):
+            pass
+
+        class D(B, C):
+            pass
+
+        class E(B):
+            pass
+
+        class F(C):
+            pass
+
+   If you have specified a module in the inheritance diagram like this::
+
+        .. inheritance-diagram:: dummy.test
+           :top-classes: dummy.test.B, dummy.test.C
+
+   any base classes which are ancestors to ``top-classes`` and are also defined
+   in the same module will be rendered as stand alone nodes. In this example
+   class A will be rendered as stand alone node in the graph. This is a known
+   issue due to how this extension works internally.
+
+   If you don't want class A (or any other ancestors) to be visible then specify
+   only the classes you would like to generate the diagram for like this::
+
+        .. inheritance-diagram:: dummy.test.D dummy.test.E dummy.test.F
+           :top-classes: dummy.test.B, dummy.test.C
+
+   .. versionchanged:: 1.7
+      Added ``top-classes`` option to limit the scope of inheritance graphs.
+
+
+Examples
+--------
+
+The following are different inheritance diagrams for the internal
+``InheritanceDiagram`` class that implements the directive.
+
+With full names::
+
+   .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
+
+.. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
+
+
+Showing class names only::
+
+   .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
+      :parts: 1
+
+.. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
+   :parts: 1
+
+Stopping the diagram at :class:`sphinx.util.docutils.SphinxDirective` (the
+highest superclass still part of Sphinx), and dropping the common left-most
+part (``sphinx``) from all names::
+
+   .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
+      :top-classes: sphinx.util.docutils.SphinxDirective
+      :parts: -1
+
+.. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
+   :top-classes: sphinx.util.docutils.SphinxDirective
+   :parts: -1
+
+.. py:class:: sphinx.ext.inheritance_diagram.InheritanceDiagram
+   :no-contents-entry:
+   :no-index-entry:
+
+   The internal class that implements the ``inheritance-diagram`` directive.
+
+
+Configuration
+-------------
+
+.. confval:: inheritance_graph_attrs
+
+   A dictionary of graphviz graph attributes for inheritance diagrams.
+
+   For example::
+
+      inheritance_graph_attrs = dict(rankdir="LR", size='"6.0, 8.0"',
+                                     fontsize=14, ratio='compress')
+
+.. confval:: inheritance_node_attrs
+
+   A dictionary of graphviz node attributes for inheritance diagrams.
+
+   For example::
+
+      inheritance_node_attrs = dict(shape='ellipse', fontsize=14, height=0.75,
+                                    color='dodgerblue1', style='filled')
+
+.. confval:: inheritance_edge_attrs
+
+   A dictionary of graphviz edge attributes for inheritance diagrams.
+
+.. confval:: inheritance_alias
+
+   Allows mapping the full qualified name of the class to custom values
+   (useful when exposing the underlying path of a class is not desirable,
+   e.g. it's a private class and should not be instantiated by the user).
+
+   For example::
+
+      inheritance_alias = {'_pytest.Magic': 'pytest.Magic'}
diff --git a/doc/usage/extensions/intersphinx.rst b/doc/usage/extensions/intersphinx.rst
new file mode 100644
index 0000000..5aaaf9f
--- /dev/null
+++ b/doc/usage/extensions/intersphinx.rst
@@ -0,0 +1,250 @@
+:mod:`sphinx.ext.intersphinx` -- Link to other projects' documentation
+======================================================================
+
+.. module:: sphinx.ext.intersphinx
+   :synopsis: Link to other Sphinx documentation.
+
+.. index:: pair: automatic; linking
+
+.. versionadded:: 0.5
+
+This extension can generate links to the documentation of objects in external
+projects, either explicitly through the :rst:role:`external` role, or as a
+fallback resolution for any other cross-reference.
+
+Usage for fallback resolution is simple: whenever Sphinx encounters a
+cross-reference that has no matching target in the current documentation set,
+it looks for targets in the external documentation sets configured in
+:confval:`intersphinx_mapping`.  A reference like
+``:py:class:`zipfile.ZipFile``` can then link to the Python documentation
+for the ZipFile class, without you having to specify where it is located
+exactly.
+
+When using the :rst:role:`external` role, you can force lookup to any external
+projects, and optionally to a specific external project.
+A link like ``:external:ref:`comparison manual <comparisons>``` will then link
+to the label "comparisons" in whichever configured external project, if it
+exists,
+and a link like ``:external+python:ref:`comparison manual <comparisons>``` will
+link to the label "comparisons" only in the doc set "python", if it exists.
+
+Behind the scenes, this works as follows:
+
+* Each Sphinx HTML build creates a file named :file:`objects.inv` that contains
+  a mapping from object names to URIs relative to the HTML set's root.
+
+* Projects using the Intersphinx extension can specify the location of such
+  mapping files in the :confval:`intersphinx_mapping` config value.  The mapping
+  will then be used to resolve both :rst:role:`external` references, and also
+  otherwise missing references to objects into links to the other documentation.
+
+* By default, the mapping file is assumed to be at the same location as the rest
+  of the documentation; however, the location of the mapping file can also be
+  specified individually, e.g. if the docs should be buildable without Internet
+  access.
+
+
+Configuration
+-------------
+
+To use Intersphinx linking, add ``'sphinx.ext.intersphinx'`` to your
+:confval:`extensions` config value, and use these config values to activate
+linking:
+
+.. confval:: intersphinx_mapping
+
+   This config value contains the locations and names of other projects that
+   should be linked to in this documentation.
+
+   Relative local paths for target locations are taken as relative to the base
+   of the built documentation, while relative local paths for inventory
+   locations are taken as relative to the source directory.
+
+   When fetching remote inventory files, proxy settings will be read from
+   the ``$HTTP_PROXY`` environment variable.
+
+   **Format**
+
+   .. versionadded:: 1.0
+
+   A dictionary mapping unique identifiers to a tuple ``(target, inventory)``.
+   Each ``target`` is the base URI of a foreign Sphinx documentation set and can
+   be a local path or an HTTP URI.  The ``inventory`` indicates where the
+   inventory file can be found: it can be ``None`` (an :file:`objects.inv` file
+   at the same location as the base URI) or another local file path or a full
+   HTTP URI to an inventory file.
+
+   The unique identifier can be used in the :rst:role:`external` role, so that
+   it is clear which intersphinx set the target belongs to.  A link like
+   ``external:python+ref:`comparison manual <comparisons>``` will link to the
+   label "comparisons" in the doc set "python", if it exists.
+
+   **Example**
+
+   To add links to modules and objects in the Python standard library
+   documentation, use::
+
+      intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
+
+   This will download the corresponding :file:`objects.inv` file from the
+   Internet and generate links to the pages under the given URI.  The downloaded
+   inventory is cached in the Sphinx environment, so it must be re-downloaded
+   whenever you do a full rebuild.
+
+   A second example, showing the meaning of a non-``None`` value of the second
+   tuple item::
+
+      intersphinx_mapping = {'python': ('https://docs.python.org/3',
+                                        'python-inv.txt')}
+
+   This will read the inventory from :file:`python-inv.txt` in the source
+   directory, but still generate links to the pages under
+   ``https://docs.python.org/3``.  It is up to you to update the inventory file
+   as new objects are added to the Python documentation.
+
+   **Multiple targets for the inventory**
+
+   .. versionadded:: 1.3
+
+   Alternative files can be specified for each inventory. One can give a
+   tuple for the second inventory tuple item as shown in the following
+   example. This will read the inventory iterating through the (second)
+   tuple items until the first successful fetch. The primary use case for
+   this to specify mirror sites for server downtime of the primary
+   inventory::
+
+      intersphinx_mapping = {'python': ('https://docs.python.org/3',
+                                        (None, 'python-inv.txt'))}
+
+   For a set of books edited and tested locally and then published
+   together, it could be helpful to try a local inventory file first,
+   to check references before publication::
+
+      intersphinx_mapping = {
+          'otherbook':
+              ('https://myproj.readthedocs.io/projects/otherbook/en/latest',
+                  ('../../otherbook/build/html/objects.inv', None)),
+      }
+
+   **Old format for this config value**
+
+   .. deprecated:: 6.2
+
+   .. RemovedInSphinx80Warning
+
+   .. caution:: This is the format used before Sphinx 1.0.
+                It is deprecated and will be removed in Sphinx 8.0.
+
+   A dictionary mapping URIs to either ``None`` or an URI.  The keys are the
+   base URI of the foreign Sphinx documentation sets and can be local paths or
+   HTTP URIs.  The values indicate where the inventory file can be found: they
+   can be ``None`` (at the same location as the base URI) or another local or
+   HTTP URI.
+
+   Example:
+
+   .. code:: python
+
+      intersphinx_mapping = {'https://docs.python.org/': None}
+
+
+.. confval:: intersphinx_cache_limit
+
+   The maximum number of days to cache remote inventories.  The default is
+   ``5``, meaning five days.  Set this to a negative value to cache inventories
+   for unlimited time.
+
+.. confval:: intersphinx_timeout
+
+   The number of seconds for timeout.  The default is ``None``, meaning do not
+   timeout.
+
+   .. note::
+
+      timeout is not a time limit on the entire response download; rather, an
+      exception is raised if the server has not issued a response for timeout
+      seconds.
+
+.. confval:: intersphinx_disabled_reftypes
+
+   .. versionadded:: 4.3
+
+   .. versionchanged:: 5.0
+
+      Changed default value from an empty list to ``['std:doc']``.
+
+   A list of strings being either:
+
+   - the name of a specific reference type in a domain,
+     e.g., ``std:doc``, ``py:func``, or ``cpp:class``,
+   - the name of a domain, and a wildcard, e.g.,
+     ``std:*``, ``py:*``, or ``cpp:*``, or
+   - simply a wildcard ``*``.
+
+   The default value is ``['std:doc']``.
+
+   When a non-:rst:role:`external` cross-reference is being resolved by
+   intersphinx, skip resolution if it matches one of the specifications in this
+   list.
+
+   For example, with ``intersphinx_disabled_reftypes = ['std:doc']``
+   a cross-reference ``:doc:`installation``` will not be attempted to be
+   resolved by intersphinx, but ``:external+otherbook:doc:`installation``` will
+   be attempted to be resolved in the inventory named ``otherbook`` in
+   :confval:`intersphinx_mapping`.
+   At the same time, all cross-references generated in, e.g., Python,
+   declarations will still be attempted to be resolved by intersphinx.
+
+   If ``*`` is in the list of domains, then no non-:rst:role:`external`
+   references will be resolved by intersphinx.
+
+Explicitly Reference External Objects
+-------------------------------------
+
+The Intersphinx extension provides the following role.
+
+.. rst:role:: external
+
+   .. versionadded:: 4.4
+
+   Use Intersphinx to perform lookup only in external projects, and not the
+   current project. Intersphinx still needs to know the type of object you
+   would like to find, so the general form of this role is to write the
+   cross-refererence as if the object is in the current project, but then prefix
+   it with ``:external``.
+   The two forms are then
+
+   - ``:external:domain:reftype:`target```,
+     e.g., ``:external:py:class:`zipfile.ZipFile```, or
+   - ``:external:reftype:`target```,
+     e.g., ``:external:doc:`installation```.
+
+   If you would like to constrain the lookup to a specific external project,
+   then the key of the project, as specified in :confval:`intersphinx_mapping`,
+   is added as well to get the two forms
+
+   - ``:external+invname:domain:reftype:`target```,
+     e.g., ``:external+python:py:class:`zipfile.ZipFile```, or
+   - ``:external+invname:reftype:`target```,
+     e.g., ``:external+python:doc:`installation```.
+
+Showing all links of an Intersphinx mapping file
+------------------------------------------------
+
+To show all Intersphinx links and their targets of an Intersphinx mapping file,
+run ``python -msphinx.ext.intersphinx url-or-path``.  This is helpful when
+searching for the root cause of a broken Intersphinx link in a documentation
+project. The following example prints the Intersphinx mapping of the Python 3
+documentation::
+
+   $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
+
+Using Intersphinx with inventory file under Basic Authorization
+---------------------------------------------------------------
+
+Intersphinx supports Basic Authorization like this::
+
+      intersphinx_mapping = {'python': ('https://user:password@docs.python.org/3',
+                                        None)}
+
+The user and password will be stripped from the URL when generating the links.
diff --git a/doc/usage/extensions/linkcode.rst b/doc/usage/extensions/linkcode.rst
new file mode 100644
index 0000000..e65a0b7
--- /dev/null
+++ b/doc/usage/extensions/linkcode.rst
@@ -0,0 +1,51 @@
+:mod:`sphinx.ext.linkcode` -- Add external links to source code
+===============================================================
+
+.. module:: sphinx.ext.linkcode
+   :synopsis: Add external links to source code.
+.. moduleauthor:: Pauli Virtanen
+
+.. versionadded:: 1.2
+
+This extension looks at your object descriptions (``.. class::``,
+``.. function::`` etc.) and adds external links to code hosted
+somewhere on the web. The intent is similar to the
+``sphinx.ext.viewcode`` extension, but assumes the source code can be
+found somewhere on the Internet.
+
+In your configuration, you need to specify a :confval:`linkcode_resolve`
+function that returns an URL based on the object.
+
+
+Configuration
+-------------
+
+.. confval:: linkcode_resolve
+
+   This is a function ``linkcode_resolve(domain, info)``,
+   which should return the URL to source code corresponding to
+   the object in given domain with given information.
+
+   The function should return ``None`` if no link is to be added.
+
+   The argument ``domain`` specifies the language domain the object is
+   in. ``info`` is a dictionary with the following keys guaranteed to
+   be present (dependent on the domain):
+
+   - ``py``: ``module`` (name of the module), ``fullname`` (name of the object)
+   - ``c``: ``names`` (list of names for the object)
+   - ``cpp``: ``names`` (list of names for the object)
+   - ``javascript``: ``object`` (name of the object), ``fullname``
+     (name of the item)
+
+   Example:
+
+   .. code-block:: python
+
+      def linkcode_resolve(domain, info):
+          if domain != 'py':
+              return None
+          if not info['module']:
+              return None
+          filename = info['module'].replace('.', '/')
+          return "https://somesite/sourcerepo/%s.py" % filename
diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst
new file mode 100644
index 0000000..df4fc6b
--- /dev/null
+++ b/doc/usage/extensions/math.rst
@@ -0,0 +1,320 @@
+.. highlight:: rest
+
+.. _math-support:
+
+Math support for HTML outputs in Sphinx
+=======================================
+
+.. module:: sphinx.ext.mathbase
+   :synopsis: Common math support for imgmath and mathjax / jsmath.
+
+.. versionadded:: 0.5
+.. versionchanged:: 1.8
+
+   Math support for non-HTML builders is integrated to sphinx-core.
+   So mathbase extension is no longer needed.
+
+Since mathematical notation isn't natively supported by HTML in any way, Sphinx
+gives a math support to HTML document with several extensions.  These use the
+reStructuredText math :rst:dir:`directive <math>` and :rst:role:`role <math>`.
+
+:mod:`sphinx.ext.imgmath` -- Render math as images
+--------------------------------------------------
+
+.. module:: sphinx.ext.imgmath
+   :synopsis: Render math as PNG or SVG images.
+
+.. versionadded:: 1.4
+
+This extension renders math via LaTeX and dvipng_ or dvisvgm_ into PNG or SVG
+images. This of course means that the computer where the docs are built must
+have both programs available.
+
+There are various configuration values you can set to influence how the images
+are built:
+
+.. confval:: imgmath_image_format
+
+   The output image format. The default is ``'png'``. It should be either
+   ``'png'`` or ``'svg'``. The image is produced by first executing ``latex``
+   on the TeX mathematical mark-up then (depending on the requested format)
+   either `dvipng`_ or `dvisvgm`_.
+
+.. confval:: imgmath_use_preview
+
+   ``dvipng`` and ``dvisvgm`` both have the ability to collect from LaTeX the
+   "depth" of the rendered math: an inline image should use this "depth" in a
+   ``vertical-align`` style to get correctly aligned with surrounding text.
+
+   This mechanism requires the `LaTeX preview package`_ (available as
+   ``preview-latex-style`` on Ubuntu xenial).  Therefore, the default for this
+   option is ``False`` but it is strongly recommended to set it to ``True``.
+
+   .. versionchanged:: 2.2
+
+      This option can be used with the ``'svg'`` :confval:`imgmath_image_format`.
+
+.. confval:: imgmath_add_tooltips
+
+   Default: ``True``.  If false, do not add the LaTeX code as an "alt" attribute
+   for math images.
+
+.. confval:: imgmath_font_size
+
+   The font size (in ``pt``) of the displayed math.  The default value is
+   ``12``.  It must be a positive integer.
+
+.. confval:: imgmath_latex
+
+   The command name with which to invoke LaTeX.  The default is ``'latex'``; you
+   may need to set this to a full path if ``latex`` is not in the executable
+   search path.
+
+   Since this setting is not portable from system to system, it is normally not
+   useful to set it in ``conf.py``; rather, giving it on the
+   :program:`sphinx-build` command line via the :option:`-D <sphinx-build -D>`
+   option should be preferable, like this::
+
+      sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html
+
+   This value should only contain the path to the latex executable, not further
+   arguments; use :confval:`imgmath_latex_args` for that purpose.
+
+   .. hint::
+
+      To use `OpenType Math fonts`__ with ``unicode-math``, via a custom
+      :confval:`imgmath_latex_preamble`, you can set :confval:`imgmath_latex`
+      to ``'dvilualatex'``, but must then set :confval:`imgmath_image_format`
+      to ``'svg'``.  Note: this has only been tested with ``dvisvgm 3.0.3``.
+      It significantly increases image production duration compared to using
+      standard ``'latex'`` with traditional TeX math fonts.
+
+      __ https://tex.stackexchange.com/questions/425098/which-opentype-math-fonts-are-available
+
+
+   .. hint::
+
+      Some fancy LaTeX mark-up (an example was reported which used TikZ to add
+      various decorations to the equation) require multiple runs of the LaTeX
+      executable.  To handle this, set this configuration setting to
+      ``'latexmk'`` (or a full path to it) as this Perl script reliably
+      chooses dynamically how many latex runs are needed.
+
+   .. versionchanged:: 6.2.0
+
+      Using ``'xelatex'`` (or a full path to it) is now supported.  But you
+      must then add ``'-no-pdf'`` to the :confval:`imgmath_latex_args` list of
+      the command options.  The ``'svg'`` :confval:`imgmath_image_format` is
+      required.  Also, you may need the ``dvisvgm`` binary to be relatively
+      recent (testing was done only with its ``3.0.3`` release).
+
+      .. note::
+
+         Regarding the previous note, it is currently not supported to use
+         ``latexmk`` with option ``-xelatex``.
+
+.. confval:: imgmath_latex_args
+
+   Additional arguments to give to latex, as a list.  The default is an empty
+   list.
+
+.. confval:: imgmath_latex_preamble
+
+   Additional LaTeX code to put into the preamble of the LaTeX files used to
+   translate the math snippets.  This is left empty by default.  Use it
+   e.g. to add packages which modify the fonts used for math, such as
+   ``'\\usepackage{newtxsf}'`` for sans-serif fonts, or
+   ``'\\usepackage{fouriernc}'`` for serif fonts.  Indeed, the default LaTeX
+   math fonts have rather thin glyphs which (in HTML output) often do not
+   match well with the font for text.
+
+.. confval:: imgmath_dvipng
+
+   The command name to invoke ``dvipng``.  The default is
+   ``'dvipng'``; you may need to set this to a full path if ``dvipng`` is not in
+   the executable search path. This option is only used when
+   ``imgmath_image_format`` is set to ``'png'``.
+
+.. confval:: imgmath_dvipng_args
+
+   Additional arguments to give to dvipng, as a list.  The default value is
+   ``['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']`` which makes the
+   image a bit darker and larger then it is by default (this compensates
+   somewhat for the thinness of default LaTeX math fonts), and produces PNGs with a
+   transparent background.  This option is used only when
+   ``imgmath_image_format`` is ``'png'``.
+
+.. confval:: imgmath_dvisvgm
+
+   The command name to invoke ``dvisvgm``.  The default is
+   ``'dvisvgm'``; you may need to set this to a full path if ``dvisvgm`` is not
+   in the executable search path.  This option is only used when
+   ``imgmath_image_format`` is ``'svg'``.
+
+.. confval:: imgmath_dvisvgm_args
+
+   Additional arguments to give to dvisvgm, as a list. The default value is
+   ``['--no-fonts']``, which means that ``dvisvgm`` will render glyphs as path
+   elements (cf the `dvisvgm FAQ`_). This option is used only when
+   ``imgmath_image_format`` is ``'svg'``.
+
+.. confval:: imgmath_embed
+
+   Default: ``False``.  If true, encode LaTeX output images within HTML files
+   (base64 encoded) and do not save separate png/svg files to disk.
+
+   .. versionadded:: 5.2
+
+:mod:`sphinx.ext.mathjax` -- Render math via JavaScript
+-------------------------------------------------------
+
+.. module:: sphinx.ext.mathjax
+   :synopsis: Render math using JavaScript via MathJax.
+
+.. warning::
+   Version 4.0 changes the version of MathJax used to version 3. You may need to
+   override ``mathjax_path`` to
+   ``https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML``
+   or update your configuration options for version 3
+   (see :confval:`mathjax3_config`).
+
+.. versionadded:: 1.1
+
+This extension puts math as-is into the HTML files.  The JavaScript package
+MathJax_ is then loaded and transforms the LaTeX markup to readable math live in
+the browser.
+
+Because MathJax (and the necessary fonts) is very large, it is not included in
+Sphinx but is set to automatically include it from a third-party site.
+
+.. attention::
+
+   You should use the math :rst:dir:`directive <math>` and
+   :rst:role:`role <math>`, not the native MathJax ``$$``, ``\(``, etc.
+
+
+.. confval:: mathjax_path
+
+   The path to the JavaScript file to include in the HTML files in order to load
+   MathJax.
+
+   The default is the ``https://`` URL that loads the JS files from the
+   `jsdelivr`__ Content Delivery Network. See the `MathJax Getting Started
+   page`__ for details. If you want MathJax to be available offline or
+   without including resources from a third-party site, you have to
+   download it and set this value to a different path.
+
+   __ https://www.jsdelivr.com/
+
+   __ https://www.mathjax.org/#gettingstarted
+
+   The path can be absolute or relative; if it is relative, it is relative to
+   the ``_static`` directory of the built docs.
+
+   For example, if you put MathJax into the static path of the Sphinx docs, this
+   value would be ``MathJax/MathJax.js``.  If you host more than one Sphinx
+   documentation set on one server, it is advisable to install MathJax in a
+   shared location.
+
+   You can also give a full ``https://`` URL different from the CDN URL.
+
+.. confval:: mathjax_options
+
+   The options to script tag for mathjax.  For example, you can set integrity
+   option with following setting::
+
+       mathjax_options = {
+           'integrity': 'sha384-......',
+       }
+
+   The default is empty (``{}``).
+
+   .. versionadded:: 1.8
+
+   .. versionchanged:: 4.4.1
+
+      Allow to change the loading method (async or defer) of MathJax if "async"
+      or "defer" key is set.
+
+.. confval:: mathjax3_config
+
+   The configuration options for MathJax v3 (which is used by default).
+   The given dictionary is assigned to the JavaScript variable
+   ``window.MathJax``.
+   For more information, please read `Configuring MathJax`__.
+
+   __ https://docs.mathjax.org/en/latest/web/configuration.html#configuration
+
+   The default is empty (not configured).
+
+   .. versionadded:: 4.0
+
+.. confval:: mathjax2_config
+
+   The configuration options for MathJax v2 (which can be loaded via
+   :confval:`mathjax_path`).
+   The value is used as a parameter of ``MathJax.Hub.Config()``.
+   For more information, please read `Using in-line configuration options`__.
+
+   __ https://docs.mathjax.org/en/v2.7-latest/
+      configuration.html#using-in-line-configuration-options
+
+   For example::
+
+       mathjax2_config = {
+           'extensions': ['tex2jax.js'],
+           'jax': ['input/TeX', 'output/HTML-CSS'],
+       }
+
+   The default is empty (not configured).
+
+   .. versionadded:: 4.0
+
+      :confval:`mathjax_config` has been renamed to :confval:`mathjax2_config`.
+
+.. confval:: mathjax_config
+
+   Former name of :confval:`mathjax2_config`.
+
+   For help converting your old MathJax configuration to to the new
+   :confval:`mathjax3_config`, see `Converting Your v2 Configuration to v3`__.
+
+   __ https://docs.mathjax.org/en/latest/web/
+      configuration.html#converting-your-v2-configuration-to-v3
+
+   .. versionadded:: 1.8
+
+   .. versionchanged:: 4.0
+
+      This has been renamed to :confval:`mathjax2_config`.
+      :confval:`mathjax_config` is still supported for backwards compatibility.
+
+:mod:`sphinx.ext.jsmath` -- Render math via JavaScript
+------------------------------------------------------
+
+.. module:: sphinx.ext.jsmath
+   :synopsis: Render math using JavaScript via JSMath.
+
+This extension works just as the MathJax extension does, but uses the older
+package jsMath_.  It provides this config value:
+
+.. confval:: jsmath_path
+
+   The path to the JavaScript file to include in the HTML files in order to load
+   JSMath.  There is no default.
+
+   The path can be absolute or relative; if it is relative, it is relative to
+   the ``_static`` directory of the built docs.
+
+   For example, if you put JSMath into the static path of the Sphinx docs, this
+   value would be ``jsMath/easy/load.js``.  If you host more than one
+   Sphinx documentation set on one server, it is advisable to install jsMath in
+   a shared location.
+
+
+.. _dvipng: https://savannah.nongnu.org/projects/dvipng/
+.. _dvisvgm: https://dvisvgm.de/
+.. _dvisvgm FAQ: https://dvisvgm.de/FAQ
+.. _MathJax: https://www.mathjax.org/
+.. _jsMath: http://www.math.union.edu/~dpvc/jsmath/
+.. _LaTeX preview package: https://www.gnu.org/software/auctex/preview-latex.html
diff --git a/doc/usage/extensions/napoleon.rst b/doc/usage/extensions/napoleon.rst
new file mode 100644
index 0000000..d2391da
--- /dev/null
+++ b/doc/usage/extensions/napoleon.rst
@@ -0,0 +1,574 @@
+:mod:`sphinx.ext.napoleon` -- Support for NumPy and Google style docstrings
+===========================================================================
+
+.. module:: sphinx.ext.napoleon
+   :synopsis: Support for NumPy and Google style docstrings
+
+.. moduleauthor:: Rob Ruana
+
+.. versionadded:: 1.3
+
+Overview
+--------
+
+.. highlight:: text
+
+Are you tired of writing docstrings that look like this::
+
+    :param path: The path of the file to wrap
+    :type path: str
+    :param field_storage: The :class:`FileStorage` instance to wrap
+    :type field_storage: FileStorage
+    :param temporary: Whether or not to delete the file when the File
+       instance is destructed
+    :type temporary: bool
+    :returns: A buffered writable file descriptor
+    :rtype: BufferedFileStorage
+
+`reStructuredText`_ is great, but it creates visually dense, hard to read
+:pep:`docstrings <287>`. Compare the jumble above to the same thing rewritten
+according to the `Google Python Style Guide`_::
+
+    Args:
+        path (str): The path of the file to wrap
+        field_storage (FileStorage): The :class:`FileStorage` instance to wrap
+        temporary (bool): Whether or not to delete the file when the File
+           instance is destructed
+
+    Returns:
+        BufferedFileStorage: A buffered writable file descriptor
+
+Much more legible, no?
+
+Napoleon is a :term:`extension` that enables Sphinx to parse both `NumPy`_ and
+`Google`_ style docstrings - the style recommended by `Khan Academy`_.
+
+Napoleon is a pre-processor that parses `NumPy`_ and `Google`_ style
+docstrings and converts them to reStructuredText before Sphinx attempts to
+parse them. This happens in an intermediate step while Sphinx is processing
+the documentation, so it doesn't modify any of the docstrings in your actual
+source code files.
+
+.. _ReStructuredText: https://docutils.sourceforge.io/rst.html
+.. _Google Python Style Guide:
+   https://google.github.io/styleguide/pyguide.html
+.. _Google:
+   https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings
+.. _NumPy:
+   https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
+.. _Khan Academy:
+   https://github.com/Khan/style-guides/blob/master/style/python.md#docstrings
+
+Getting Started
+~~~~~~~~~~~~~~~
+
+1. After :doc:`setting up Sphinx </usage/quickstart>` to build your docs,
+   enable napoleon in the Sphinx `conf.py` file::
+
+       # conf.py
+
+       # Add napoleon to the extensions list
+       extensions = ['sphinx.ext.napoleon']
+
+2. Use `sphinx-apidoc` to build your API documentation::
+
+       $ sphinx-apidoc -f -o docs/source projectdir
+
+
+Docstrings
+~~~~~~~~~~
+
+Napoleon interprets every docstring that :mod:`autodoc <sphinx.ext.autodoc>`
+can find, including docstrings on: ``modules``, ``classes``, ``attributes``,
+``methods``, ``functions``, and ``variables``. Inside each docstring,
+specially formatted `Sections`_ are parsed and converted to
+reStructuredText.
+
+All standard reStructuredText formatting still works as expected.
+
+
+.. _Sections:
+
+Docstring Sections
+~~~~~~~~~~~~~~~~~~
+
+All of the following section headers are supported:
+
+* ``Args`` *(alias of Parameters)*
+* ``Arguments`` *(alias of Parameters)*
+* ``Attention``
+* ``Attributes``
+* ``Caution``
+* ``Danger``
+* ``Error``
+* ``Example``
+* ``Examples``
+* ``Hint``
+* ``Important``
+* ``Keyword Args`` *(alias of Keyword Arguments)*
+* ``Keyword Arguments``
+* ``Methods``
+* ``Note``
+* ``Notes``
+* ``Other Parameters``
+* ``Parameters``
+* ``Return`` *(alias of Returns)*
+* ``Returns``
+* ``Raise`` *(alias of Raises)*
+* ``Raises``
+* ``References``
+* ``See Also``
+* ``Tip``
+* ``Todo``
+* ``Warning``
+* ``Warnings`` *(alias of Warning)*
+* ``Warn`` *(alias of Warns)*
+* ``Warns``
+* ``Yield`` *(alias of Yields)*
+* ``Yields``
+
+Google vs NumPy
+~~~~~~~~~~~~~~~
+
+Napoleon supports two styles of docstrings: `Google`_ and `NumPy`_. The
+main difference between the two styles is that Google uses indentation to
+separate sections, whereas NumPy uses underlines.
+
+Google style:
+
+.. code-block:: python
+
+    def func(arg1, arg2):
+        """Summary line.
+
+        Extended description of function.
+
+        Args:
+            arg1 (int): Description of arg1
+            arg2 (str): Description of arg2
+
+        Returns:
+            bool: Description of return value
+
+        """
+        return True
+
+NumPy style:
+
+.. code-block:: python
+
+    def func(arg1, arg2):
+        """Summary line.
+
+        Extended description of function.
+
+        Parameters
+        ----------
+        arg1 : int
+            Description of arg1
+        arg2 : str
+            Description of arg2
+
+        Returns
+        -------
+        bool
+            Description of return value
+
+        """
+        return True
+
+NumPy style tends to require more vertical space, whereas Google style
+tends to use more horizontal space. Google style tends to be easier to
+read for short and simple docstrings, whereas NumPy style tends be easier
+to read for long and in-depth docstrings.
+
+The choice between styles is largely aesthetic, but the two styles should
+not be mixed. Choose one style for your project and be consistent with it.
+
+.. seealso::
+
+   For complete examples:
+
+   * :ref:`example_google`
+   * :ref:`example_numpy`
+
+
+Type Annotations
+~~~~~~~~~~~~~~~~
+
+:pep:`484` introduced a standard way to express types in Python code.
+This is an alternative to expressing types directly in docstrings.
+One benefit of expressing types according to :pep:`484` is that
+type checkers and IDEs can take advantage of them for static code
+analysis. :pep:`484` was then extended by :pep:`526` which introduced
+a similar way to annotate variables (and attributes).
+
+Google style with Python 3 type annotations::
+
+    def func(arg1: int, arg2: str) -> bool:
+        """Summary line.
+
+        Extended description of function.
+
+        Args:
+            arg1: Description of arg1
+            arg2: Description of arg2
+
+        Returns:
+            Description of return value
+
+        """
+        return True
+
+    class Class:
+        """Summary line.
+
+        Extended description of class
+
+        Attributes:
+            attr1: Description of attr1
+            attr2: Description of attr2
+        """
+
+        attr1: int
+        attr2: str
+
+Google style with types in docstrings::
+
+    def func(arg1, arg2):
+        """Summary line.
+
+        Extended description of function.
+
+        Args:
+            arg1 (int): Description of arg1
+            arg2 (str): Description of arg2
+
+        Returns:
+            bool: Description of return value
+
+        """
+        return True
+
+    class Class:
+        """Summary line.
+
+        Extended description of class
+
+        Attributes:
+            attr1 (int): Description of attr1
+            attr2 (str): Description of attr2
+        """
+
+.. Note::
+   `Python 2/3 compatible annotations`_ aren't currently
+   supported by Sphinx and won't show up in the docs.
+
+.. _Python 2/3 compatible annotations: https://peps.python.org/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code
+
+
+Configuration
+-------------
+
+Listed below are all the settings used by napoleon and their default
+values. These settings can be changed in the Sphinx `conf.py` file. Make
+sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
+
+    # conf.py
+
+    # Add any Sphinx extension module names here, as strings
+    extensions = ['sphinx.ext.napoleon']
+
+    # Napoleon settings
+    napoleon_google_docstring = True
+    napoleon_numpy_docstring = True
+    napoleon_include_init_with_doc = False
+    napoleon_include_private_with_doc = False
+    napoleon_include_special_with_doc = True
+    napoleon_use_admonition_for_examples = False
+    napoleon_use_admonition_for_notes = False
+    napoleon_use_admonition_for_references = False
+    napoleon_use_ivar = False
+    napoleon_use_param = True
+    napoleon_use_rtype = True
+    napoleon_preprocess_types = False
+    napoleon_type_aliases = None
+    napoleon_attr_annotations = True
+
+.. _Google style:
+   https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings
+.. _NumPy style:
+   https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
+
+.. confval:: napoleon_google_docstring
+
+   True to parse `Google style`_ docstrings. False to disable support
+   for Google style docstrings. *Defaults to True.*
+
+.. confval:: napoleon_numpy_docstring
+
+   True to parse `NumPy style`_ docstrings. False to disable support
+   for NumPy style docstrings. *Defaults to True.*
+
+.. confval:: napoleon_include_init_with_doc
+
+   True to list ``__init___`` docstrings separately from the class
+   docstring. False to fall back to Sphinx's default behavior, which
+   considers the ``__init___`` docstring as part of the class
+   documentation. *Defaults to False.*
+
+   **If True**::
+
+       def __init__(self):
+           """
+           This will be included in the docs because it has a docstring
+           """
+
+       def __init__(self):
+           # This will NOT be included in the docs
+
+.. confval:: napoleon_include_private_with_doc
+
+   True to include private members (like ``_membername``) with docstrings
+   in the documentation. False to fall back to Sphinx's default behavior.
+   *Defaults to False.*
+
+   **If True**::
+
+       def _included(self):
+           """
+           This will be included in the docs because it has a docstring
+           """
+           pass
+
+       def _skipped(self):
+           # This will NOT be included in the docs
+           pass
+
+.. confval:: napoleon_include_special_with_doc
+
+   True to include special members (like ``__membername__``) with
+   docstrings in the documentation. False to fall back to Sphinx's
+   default behavior. *Defaults to True.*
+
+   **If True**::
+
+       def __str__(self):
+           """
+           This will be included in the docs because it has a docstring
+           """
+           return unicode(self).encode('utf-8')
+
+       def __unicode__(self):
+           # This will NOT be included in the docs
+           return unicode(self.__class__.__name__)
+
+.. confval:: napoleon_use_admonition_for_examples
+
+   True to use the ``.. admonition::`` directive for the **Example** and
+   **Examples** sections. False to use the ``.. rubric::`` directive
+   instead. One may look better than the other depending on what HTML
+   theme is used. *Defaults to False.*
+
+   This `NumPy style`_ snippet will be converted as follows::
+
+       Example
+       -------
+       This is just a quick example
+
+   **If True**::
+
+       .. admonition:: Example
+
+          This is just a quick example
+
+   **If False**::
+
+       .. rubric:: Example
+
+       This is just a quick example
+
+.. confval:: napoleon_use_admonition_for_notes
+
+   True to use the ``.. admonition::`` directive for **Notes** sections.
+   False to use the ``.. rubric::`` directive instead. *Defaults to False.*
+
+   .. note:: The singular **Note** section will always be converted to a
+      ``.. note::`` directive.
+
+   .. seealso::
+
+      :confval:`napoleon_use_admonition_for_examples`
+
+.. confval:: napoleon_use_admonition_for_references
+
+   True to use the ``.. admonition::`` directive for **References**
+   sections. False to use the ``.. rubric::`` directive instead.
+   *Defaults to False.*
+
+   .. seealso::
+
+      :confval:`napoleon_use_admonition_for_examples`
+
+.. confval:: napoleon_use_ivar
+
+   True to use the ``:ivar:`` role for instance variables. False to use
+   the ``.. attribute::`` directive instead. *Defaults to False.*
+
+   This `NumPy style`_ snippet will be converted as follows::
+
+       Attributes
+       ----------
+       attr1 : int
+           Description of `attr1`
+
+   **If True**::
+
+       :ivar attr1: Description of `attr1`
+       :vartype attr1: int
+
+   **If False**::
+
+       .. attribute:: attr1
+
+          Description of `attr1`
+
+          :type: int
+
+.. confval:: napoleon_use_param
+
+   True to use a ``:param:`` role for each function parameter. False to
+   use a single ``:parameters:`` role for all the parameters.
+   *Defaults to True.*
+
+   This `NumPy style`_ snippet will be converted as follows::
+
+       Parameters
+       ----------
+       arg1 : str
+           Description of `arg1`
+       arg2 : int, optional
+           Description of `arg2`, defaults to 0
+
+   **If True**::
+
+       :param arg1: Description of `arg1`
+       :type arg1: str
+       :param arg2: Description of `arg2`, defaults to 0
+       :type arg2: :class:`int`, *optional*
+
+   **If False**::
+
+       :parameters: * **arg1** (*str*) --
+                      Description of `arg1`
+                    * **arg2** (*int, optional*) --
+                      Description of `arg2`, defaults to 0
+
+.. confval:: napoleon_use_keyword
+
+   True to use a ``:keyword:`` role for each function keyword argument.
+   False to use a single ``:keyword arguments:`` role for all the
+   keywords.
+   *Defaults to True.*
+
+   This behaves similarly to :confval:`napoleon_use_param`. Note unlike docutils,
+   ``:keyword:`` and ``:param:`` will not be treated the same way - there will
+   be a separate "Keyword Arguments" section, rendered in the same fashion as
+   "Parameters" section (type links created if possible)
+
+   .. seealso::
+
+      :confval:`napoleon_use_param`
+
+.. confval:: napoleon_use_rtype
+
+   True to use the ``:rtype:`` role for the return type. False to output
+   the return type inline with the description. *Defaults to True.*
+
+   This `NumPy style`_ snippet will be converted as follows::
+
+       Returns
+       -------
+       bool
+           True if successful, False otherwise
+
+   **If True**::
+
+       :returns: True if successful, False otherwise
+       :rtype: bool
+
+   **If False**::
+
+       :returns: *bool* -- True if successful, False otherwise
+
+.. confval:: napoleon_preprocess_types
+
+   True to convert the type definitions in the docstrings as references.
+   Defaults to *False*.
+
+   .. versionadded:: 3.2.1
+   .. versionchanged:: 3.5
+
+      Do preprocess the Google style docstrings also.
+
+.. confval:: napoleon_type_aliases
+
+   A mapping to translate type names to other names or references. Works
+   only when ``napoleon_use_param = True``. *Defaults to None.*
+
+   With::
+
+       napoleon_type_aliases = {
+           "CustomType": "mypackage.CustomType",
+           "dict-like": ":term:`dict-like <mapping>`",
+       }
+
+   This `NumPy style`_ snippet::
+
+       Parameters
+       ----------
+       arg1 : CustomType
+           Description of `arg1`
+       arg2 : dict-like
+           Description of `arg2`
+
+   becomes::
+
+       :param arg1: Description of `arg1`
+       :type arg1: mypackage.CustomType
+       :param arg2: Description of `arg2`
+       :type arg2: :term:`dict-like <mapping>`
+
+   .. versionadded:: 3.2
+
+.. confval:: napoleon_attr_annotations
+
+   True to allow using :pep:`526` attributes annotations in classes.
+   If an attribute is documented in the docstring without a type and
+   has an annotation in the class body, that type is used.
+
+   .. versionadded:: 3.4
+
+.. confval:: napoleon_custom_sections
+
+   Add a list of custom sections to include, expanding the list of parsed sections.
+   *Defaults to None.*
+
+   The entries can either be strings or tuples, depending on the intention:
+
+   * To create a custom "generic" section, just pass a string.
+   * To create an alias for an existing section, pass a tuple containing the
+     alias name and the original, in that order.
+   * To create a custom section that displays like the parameters or returns
+     section, pass a tuple containing the custom section name and a string
+     value, "params_style" or "returns_style".
+
+   If an entry is just a string, it is interpreted as a header for a generic
+   section. If the entry is a tuple/list/indexed container, the first entry
+   is the name of the section, the second is the section key to emulate. If the
+   second entry value is "params_style" or "returns_style", the custom section
+   will be displayed like the parameters section or returns section.
+
+   .. versionadded:: 1.8
+   .. versionchanged:: 3.5
+      Support ``params_style`` and ``returns_style``
diff --git a/doc/usage/extensions/todo.rst b/doc/usage/extensions/todo.rst
new file mode 100644
index 0000000..bf8b922
--- /dev/null
+++ b/doc/usage/extensions/todo.rst
@@ -0,0 +1,62 @@
+:mod:`sphinx.ext.todo` -- Support for todo items
+================================================
+
+.. module:: sphinx.ext.todo
+   :synopsis: Allow inserting todo items into documents.
+.. moduleauthor:: Daniel Bültmann
+
+.. versionadded:: 0.5
+
+There are two additional directives when using this extension:
+
+.. rst:directive:: todo
+
+   Use this directive like, for example, :rst:dir:`note`.
+
+   It will only show up in the output if :confval:`todo_include_todos` is
+   ``True``.
+
+   .. versionadded:: 1.3.2
+      This directive supports an ``class`` option that determines the class
+      attribute for HTML output.  If not given, the class defaults to
+      ``admonition-todo``.
+
+
+.. rst:directive:: todolist
+
+   This directive is replaced by a list of all todo directives in the whole
+   documentation, if :confval:`todo_include_todos` is ``True``.
+
+
+These can be configured as seen below.
+
+Configuration
+-------------
+
+.. confval:: todo_include_todos
+
+   If this is ``True``, :rst:dir:`todo` and :rst:dir:`todolist` produce output,
+   else they produce nothing.  The default is ``False``.
+
+.. confval:: todo_emit_warnings
+
+   If this is ``True``, :rst:dir:`todo` emits a warning for each TODO entries.
+   The default is ``False``.
+
+   .. versionadded:: 1.5
+
+.. confval:: todo_link_only
+
+   If this is ``True``, :rst:dir:`todolist` produce output without file path and
+   line, The default is ``False``.
+
+   .. versionadded:: 1.4
+
+autodoc provides the following an additional event:
+
+.. event:: todo-defined (app, node)
+
+   .. versionadded:: 1.5
+
+   Emitted when a todo is defined. *node* is the defined
+   ``sphinx.ext.todo.todo_node`` node.
diff --git a/doc/usage/extensions/viewcode.rst b/doc/usage/extensions/viewcode.rst
new file mode 100644
index 0000000..c90d2ba
--- /dev/null
+++ b/doc/usage/extensions/viewcode.rst
@@ -0,0 +1,106 @@
+:mod:`sphinx.ext.viewcode` -- Add links to highlighted source code
+==================================================================
+
+.. module:: sphinx.ext.viewcode
+   :synopsis: Add links to a highlighted version of the source code.
+.. moduleauthor:: Georg Brandl
+
+.. versionadded:: 1.0
+
+This extension looks at your Python object descriptions (``.. class::``, ``..
+function::`` etc.) and tries to find the source files where the objects are
+contained.  When found, a separate HTML page will be output for each module with
+a highlighted version of the source code, and a link will be added to all object
+descriptions that leads to the source code of the described object.  A link back
+from the source to the description will also be inserted.
+
+.. warning::
+
+   Basically, ``viewcode`` extension will import the modules being linked to.
+   If any modules have side effects on import, these will be executed when
+   ``sphinx-build`` is run.
+
+   If you document scripts (as opposed to library modules), make sure their
+   main routine is protected by a ``if __name__ == '__main__'`` condition.
+
+   In addition, if you don't want to import the modules by ``viewcode``,
+   you can tell the location of the location of source code to ``viewcode``
+   using the :event:`viewcode-find-source` event.
+
+   If :confval:`viewcode_follow_imported_members` is enabled,
+   you will also need to resolve imported attributes
+   using the :event:`viewcode-follow-imported` event.
+
+This extension works only on HTML related builders like ``html``,
+``applehelp``, ``devhelp``, ``htmlhelp``, ``qthelp`` and so on except
+``singlehtml``. By default ``epub`` builder doesn't
+support this extension (see :confval:`viewcode_enable_epub`).
+
+Configuration
+-------------
+
+.. confval:: viewcode_follow_imported_members
+
+   If this is ``True``, viewcode extension will emit
+   :event:`viewcode-follow-imported` event to resolve the name of the module
+   by other extensions.  The default is ``True``.
+
+   .. versionadded:: 1.3
+
+   .. versionchanged:: 1.8
+      Renamed from ``viewcode_import`` to ``viewcode_follow_imported_members``.
+
+.. confval:: viewcode_enable_epub
+
+   If this is ``True``, viewcode extension is also enabled even if you use
+   epub builders. This extension generates pages outside toctree, but this
+   is not preferred as epub format.
+
+   Until 1.4.x, this extension is always enabled. If you want to generate
+   epub as same as 1.4.x, you should set ``True``, but epub format checker's
+   score becomes worse.
+
+   The default is ``False``.
+
+   .. versionadded:: 1.5
+
+   .. warning::
+
+      Not all epub readers support pages generated by viewcode extension.
+      These readers ignore links to pages are not under toctree.
+
+      Some reader's rendering result are corrupted and
+      `epubcheck <https://github.com/IDPF/epubcheck>`_'s score
+      becomes worse even if the reader supports.
+
+.. confval:: viewcode_line_numbers
+
+   Default: ``False``.
+
+   If set to ``True``, inline line numbers will be added to the highlighted code.
+
+   .. versionadded:: 7.2
+
+.. event:: viewcode-find-source (app, modname)
+
+   .. versionadded:: 1.8
+
+   Find the source code for a module.
+   An event handler for this event should return
+   a tuple of the source code itself and a dictionary of tags.
+   The dictionary maps the name of a class, function, attribute, etc
+   to a tuple of its type, the start line number, and the end line number.
+   The type should be one of "class", "def", or "other".
+
+   :param app: The Sphinx application object.
+   :param modname: The name of the module to find source code for.
+
+.. event:: viewcode-follow-imported (app, modname, attribute)
+
+   .. versionadded:: 1.8
+
+   Find the name of the original module for an attribute.
+
+   :param app: The Sphinx application object.
+   :param modname: The name of the module that the attribute belongs to.
+   :param attribute: The name of the member to follow.
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
new file mode 100644
index 0000000..fd8cdd8
--- /dev/null
+++ b/doc/usage/index.rst
@@ -0,0 +1,20 @@
+============
+Using Sphinx
+============
+
+This guide serves to demonstrate how one can get started with Sphinx and covers
+everything from installing Sphinx and configuring your first Sphinx project to
+using some of the advanced features Sphinx provides out-of-the-box. If you are
+looking for guidance on extending Sphinx, refer to :doc:`/development/index`.
+
+.. toctree::
+   :maxdepth: 2
+
+   restructuredtext/index
+   markdown
+   configuration
+   builders/index
+   extensions/index
+   theming
+   advanced/intl
+   advanced/websupport/index
diff --git a/doc/usage/installation.rst b/doc/usage/installation.rst
new file mode 100644
index 0000000..e85603e
--- /dev/null
+++ b/doc/usage/installation.rst
@@ -0,0 +1,282 @@
+=================
+Installing Sphinx
+=================
+
+.. contents::
+   :depth: 1
+   :local:
+   :backlinks: none
+
+.. highlight:: console
+
+Overview
+--------
+
+Sphinx is written in `Python`__ and supports Python 3.9+. It builds upon the
+shoulders of many third-party libraries such as `Docutils`__ and `Jinja`__,
+which are installed when Sphinx is installed.
+
+__ https://docs.python-guide.org/
+__ https://docutils.sourceforge.io/
+__ https://jinja.palletsprojects.com/
+
+
+Linux
+-----
+
+Debian/Ubuntu
+~~~~~~~~~~~~~
+
+Install either ``python3-sphinx`` using :command:`apt-get`:
+
+::
+
+   $ apt-get install python3-sphinx
+
+If it not already present, this will install Python for you.
+
+RHEL, CentOS
+~~~~~~~~~~~~
+
+Install ``python-sphinx`` using :command:`yum`:
+
+::
+
+   $ yum install python-sphinx
+
+If it not already present, this will install Python for you.
+
+Other distributions
+~~~~~~~~~~~~~~~~~~~
+
+Most Linux distributions have Sphinx in their package repositories.  Usually
+the package is called ``python3-sphinx``, ``python-sphinx`` or ``sphinx``.  Be
+aware that there are at least two other packages with ``sphinx`` in their name:
+a speech recognition toolkit (*CMU Sphinx*) and a full-text search database
+(*Sphinx search*).
+
+
+macOS
+-----
+
+Sphinx can be installed using `Homebrew`__, `MacPorts`__, or as part of
+a Python distribution such as `Anaconda`__.
+
+__ https://brew.sh/
+__ https://www.macports.org/
+__ https://www.anaconda.com/download/#macos
+
+Homebrew
+~~~~~~~~
+
+::
+
+   $ brew install sphinx-doc
+
+For more information, refer to the `package overview`__.
+
+__ https://formulae.brew.sh/formula/sphinx-doc
+
+MacPorts
+~~~~~~~~
+
+Install either ``python3x-sphinx`` using :command:`port`:
+
+::
+
+   $ sudo port install py39-sphinx
+
+To set up the executable paths, use the ``port select`` command:
+
+::
+
+   $ sudo port select --set python python39
+   $ sudo port select --set sphinx py39-sphinx
+
+For more information, refer to the `package overview`__.
+
+__ https://www.macports.org/ports.php?by=library&substr=py39-sphinx
+
+Anaconda
+~~~~~~~~
+
+::
+
+   $ conda install sphinx
+
+Windows
+-------
+
+Sphinx can be install using `Chocolatey`__ or
+:ref:`installed manually <windows-other-method>`.
+
+__ https://chocolatey.org/
+
+Chocolatey
+~~~~~~~~~~
+
+::
+
+   $ choco install sphinx
+
+You would need to `install Chocolatey
+<https://chocolatey.org/install>`_
+before running this.
+
+For more information, refer to the `chocolatey page`__.
+
+__ https://chocolatey.org/packages/sphinx/
+
+.. _windows-other-method:
+
+Other Methods
+~~~~~~~~~~~~~
+
+Most Windows users do not have Python installed by default, so we begin with
+the installation of Python itself.  To check if you already have Python
+installed, open the *Command Prompt* (:kbd:`⊞Win-r` and type :command:`cmd`).
+Once the command prompt is open, type :command:`python --version` and press
+Enter.  If Python is installed, you will see the version of Python printed to
+the screen.  If you do not have Python installed, refer to the `Hitchhikers
+Guide to Python's`__ Python on Windows installation guides. You must install
+`Python 3`__.
+
+Once Python is installed, you can install Sphinx using :command:`pip`.  Refer
+to the :ref:`pip installation instructions <install-pypi>` below for more
+information.
+
+__ https://docs.python-guide.org/
+__ https://docs.python-guide.org/starting/install3/win/
+
+
+.. _install-pypi:
+
+Installation from PyPI
+----------------------
+
+Sphinx packages are published on the `Python Package Index
+<https://pypi.org/project/Sphinx/>`_.  The preferred tool for installing
+packages from *PyPI* is :command:`pip`.  This tool is provided with all modern
+versions of Python.
+
+On Linux or MacOS, you should open your terminal and run the following command.
+
+::
+
+   $ pip install -U sphinx
+
+On Windows, you should open *Command Prompt* (:kbd:`⊞Win-r` and type
+:command:`cmd`) and run the same command.
+
+.. code-block:: doscon
+
+   C:\> pip install -U sphinx
+
+After installation, type :command:`sphinx-build --version` on the command
+prompt.  If everything worked fine, you will see the version number for the
+Sphinx package you just installed.
+
+Installation from *PyPI* also allows you to install the latest development
+release.  You will not generally need (or want) to do this, but it can be
+useful if you see a possible bug in the latest stable release.  To do this, use
+the ``--pre`` flag.
+
+::
+
+   $ pip install -U --pre sphinx
+
+Using virtual environments
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When installing Sphinx using pip,
+it is highly recommended to use *virtual environments*,
+which isolate the installed packages from the system packages,
+thus removing the need to use administrator privileges.
+To create a virtual environment in the ``.venv`` directory,
+use the following command.
+
+::
+
+   $ python -m venv .venv
+
+You can read more about them in the `Python Packaging User Guide`_.
+
+.. _Python Packaging User Guide: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment
+
+.. warning::
+
+   Note that in some Linux distributions, such as Debian and Ubuntu,
+   this might require an extra installation step as follows.
+
+   .. code-block:: console
+
+      $ apt-get install python3-venv
+
+Docker
+------
+
+Docker images for Sphinx are published on the `Docker Hub`_.  There are two kind
+of images:
+
+- `sphinxdoc/sphinx`_
+- `sphinxdoc/sphinx-latexpdf`_
+
+.. _Docker Hub: https://hub.docker.com/
+.. _sphinxdoc/sphinx: https://hub.docker.com/r/sphinxdoc/sphinx
+.. _sphinxdoc/sphinx-latexpdf: https://hub.docker.com/r/sphinxdoc/sphinx-latexpdf
+
+Former one is used for standard usage of Sphinx, and latter one is mainly used for
+PDF builds using LaTeX.  Please choose one for your purpose.
+
+.. note::
+
+   sphinxdoc/sphinx-latexpdf contains TeXLive packages. So the image is very large
+   (over 2GB!).
+
+.. hint::
+
+   When using docker images, please use ``docker run`` command to invoke sphinx
+   commands.  For example, you can use following command to create a Sphinx
+   project:
+
+   .. code-block:: console
+
+      $ docker run -it --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-quickstart
+
+   And you can use the following command to build HTML document:
+
+   .. code-block:: console
+
+      $ docker run --rm -v /path/to/document:/docs sphinxdoc/sphinx make html
+
+For more details, please read `README file`__ of docker images.
+
+.. __: https://hub.docker.com/r/sphinxdoc/sphinx
+
+
+Installation from source
+------------------------
+
+You can install Sphinx directly from a clone of the `Git repository`__.  This
+can be done either by cloning the repo and installing from the local clone, on
+simply installing directly via :command:`git`.
+
+::
+
+   $ git clone https://github.com/sphinx-doc/sphinx
+   $ cd sphinx
+   $ pip install .
+
+::
+
+   $ pip install git+https://github.com/sphinx-doc/sphinx
+
+You can also download a snapshot of the Git repo in either `tar.gz`__ or
+`zip`__ format.  Once downloaded and extracted, these can be installed with
+:command:`pip` as above.
+
+.. highlight:: default
+
+__ https://github.com/sphinx-doc/sphinx
+__ https://github.com/sphinx-doc/sphinx/archive/master.tar.gz
+__ https://github.com/sphinx-doc/sphinx/archive/master.zip
diff --git a/doc/usage/markdown.rst b/doc/usage/markdown.rst
new file mode 100644
index 0000000..ac24f8d
--- /dev/null
+++ b/doc/usage/markdown.rst
@@ -0,0 +1,52 @@
+.. highlight:: python
+
+.. _markdown:
+
+========
+Markdown
+========
+
+`Markdown`__ is a lightweight markup language with a simplistic plain text
+formatting syntax.  It exists in many syntactically different *flavors*.  To
+support Markdown-based documentation, Sphinx can use `MyST-Parser`__.
+MyST-Parser is a Docutils bridge to `markdown-it-py`__, a Python package for
+parsing the `CommonMark`__ Markdown flavor.
+
+__ https://daringfireball.net/projects/markdown/
+__ https://myst-parser.readthedocs.io/en/latest/
+__ https://github.com/executablebooks/markdown-it-py
+__ https://commonmark.org/
+
+Configuration
+-------------
+
+To configure your Sphinx project for Markdown support, proceed as follows:
+
+#. Install the Markdown parser *MyST-Parser*::
+
+      pip install --upgrade myst-parser
+
+#. Add *myst_parser* to the
+   :confval:`list of configured extensions <extensions>`::
+
+      extensions = ['myst_parser']
+
+   .. note::
+      MyST-Parser requires Sphinx 2.1 or newer.
+
+#. If you want to use Markdown files with extensions other than ``.md``, adjust
+   the :confval:`source_suffix` variable.  The following example configures
+   Sphinx to parse all files with the extensions ``.md`` and ``.txt`` as
+   Markdown::
+
+      source_suffix = {
+          '.rst': 'restructuredtext',
+          '.txt': 'markdown',
+          '.md': 'markdown',
+      }
+
+#. You can further configure *MyST-Parser* to allow custom syntax that
+   standard *CommonMark* doesn't support.  Read more in the `MyST-Parser
+   documentation`__.
+
+__ https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html
diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst
new file mode 100644
index 0000000..0773f60
--- /dev/null
+++ b/doc/usage/quickstart.rst
@@ -0,0 +1,348 @@
+===============
+Getting Started
+===============
+
+Sphinx is a *documentation generator* or a tool that translates a set of plain
+text source files into various output formats, automatically producing
+cross-references, indices, etc.  That is, if you have a directory containing a
+bunch of :doc:`/usage/restructuredtext/index` or :doc:`/usage/markdown`
+documents, Sphinx can generate a series of HTML files, a PDF file (via LaTeX),
+man pages and much more.
+
+Sphinx focuses on documentation, in particular handwritten documentation,
+however, Sphinx can also be used to generate blogs, homepages and even books.
+Much of Sphinx's power comes from the richness of its default plain-text markup
+format, :doc:`reStructuredText </usage/restructuredtext/index>`, along with
+its :doc:`significant extensibility capabilities </development/index>`.
+
+The goal of this document is to give you a quick taste of what Sphinx is and
+how you might use it. When you're done here, you can check out the
+:doc:`installation guide </usage/installation>` followed by the intro to the
+default markup format used by Sphinx, :doc:`reStucturedText
+</usage/restructuredtext/index>`.
+
+For a great "introduction" to writing docs in general -- the whys and hows, see
+also `Write the docs`__, written by Eric Holscher.
+
+.. __: https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/
+
+
+Setting up the documentation sources
+------------------------------------
+
+The root directory of a Sphinx collection of plain-text document sources is
+called the :term:`source directory`.  This directory also contains the Sphinx
+configuration file :file:`conf.py`, where you can configure all aspects of how
+Sphinx reads your sources and builds your documentation.  [#]_
+
+Sphinx comes with a script called :program:`sphinx-quickstart` that sets up a
+source directory and creates a default :file:`conf.py` with the most useful
+configuration values from a few questions it asks you. To use this, run:
+
+.. code-block:: console
+
+   $ sphinx-quickstart
+
+
+Defining document structure
+---------------------------
+
+Let's assume you've run :program:`sphinx-quickstart`.  It created a source
+directory with :file:`conf.py` and a root document, :file:`index.rst`.  The
+main function of the :term:`root document` is to serve as a welcome page, and
+to contain the root of the "table of contents tree" (or *toctree*).  This is one
+of the main things that Sphinx adds to reStructuredText, a way to connect
+multiple files to a single hierarchy of documents.
+
+.. sidebar:: reStructuredText directives
+
+   ``toctree`` is a reStructuredText :dfn:`directive`, a very versatile piece
+   of markup.  Directives can have arguments, options and content.
+
+   *Arguments* are given directly after the double colon following the
+   directive's name.  Each directive decides whether it can have arguments, and
+   how many.
+
+   *Options* are given after the arguments, in form of a "field list".  The
+   ``maxdepth`` is such an option for the ``toctree`` directive.
+
+   *Content* follows the options or arguments after a blank line.  Each
+   directive decides whether to allow content, and what to do with it.
+
+   A common gotcha with directives is that **the first line of the content must
+   be indented to the same level as the options are**.
+
+The ``toctree`` directive initially is empty, and looks like so:
+
+.. code-block:: rst
+
+   .. toctree::
+      :maxdepth: 2
+
+You add documents listing them in the *content* of the directive:
+
+.. code-block:: rst
+
+   .. toctree::
+      :maxdepth: 2
+
+      usage/installation
+      usage/quickstart
+      ...
+
+This is exactly how the ``toctree`` for this documentation looks.  The
+documents to include are given as :term:`document name`\ s, which in short
+means that you leave off the file name extension and use forward slashes
+(``/``) as directory separators.
+
+|more| Read more about :ref:`the toctree directive <toctree-directive>`.
+
+You can now create the files you listed in the ``toctree`` and add content, and
+their section titles will be inserted (up to the ``maxdepth`` level) at the
+place where the ``toctree`` directive is placed.  Also, Sphinx now knows about
+the order and hierarchy of your documents.  (They may contain ``toctree``
+directives themselves, which means you can create deeply nested hierarchies if
+necessary.)
+
+
+Adding content
+--------------
+
+In Sphinx source files, you can use most features of standard
+:term:`reStructuredText`.  There are also several features added by Sphinx.
+For example, you can add cross-file references in a portable way (which works
+for all output types) using the :rst:role:`ref` role.
+
+For an example, if you are viewing the HTML version, you can look at the source
+for this document -- use the "Show Source" link in the sidebar.
+
+.. todo:: Update the below link when we add new guides on these.
+
+|more| See :doc:`/usage/restructuredtext/index` for a more in-depth
+introduction to reStructuredText, including markup added by Sphinx.
+
+
+Running the build
+-----------------
+
+Now that you have added some files and content, let's make a first build of the
+docs.  A build is started with the :program:`sphinx-build` program:
+
+.. code-block:: console
+
+   $ sphinx-build -b html sourcedir builddir
+
+where *sourcedir* is the :term:`source directory`, and *builddir* is the
+directory in which you want to place the built documentation.
+The :option:`-b <sphinx-build -b>` option selects a builder; in this example
+Sphinx will build HTML files.
+
+|more| Refer to the :doc:`sphinx-build man page </man/sphinx-build>` for all
+options that :program:`sphinx-build` supports.
+
+However, :program:`sphinx-quickstart` script creates a :file:`Makefile` and a
+:file:`make.bat` which make life even easier for you. These can be executed by
+running :command:`make` with the name of the builder. For example.
+
+.. code-block:: console
+
+   $ make html
+
+This will build HTML docs in the build directory you chose. Execute
+:command:`make` without an argument to see which targets are available.
+
+.. admonition:: How do I generate PDF documents?
+
+   ``make latexpdf`` runs the :mod:`LaTeX builder
+   <sphinx.builders.latex.LaTeXBuilder>` and readily invokes the pdfTeX
+   toolchain for you.
+
+
+.. todo:: Move this whole section into a guide on rST or directives
+
+Documenting objects
+-------------------
+
+One of Sphinx's main objectives is easy documentation of :dfn:`objects` (in a
+very general sense) in any :dfn:`domain`.  A domain is a collection of object
+types that belong together, complete with markup to create and reference
+descriptions of these objects.
+
+The most prominent domain is the Python domain. For example, to document
+Python's built-in function ``enumerate()``, you would add this to one of your
+source files.
+
+.. code-block:: rst
+
+   .. py:function:: enumerate(sequence[, start=0])
+
+      Return an iterator that yields tuples of an index and an item of the
+      *sequence*. (And so on.)
+
+This is rendered like this:
+
+.. py:function:: enumerate(sequence[, start=0])
+
+   Return an iterator that yields tuples of an index and an item of the
+   *sequence*. (And so on.)
+
+The argument of the directive is the :dfn:`signature` of the object you
+describe, the content is the documentation for it.  Multiple signatures can be
+given, each in its own line.
+
+The Python domain also happens to be the default domain, so you don't need to
+prefix the markup with the domain name.
+
+.. code-block:: rst
+
+   .. function:: enumerate(sequence[, start=0])
+
+      ...
+
+does the same job if you keep the default setting for the default domain.
+
+There are several more directives for documenting other types of Python
+objects, for example :rst:dir:`py:class` or :rst:dir:`py:method`.  There is
+also a cross-referencing :dfn:`role` for each of these object types.  This
+markup will create a link to the documentation of ``enumerate()``.
+
+::
+
+   The :py:func:`enumerate` function can be used for ...
+
+And here is the proof: A link to :func:`enumerate`.
+
+Again, the ``py:`` can be left out if the Python domain is the default one.  It
+doesn't matter which file contains the actual documentation for
+``enumerate()``; Sphinx will find it and create a link to it.
+
+Each domain will have special rules for how the signatures can look like, and
+make the formatted output look pretty, or add specific features like links to
+parameter types, e.g. in the C/C++ domains.
+
+|more| See :doc:`/usage/restructuredtext/domains` for all the available domains
+and their directives/roles.
+
+
+Basic configuration
+-------------------
+
+Earlier we mentioned that the :file:`conf.py` file controls how Sphinx
+processes your documents.  In that file, which is executed as a Python source
+file, you assign configuration values.  For advanced users: since it is
+executed by Sphinx, you can do non-trivial tasks in it, like extending
+:data:`sys.path` or importing a module to find out the version you are
+documenting.
+
+The config values that you probably want to change are already put into the
+:file:`conf.py` by :program:`sphinx-quickstart` and initially commented out
+(with standard Python syntax: a ``#`` comments the rest of the line).  To
+change the default value, remove the hash sign and modify the value.  To
+customize a config value that is not automatically added by
+:program:`sphinx-quickstart`, just add an additional assignment.
+
+Keep in mind that the file uses Python syntax for strings, numbers, lists and
+so on.  The file is saved in UTF-8 by default, as indicated by the encoding
+declaration in the first line.
+
+|more| See :doc:`/usage/configuration` for documentation of all available
+config values.
+
+
+.. todo:: Move this entire doc to a different section
+
+Autodoc
+-------
+
+When documenting Python code, it is common to put a lot of documentation in the
+source files, in documentation strings.  Sphinx supports the inclusion of
+docstrings from your modules with an :dfn:`extension` (an extension is a Python
+module that provides additional features for Sphinx projects) called *autodoc*.
+
+In order to use *autodoc*, you need to activate it in :file:`conf.py` by
+putting the string ``'sphinx.ext.autodoc'`` into the list assigned to the
+:confval:`extensions` config value::
+
+   extensions = ['sphinx.ext.autodoc']
+
+Then, you have a few additional directives at your disposal.  For example, to
+document the function ``io.open()``, reading its signature and
+docstring from the source file, you'd write this::
+
+   .. autofunction:: io.open
+
+You can also document whole classes or even modules automatically, using member
+options for the auto directives, like ::
+
+   .. automodule:: io
+      :members:
+
+*autodoc* needs to import your modules in order to extract the docstrings.
+Therefore, you must add the appropriate path to :py:data:`sys.path` in your
+:file:`conf.py`.
+
+.. 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.
+
+|more| See :mod:`sphinx.ext.autodoc` for the complete description of the
+features of autodoc.
+
+
+.. todo:: Move this doc to another section
+
+Intersphinx
+-----------
+
+Many Sphinx documents including the `Python documentation`_ are published on
+the Internet.  When you want to make links to such documents from your
+documentation, you can do it with :mod:`sphinx.ext.intersphinx`.
+
+.. _Python documentation: https://docs.python.org/3
+
+In order to use intersphinx, you need to activate it in :file:`conf.py` by
+putting the string ``'sphinx.ext.intersphinx'`` into the :confval:`extensions`
+list and set up the :confval:`intersphinx_mapping` config value.
+
+For example, to link to ``io.open()`` in the Python library manual, you need to
+setup your :confval:`intersphinx_mapping` like::
+
+   intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
+
+And now, you can write a cross-reference like ``:py:func:`io.open```.  Any
+cross-reference that has no matching target in the current documentation set,
+will be looked up in the documentation sets configured in
+:confval:`intersphinx_mapping` (this needs access to the URL in order to
+download the list of valid targets).  Intersphinx also works for some other
+:term:`domain`\'s roles including ``:ref:``, however it doesn't work for
+``:doc:`` as that is non-domain role.
+
+|more| See :mod:`sphinx.ext.intersphinx` for the complete description of the
+features of intersphinx.
+
+
+More topics to be covered
+-------------------------
+
+- :doc:`Other extensions </usage/extensions/index>`:
+- Static files
+- :doc:`Selecting a theme </usage/theming>`
+- :ref:`Templating <templating>`
+- Using extensions
+- :ref:`Writing extensions <dev-extensions>`
+
+
+.. rubric:: Footnotes
+
+.. [#] This is the usual layout.  However, :file:`conf.py` can also live in
+       another directory, the :term:`configuration directory`.  Refer to the
+       :doc:`sphinx-build man page </man/sphinx-build>` for more information.
+
+.. |more| image:: /_static/more.png
+          :align: middle
+          :alt: more info
diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst
new file mode 100644
index 0000000..cc3c615
--- /dev/null
+++ b/doc/usage/restructuredtext/basics.rst
@@ -0,0 +1,631 @@
+.. highlight:: rst
+
+.. _rst-primer:
+
+=======================
+reStructuredText Primer
+=======================
+
+reStructuredText is the default plaintext markup language used by Sphinx.  This
+section is a brief introduction to reStructuredText (reST) concepts and syntax,
+intended to provide authors with enough information to author documents
+productively.  Since reST was designed to be a simple, unobtrusive markup
+language, this will not take too long.
+
+.. seealso::
+
+   The authoritative `reStructuredText User Documentation
+   <https://docutils.sourceforge.io/rst.html>`_.  The "ref" links in this
+   document link to the description of the individual constructs in the reST
+   reference.
+
+
+Paragraphs
+----------
+
+The paragraph (:duref:`ref <paragraphs>`) is the most basic block in a reST
+document.  Paragraphs are simply chunks of text separated by one or more blank
+lines.  As in Python, indentation is significant in reST, so all lines of the
+same paragraph must be left-aligned to the same level of indentation.
+
+
+.. _rst-inline-markup:
+
+Inline markup
+-------------
+
+The standard reST inline markup is quite simple: use
+
+* one asterisk: ``*text*`` for emphasis (italics),
+* two asterisks: ``**text**`` for strong emphasis (boldface), and
+* backquotes: ````text```` for code samples.
+
+If asterisks or backquotes appear in running text and could be confused with
+inline markup delimiters, they have to be escaped with a backslash.
+
+Be aware of some restrictions of this markup:
+
+* it may not be nested,
+* content may not start or end with whitespace: ``* text*`` is wrong,
+* it must be separated from surrounding text by non-word characters.  Use a
+  backslash escaped space to work around that: ``thisis\ *one*\ word``.
+
+These restrictions may be lifted in future versions of the docutils.
+
+It is also possible to replace or expand upon some of this inline markup with
+roles. Refer to :ref:`rst-roles-alt` for more information.
+
+
+Lists and Quote-like blocks
+---------------------------
+
+List markup (:duref:`ref <bullet-lists>`) is natural: just place an asterisk at
+the start of a paragraph and indent properly.  The same goes for numbered
+lists; they can also be autonumbered using a ``#`` sign::
+
+   * This is a bulleted list.
+   * It has two items, the second
+     item uses two lines.
+
+   1. This is a numbered list.
+   2. It has two items too.
+
+   #. This is a numbered list.
+   #. It has two items too.
+
+Nested lists are possible, but be aware that they must be separated from the
+parent list items by blank lines::
+
+   * this is
+   * a list
+
+     * with a nested list
+     * and some subitems
+
+   * and here the parent list continues
+
+Definition lists (:duref:`ref <definition-lists>`) are created as follows::
+
+   term (up to a line of text)
+      Definition of the term, which must be indented
+
+      and can even consist of multiple paragraphs
+
+   next term
+      Description.
+
+Note that the term cannot have more than one line of text.
+
+Quoted paragraphs (:duref:`ref <block-quotes>`) are created by just indenting
+them more than the surrounding paragraphs.
+
+Line blocks (:duref:`ref <line-blocks>`) are a way of preserving line breaks::
+
+   | These lines are
+   | broken exactly like in
+   | the source file.
+
+There are also several more special blocks available:
+
+* field lists (:duref:`ref <field-lists>`, with caveats noted in
+  :ref:`rst-field-lists`)
+* option lists (:duref:`ref <option-lists>`)
+* quoted literal blocks (:duref:`ref <quoted-literal-blocks>`)
+* doctest blocks (:duref:`ref <doctest-blocks>`)
+
+
+.. _rst-literal-blocks:
+
+Literal blocks
+--------------
+
+Literal code blocks (:duref:`ref <literal-blocks>`) are introduced by ending a
+paragraph with the special marker ``::``.  The literal block must be indented
+(and, like all paragraphs, separated from the surrounding ones by blank
+lines)::
+
+   This is a normal text paragraph. The next paragraph is a code sample::
+
+      It is not processed in any way, except
+      that the indentation is removed.
+
+      It can span multiple lines.
+
+   This is a normal text paragraph again.
+
+The handling of the ``::`` marker is smart:
+
+* If it occurs as a paragraph of its own, that paragraph is completely left out
+  of the document.
+* If it is preceded by whitespace, the marker is removed.
+* If it is preceded by non-whitespace, the marker is replaced by a single
+  colon.
+
+That way, the second sentence in the above example's first paragraph would be
+rendered as "The next paragraph is a code sample:".
+
+Code highlighting can be enabled for these literal blocks on a document-wide
+basis using the :rst:dir:`highlight` directive and on a project-wide basis
+using the :confval:`highlight_language` configuration option. The
+:rst:dir:`code-block` directive can be used to set highlighting on a
+block-by-block basis. These directives are discussed later.
+
+
+.. _rst-doctest-blocks:
+
+Doctest blocks
+--------------
+
+Doctest blocks (:duref:`ref <doctest-blocks>`) are interactive Python sessions
+cut-and-pasted into docstrings. They do not require the
+:ref:`literal blocks <rst-literal-blocks>` syntax. The doctest block must end
+with a blank line and should *not* end with an unused prompt::
+
+    >>> 1 + 1
+    2
+
+.. _rst-tables:
+
+Tables
+------
+
+For *grid tables* (:duref:`ref <grid-tables>`), you have to "paint" the cell
+grid yourself.  They look like this::
+
+   +------------------------+------------+----------+----------+
+   | Header row, column 1   | Header 2   | Header 3 | Header 4 |
+   | (header rows optional) |            |          |          |
+   +========================+============+==========+==========+
+   | body row 1, column 1   | column 2   | column 3 | column 4 |
+   +------------------------+------------+----------+----------+
+   | body row 2             | ...        | ...      |          |
+   +------------------------+------------+----------+----------+
+
+*Simple tables* (:duref:`ref <simple-tables>`) are easier to write, but
+limited: they must contain more than one row, and the first column cells cannot
+contain multiple lines.  They look like this::
+
+   =====  =====  =======
+   A      B      A and B
+   =====  =====  =======
+   False  False  False
+   True   False  False
+   False  True   False
+   True   True   True
+   =====  =====  =======
+
+Two more syntaxes are supported: *CSV tables* and *List tables*. They use an
+*explicit markup block*. Refer to :ref:`table-directives` for more information.
+
+
+Hyperlinks
+----------
+
+External links
+~~~~~~~~~~~~~~
+
+Use ```Link text <https://domain.invalid/>`_`` for inline web links.  If the
+link text should be the web address, you don't need special markup at all, the
+parser finds links and mail addresses in ordinary text.
+
+.. important:: There must be a space between the link text and the opening \< for the URL.
+
+You can also separate the link and the target definition (:duref:`ref
+<hyperlink-targets>`), like this::
+
+   This is a paragraph that contains `a link`_.
+
+   .. _a link: https://domain.invalid/
+
+Internal links
+~~~~~~~~~~~~~~
+
+Internal linking is done via a special reST role provided by Sphinx, see the
+section on specific markup, :ref:`ref-role`.
+
+
+.. _rst-sections:
+
+Sections
+--------
+
+Section headers (:duref:`ref <sections>`) are created by underlining (and
+optionally overlining) the section title with a punctuation character, at least
+as long as the text::
+
+   =================
+   This is a heading
+   =================
+
+Normally, there are no heading levels assigned to certain characters as the
+structure is determined from the succession of headings.  However, this
+convention is used in `Python Developer's Guide for documenting
+<https://devguide.python.org/documentation/markup/#sections>`_ which you may
+follow:
+
+* ``#`` with overline, for parts
+* ``*`` with overline, for chapters
+* ``=`` for sections
+* ``-`` for subsections
+* ``^`` for subsubsections
+* ``"`` for paragraphs
+
+Of course, you are free to use your own marker characters (see the reST
+documentation), and use a deeper nesting level, but keep in mind that most
+target formats (HTML, LaTeX) have a limited supported nesting depth.
+
+
+.. _rst-field-lists:
+
+Field Lists
+-----------
+
+Field lists (:duref:`ref <field-lists>`) are sequences of fields marked up like
+this::
+
+   :fieldname: Field content
+
+They are commonly used in Python documentation::
+
+    def my_function(my_arg, my_other_arg):
+        """A function just for me.
+
+        :param my_arg: The first of my arguments.
+        :param my_other_arg: The second of my arguments.
+
+        :returns: A message (just for me, of course).
+        """
+
+Sphinx extends standard docutils behavior and intercepts field lists specified
+at the beginning of documents.  Refer to :doc:`field-lists` for more
+information.
+
+
+.. TODO This ref should be 'rst-roles', but that already exists. Rename the
+.. other ones
+
+.. _rst-roles-alt:
+
+Roles
+-----
+
+A role or "custom interpreted text role" (:duref:`ref <roles>`) is an inline
+piece of explicit markup. It signifies that the enclosed text should be
+interpreted in a specific way.  Sphinx uses this to provide semantic markup and
+cross-referencing of identifiers, as described in the appropriate section.  The
+general syntax is ``:rolename:`content```.
+
+Docutils supports the following roles:
+
+* :durole:`emphasis` -- equivalent of ``*emphasis*``
+* :durole:`strong` -- equivalent of ``**strong**``
+* :durole:`literal` -- equivalent of ````literal````
+* :durole:`subscript` -- subscript text
+* :durole:`superscript` -- superscript text
+* :durole:`title-reference` -- for titles of books, periodicals, and other
+  materials
+
+Refer to :doc:`roles` for roles added by Sphinx.
+
+
+Explicit Markup
+---------------
+
+"Explicit markup" (:duref:`ref <explicit-markup-blocks>`) is used in reST for
+most constructs that need special handling, such as footnotes,
+specially-highlighted paragraphs, comments, and generic directives.
+
+An explicit markup block begins with a line starting with ``..`` followed by
+whitespace and is terminated by the next paragraph at the same level of
+indentation.  (There needs to be a blank line between explicit markup and
+normal paragraphs.  This may all sound a bit complicated, but it is intuitive
+enough when you write it.)
+
+
+.. _rst-directives:
+
+Directives
+----------
+
+A directive (:duref:`ref <directives>`) is a generic block of explicit markup.
+Along with roles, it is one of the extension mechanisms of reST, and Sphinx
+makes heavy use of it.
+
+Docutils supports the following directives:
+
+* Admonitions: :dudir:`attention`, :dudir:`caution`, :dudir:`danger`,
+  :dudir:`error`, :dudir:`hint`, :dudir:`important`, :dudir:`note`,
+  :dudir:`tip`, :dudir:`warning` and the generic
+  :dudir:`admonition <admonitions>`.  (Most themes style only "note" and
+  "warning" specially.)
+
+* Images:
+
+  - :dudir:`image` (see also Images_ below)
+  - :dudir:`figure` (an image with caption and optional legend)
+
+* Additional body elements:
+
+  - :dudir:`contents <table-of-contents>` (a local, i.e. for the current file
+    only, table of contents)
+  - :dudir:`container` (a container with a custom class, useful to generate an
+    outer ``<div>`` in HTML)
+  - :dudir:`rubric` (a heading without relation to the document sectioning)
+  - :dudir:`topic`, :dudir:`sidebar` (special highlighted body elements)
+  - :dudir:`parsed-literal` (literal block that supports inline markup)
+  - :dudir:`epigraph` (a block quote with optional attribution line)
+  - :dudir:`highlights`, :dudir:`pull-quote` (block quotes with their own
+    class attribute)
+  - :dudir:`compound <compound-paragraph>` (a compound paragraph)
+
+* Special tables:
+
+  - :dudir:`table` (a table with title)
+  - :dudir:`csv-table` (a table generated from comma-separated values)
+  - :dudir:`list-table` (a table generated from a list of lists)
+
+* Special directives:
+
+  - :dudir:`raw <raw-data-pass-through>` (include raw target-format markup)
+  - :dudir:`include` (include reStructuredText from another file) -- in Sphinx,
+    when given an absolute include file path, this directive takes it as
+    relative to the source directory
+
+    .. _rstclass:
+
+  - :dudir:`class` (assign a class attribute to the next element)
+
+    .. note::
+
+       When the default domain contains a ``class`` directive, this directive
+       will be shadowed.  Therefore, Sphinx re-exports it as ``rst-class``.
+
+* HTML specifics:
+
+  - :dudir:`meta`
+    (generation of HTML ``<meta>`` tags, see also :ref:`html-meta` below)
+  - :dudir:`title <metadata-document-title>` (override document title)
+
+* Influencing markup:
+
+  - :dudir:`default-role` (set a new default role)
+  - :dudir:`role` (create a new role)
+
+  Since these are only per-file, better use Sphinx's facilities for setting the
+  :confval:`default_role`.
+
+.. warning::
+
+   Do *not* use the directives :dudir:`sectnum`, :dudir:`header` and
+   :dudir:`footer`.
+
+Directives added by Sphinx are described in :doc:`directives`.
+
+Basically, a directive consists of a name, arguments, options and content.
+(Keep this terminology in mind, it is used in the next chapter describing
+custom directives.)  Looking at this example, ::
+
+   .. function:: foo(x)
+                 foo(y, z)
+      :module: some.module.name
+
+      Return a line of text input from the user.
+
+``function`` is the directive name.  It is given two arguments here, the
+remainder of the first line and the second line, as well as one option
+``module`` (as you can see, options are given in the lines immediately
+following the arguments and indicated by the colons).  Options must be indented
+to the same level as the directive content.
+
+The directive content follows after a blank line and is indented relative to
+the directive start or if options are present, by the same amount as the
+options.
+
+Be careful as the indent is not a fixed number of whitespace, e.g. three, but
+any number whitespace.  This can be surprising when a fixed indent is used
+throughout the document and can make a difference for directives which are
+sensitive to whitespace. Compare::
+
+   .. code-block::
+      :caption: A cool example
+
+          The output of this line starts with four spaces.
+
+   .. code-block::
+
+          The output of this line has no spaces at the beginning.
+
+In the first code block, the indent for the content was fixated by the option
+line to three spaces, consequently the content starts with four spaces.
+In the latter the indent was fixed by the content itself to seven spaces, thus
+it does not start with a space.
+
+
+Images
+------
+
+reST supports an image directive (:dudir:`ref <image>`), used like so::
+
+   .. image:: gnu.png
+      (options)
+
+When used within Sphinx, the file name given (here ``gnu.png``) must either be
+relative to the source file, or absolute which means that they are relative to
+the top source directory.  For example, the file ``sketch/spam.rst`` could
+refer to the image ``images/spam.png`` as ``../images/spam.png`` or
+``/images/spam.png``.
+
+Sphinx will automatically copy image files over to a subdirectory of the output
+directory on building (e.g. the ``_static`` directory for HTML output.)
+
+Interpretation of image size options (``width`` and ``height``) is as follows:
+if the size has no unit or the unit is pixels, the given size will only be
+respected for output channels that support pixels. Other units (like ``pt`` for
+points) will be used for HTML and LaTeX output (the latter replaces ``pt`` by
+``bp`` as this is the TeX unit such that ``72bp=1in``).
+
+Sphinx extends the standard docutils behavior by allowing an asterisk for the
+extension::
+
+   .. image:: gnu.*
+
+Sphinx then searches for all images matching the provided pattern and
+determines their type.  Each builder then chooses the best image out of these
+candidates.  For instance, if the file name ``gnu.*`` was given and two files
+:file:`gnu.pdf` and :file:`gnu.png` existed in the source tree, the LaTeX
+builder would choose the former, while the HTML builder would prefer the
+latter.  Supported image types and choosing priority are defined at
+:doc:`/usage/builders/index`.
+
+Note that image file names should not contain spaces.
+
+.. versionchanged:: 0.4
+   Added the support for file names ending in an asterisk.
+
+.. versionchanged:: 0.6
+   Image paths can now be absolute.
+
+.. versionchanged:: 1.5
+   latex target supports pixels (default is ``96px=1in``).
+
+
+Footnotes
+---------
+
+For footnotes (:duref:`ref <footnotes>`), use ``[#name]_`` to mark the footnote
+location, and add the footnote body at the bottom of the document after a
+"Footnotes" rubric heading, like so::
+
+   Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
+
+   .. rubric:: Footnotes
+
+   .. [#f1] Text of the first footnote.
+   .. [#f2] Text of the second footnote.
+
+You can also explicitly number the footnotes (``[1]_``) or use auto-numbered
+footnotes without names (``[#]_``).
+
+
+Citations
+---------
+
+Standard reST citations (:duref:`ref <citations>`) are supported, with the
+additional feature that they are "global", i.e. all citations can be referenced
+from all files.  Use them like so::
+
+   Lorem ipsum [Ref]_ dolor sit amet.
+
+   .. [Ref] Book or article reference, URL or whatever.
+
+Citation usage is similar to footnote usage, but with a label that is not
+numeric or begins with ``#``.
+
+
+Substitutions
+-------------
+
+reST supports "substitutions" (:duref:`ref <substitution-definitions>`), which
+are pieces of text and/or markup referred to in the text by ``|name|``.  They
+are defined like footnotes with explicit markup blocks, like this::
+
+   .. |name| replace:: replacement *text*
+
+or this::
+
+   .. |caution| image:: warning.png
+                :alt: Warning!
+
+See the :duref:`reST reference for substitutions <substitution-definitions>`
+for details.
+
+.. index:: ! pair: global; substitutions
+
+If you want to use some substitutions for all documents, put them into
+:confval:`rst_prolog` or :confval:`rst_epilog` or put them into a separate file
+and include it into all documents you want to use them in, using the
+:dudir:`include` directive.  (Be sure to give the include file a file name
+extension differing from that of other source files, to avoid Sphinx finding it
+as a standalone document.)
+
+Sphinx defines some default substitutions, see :ref:`default-substitutions`.
+
+
+Comments
+--------
+
+Every explicit markup block which isn't a valid markup construct (like the
+footnotes above) is regarded as a comment (:duref:`ref <comments>`).  For
+example::
+
+   .. This is a comment.
+
+You can indent text after a comment start to form multiline comments::
+
+   ..
+      This whole indented block
+      is a comment.
+
+      Still in the comment.
+
+
+.. _html-meta:
+
+HTML Metadata
+-------------
+
+The :dudir:`meta` directive allows specifying the HTML
+`metadata element`_ of a Sphinx documentation page.  For example, the
+directive::
+
+   .. meta::
+      :description: The Sphinx documentation builder
+      :keywords: Sphinx, documentation, builder
+
+will generate the following HTML output:
+
+.. code:: html
+
+   <meta name="description" content="The Sphinx documentation builder">
+   <meta name="keywords" content="Sphinx, documentation, builder">
+
+Also, Sphinx will add the keywords as specified in the meta directive to the
+search index.  Thereby, the ``lang`` attribute of the meta element is
+considered.  For example, the directive::
+
+   .. meta::
+      :keywords: backup
+      :keywords lang=en: pleasefindthiskey pleasefindthiskeytoo
+      :keywords lang=de: bittediesenkeyfinden
+
+adds the following words to the search indices of builds with different language
+configurations:
+
+* ``pleasefindthiskey``, ``pleasefindthiskeytoo`` to *English* builds;
+* ``bittediesenkeyfinden`` to *German* builds;
+* ``backup`` to builds in all languages.
+
+.. _metadata element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta
+
+
+Source encoding
+---------------
+
+Since the easiest way to include special characters like em dashes or copyright
+signs in reST is to directly write them as Unicode characters, one has to
+specify an encoding.  Sphinx assumes source files to be encoded in UTF-8 by
+default; you can change this with the :confval:`source_encoding` config value.
+
+
+Gotchas
+-------
+
+There are some problems one commonly runs into while authoring reST documents:
+
+* **Separation of inline markup:** As said above, inline markup spans must be
+  separated from the surrounding text by non-word characters, you have to use a
+  backslash-escaped space to get around that.  See :duref:`the reference
+  <substitution-definitions>` for the details.
+
+* **No nested inline markup:** Something like ``*see :func:`foo`*`` is not
+  possible.
diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst
new file mode 100644
index 0000000..1fd5b66
--- /dev/null
+++ b/doc/usage/restructuredtext/directives.rst
@@ -0,0 +1,1311 @@
+.. highlight:: rst
+
+==========
+Directives
+==========
+
+:ref:`As previously discussed <rst-directives>`, a directive is a generic block
+of explicit markup. While Docutils provides a number of directives, Sphinx
+provides many more and uses directives as one of the primary extension
+mechanisms.
+
+See :doc:`/usage/restructuredtext/domains` for roles added by domains.
+
+.. seealso::
+
+   Refer to the :ref:`reStructuredText Primer <rst-directives>` for an overview
+   of the directives provided by Docutils.
+
+
+.. _toctree-directive:
+
+Table of contents
+-----------------
+
+.. index:: pair: table of; contents
+
+Since reST does not have facilities to interconnect several documents, or split
+documents into multiple output files, Sphinx uses a custom directive to add
+relations between the single files the documentation is made of, as well as
+tables of contents.  The ``toctree`` directive is the central element.
+
+.. note::
+
+   Simple "inclusion" of one file in another can be done with the
+   :dudir:`include` directive.
+
+.. note::
+
+   To create table of contents for current document (.rst file), use the
+   standard reST :dudir:`contents directive <table-of-contents>`.
+
+.. rst:directive:: toctree
+
+   This directive inserts a "TOC tree" at the current location, using the
+   individual TOCs (including "sub-TOC trees") of the documents given in the
+   directive body.  Relative document names (not beginning with a slash) are
+   relative to the document the directive occurs in, absolute names are relative
+   to the source directory.  A numeric ``maxdepth`` option may be given to
+   indicate the depth of the tree; by default, all levels are included. [#]_
+
+   The representation of "TOC tree" is changed in each output format.  The
+   builders that output multiple files (ex. HTML) treat it as a collection of
+   hyperlinks.  On the other hand, the builders that output a single file (ex.
+   LaTeX, man page, etc.) replace it with the content of the documents on the
+   TOC tree.
+
+   Consider this example (taken from the Python docs' library reference index)::
+
+      .. toctree::
+         :maxdepth: 2
+
+         intro
+         strings
+         datatypes
+         numeric
+         (many more documents listed here)
+
+   This accomplishes two things:
+
+   * Tables of contents from all those documents are inserted, with a maximum
+     depth of two, that means one nested heading.  ``toctree`` directives in
+     those documents are also taken into account.
+   * Sphinx knows the relative order of the documents ``intro``,
+     ``strings`` and so forth, and it knows that they are children of the shown
+     document, the library index.  From this information it generates "next
+     chapter", "previous chapter" and "parent chapter" links.
+
+   **Entries**
+
+   Document titles in the :rst:dir:`toctree` will be automatically read from the
+   title of the referenced document. If that isn't what you want, you can
+   specify an explicit title and target using a similar syntax to reST
+   hyperlinks (and Sphinx's :ref:`cross-referencing syntax <xref-syntax>`). This
+   looks like::
+
+       .. toctree::
+
+          intro
+          All about strings <strings>
+          datatypes
+
+   The second line above will link to the ``strings`` document, but will use the
+   title "All about strings" instead of the title of the ``strings`` document.
+
+   You can also add external links, by giving an HTTP URL instead of a document
+   name.
+
+   **Section numbering**
+
+   If you want to have section numbers even in HTML output, give the
+   **toplevel** toctree a ``numbered`` option.  For example::
+
+      .. toctree::
+         :numbered:
+
+         foo
+         bar
+
+   Numbering then starts at the heading of ``foo``.  Sub-toctrees are
+   automatically numbered (don't give the ``numbered`` flag to those).
+
+   Numbering up to a specific depth is also possible, by giving the depth as a
+   numeric argument to ``numbered``.
+
+   **Additional options**
+
+   You can use the ``caption`` option to provide a toctree caption and you can
+   use the ``name`` option to provide an implicit target name that can be
+   referenced by using :rst:role:`ref`::
+
+      .. toctree::
+         :caption: Table of Contents
+         :name: mastertoc
+
+         foo
+
+   If you want only the titles of documents in the tree to show up, not other
+   headings of the same level, you can use the ``titlesonly`` option::
+
+      .. toctree::
+         :titlesonly:
+
+         foo
+         bar
+
+   You can use "globbing" in toctree directives, by giving the ``glob`` flag
+   option.  All entries are then matched against the list of available
+   documents, and matches are inserted into the list alphabetically.  Example::
+
+      .. toctree::
+         :glob:
+
+         intro*
+         recipe/*
+         *
+
+   This includes first all documents whose names start with ``intro``, then all
+   documents in the ``recipe`` folder, then all remaining documents (except the
+   one containing the directive, of course.) [#]_
+
+   The special entry name ``self`` stands for the document containing the
+   toctree directive.  This is useful if you want to generate a "sitemap" from
+   the toctree.
+
+   You can use the ``reversed`` flag option to reverse the order of the entries
+   in the list. This can be useful when using the ``glob`` flag option to
+   reverse the ordering of the files.  Example::
+
+      .. toctree::
+         :glob:
+         :reversed:
+
+         recipe/*
+
+   You can also give a "hidden" option to the directive, like this::
+
+      .. toctree::
+         :hidden:
+
+         doc_1
+         doc_2
+
+   This will still notify Sphinx of the document hierarchy, but not insert links
+   into the document at the location of the directive -- this makes sense if you
+   intend to insert these links yourself, in a different style, or in the HTML
+   sidebar.
+
+   In cases where you want to have only one top-level toctree and hide all other
+   lower level toctrees you can add the "includehidden" option to the top-level
+   toctree entry::
+
+      .. toctree::
+         :includehidden:
+
+         doc_1
+         doc_2
+
+   All other toctree entries can then be eliminated by the "hidden" option.
+
+   In the end, all documents in the :term:`source directory` (or subdirectories)
+   must occur in some ``toctree`` directive; Sphinx will emit a warning if it
+   finds a file that is not included, because that means that this file will not
+   be reachable through standard navigation.
+
+   Use :confval:`exclude_patterns` to explicitly exclude documents or
+   directories from building completely.  Use :ref:`the "orphan" metadata
+   <metadata>` to let a document be built, but notify Sphinx that it is not
+   reachable via a toctree.
+
+   The "root document" (selected by :confval:`root_doc`) is the "root" of the TOC
+   tree hierarchy.  It can be used as the documentation's main page, or as a
+   "full table of contents" if you don't give a ``maxdepth`` option.
+
+   .. versionchanged:: 0.3
+      Added "globbing" option.
+
+   .. versionchanged:: 0.6
+      Added "numbered" and "hidden" options as well as external links and
+      support for "self" references.
+
+   .. versionchanged:: 1.0
+      Added "titlesonly" option.
+
+   .. versionchanged:: 1.1
+      Added numeric argument to "numbered".
+
+   .. versionchanged:: 1.2
+      Added "includehidden" option.
+
+   .. versionchanged:: 1.3
+      Added "caption" and "name" option.
+
+Special names
+^^^^^^^^^^^^^
+
+Sphinx reserves some document names for its own use; you should not try to
+create documents with these names -- it will cause problems.
+
+The special document names (and pages generated for them) are:
+
+* ``genindex``, ``modindex``, ``search``
+
+  These are used for the general index, the Python module index, and the search
+  page, respectively.
+
+  The general index is populated with entries from modules, all
+  index-generating :ref:`object descriptions <basic-domain-markup>`, and from
+  :rst:dir:`index` directives.
+
+  The Python module index contains one entry per :rst:dir:`py:module`
+  directive.
+
+  The search page contains a form that uses the generated JSON search index and
+  JavaScript to full-text search the generated documents for search words; it
+  should work on every major browser that supports modern JavaScript.
+
+* every name beginning with ``_``
+
+  Though few such names are currently used by Sphinx, you should not
+  create documents or document-containing directories with such names.  (Using
+  ``_`` as a prefix for a custom template directory is fine.)
+
+.. warning::
+
+   Be careful with unusual characters in filenames.  Some formats may interpret
+   these characters in unexpected ways:
+
+   * Do not use the colon ``:`` for HTML based formats.  Links to other parts
+     may not work.
+
+   * Do not use the plus ``+`` for the ePub format.  Some resources may not be
+     found.
+
+
+Paragraph-level markup
+----------------------
+
+.. index:: note, warning
+           pair: changes; in version
+
+These directives create short paragraphs and can be used inside information
+units as well as normal text.
+
+.. rst:directive:: .. note::
+
+   An especially important bit of information about an API that a user should be
+   aware of when using whatever bit of API the note pertains to.  The content of
+   the directive should be written in complete sentences and include all
+   appropriate punctuation.
+
+   Example::
+
+      .. note::
+
+         This function is not suitable for sending spam e-mails.
+
+.. rst:directive:: .. warning::
+
+   An important bit of information about an API that a user should be very aware
+   of when using whatever bit of API the warning pertains to.  The content of
+   the directive should be written in complete sentences and include all
+   appropriate punctuation. This differs from :rst:dir:`note` in that it is
+   recommended over :rst:dir:`note` for information regarding security.
+
+.. rst:directive:: .. versionadded:: version
+
+   This directive documents the version of the project which added the described
+   feature to the library or C API. When this applies to an entire module, it
+   should be placed at the top of the module section before any prose.
+
+   The first argument must be given and is the version in question; you can add
+   a second argument consisting of a *brief* explanation of the change.
+
+   Example::
+
+      .. versionadded:: 2.5
+         The *spam* parameter.
+
+   Note that there must be no blank line between the directive head and the
+   explanation; this is to make these blocks visually continuous in the markup.
+
+.. rst:directive:: .. versionchanged:: version
+
+   Similar to :rst:dir:`versionadded`, but describes when and what changed in
+   the named feature in some way (new parameters, changed side effects, etc.).
+
+.. rst:directive:: .. deprecated:: version
+
+   Similar to :rst:dir:`versionchanged`, but describes when the feature was
+   deprecated.  An explanation can also be given, for example to inform the
+   reader what should be used instead.  Example::
+
+      .. deprecated:: 3.1
+         Use :func:`spam` instead.
+
+.. rst:directive:: seealso
+
+   Many sections include a list of references to module documentation or
+   external documents.  These lists are created using the :rst:dir:`seealso`
+   directive.
+
+   The :rst:dir:`seealso` directive is typically placed in a section just before
+   any subsections.  For the HTML output, it is shown boxed off from the main
+   flow of the text.
+
+   The content of the :rst:dir:`seealso` directive should be a reST definition
+   list. Example::
+
+      .. seealso::
+
+         Module :py:mod:`zipfile`
+            Documentation of the :py:mod:`zipfile` standard module.
+
+         `GNU tar manual, Basic Tar Format <http://link>`_
+            Documentation for tar archive files, including GNU tar extensions.
+
+   There's also a "short form" allowed that looks like this::
+
+      .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`
+
+   .. versionadded:: 0.5
+      The short form.
+
+.. rst:directive:: .. rubric:: title
+
+   This directive creates a paragraph heading that is not used to create a
+   table of contents node.
+
+   .. note::
+
+      If the *title* of the rubric is "Footnotes" (or the selected language's
+      equivalent), this rubric is ignored by the LaTeX writer, since it is
+      assumed to only contain footnote definitions and therefore would create an
+      empty heading.
+
+.. rst:directive:: centered
+
+   This directive creates a centered boldfaced line of text.  Use it as
+   follows::
+
+      .. centered:: LICENSE AGREEMENT
+
+   .. deprecated:: 1.1
+      This presentation-only directive is a legacy from older versions.
+      Use a :ref:`rst-class <rstclass>` directive instead and add an
+      appropriate style.
+
+.. rst:directive:: hlist
+
+   This directive must contain a bullet list.  It will transform it into a more
+   compact list by either distributing more than one item horizontally, or
+   reducing spacing between items, depending on the builder.
+
+   For builders that support the horizontal distribution, there is a ``columns``
+   option that specifies the number of columns; it defaults to 2.  Example::
+
+      .. hlist::
+         :columns: 3
+
+         * A list of
+         * short items
+         * that should be
+         * displayed
+         * horizontally
+
+   .. versionadded:: 0.6
+
+
+.. _code-examples:
+
+Showing code examples
+---------------------
+
+.. index:: pair: code; examples
+           single: sourcecode
+
+There are multiple ways to show syntax-highlighted literal code blocks in
+Sphinx:
+
+* using :ref:`reST doctest blocks <rst-doctest-blocks>`;
+* using :ref:`reST literal blocks <rst-literal-blocks>`, optionally in
+  combination with the :rst:dir:`highlight` directive;
+* using the :rst:dir:`code-block` directive;
+* and using the :rst:dir:`literalinclude` directive.
+
+Doctest blocks can only be used
+to show interactive Python sessions, while the remaining three can be used for
+other languages. Of these three, literal blocks are useful when an entire
+document, or at least large sections of it, use code blocks with the same
+syntax and which should be styled in the same manner. On the other hand, the
+:rst:dir:`code-block` directive makes more sense when you want more fine-tuned
+control over the styling of each block or when you have a document containing
+code blocks using multiple varied syntaxes. Finally, the
+:rst:dir:`literalinclude` directive is useful for including entire code files
+in your documentation.
+
+In all cases, Syntax highlighting is provided by `Pygments
+<https://pygments.org>`_. When using literal blocks, this is configured using
+any :rst:dir:`highlight` directives in the source file. When a ``highlight``
+directive is encountered, it is used until the next ``highlight`` directive is
+encountered. If there is no ``highlight`` directive in the file, the global
+highlighting language is used. This defaults to ``python`` but can be
+configured using the :confval:`highlight_language` config value. The following
+values are supported:
+
+* ``none`` (no highlighting)
+* ``default`` (similar to ``python3`` but with a fallback to ``none`` without
+  warning highlighting fails; the default when :confval:`highlight_language`
+  isn't set)
+* ``guess`` (let Pygments guess the lexer based on contents, only works with
+  certain well-recognizable languages)
+* ``python``
+* ``rest``
+* ``c``
+* ... and any other `lexer alias that Pygments supports`__
+
+If highlighting with the selected language fails (i.e. Pygments emits an
+"Error" token), the block is not highlighted in any way.
+
+.. important::
+
+   The list of lexer aliases supported is tied to the Pygment version. If you
+   want to ensure consistent highlighting, you should fix your version of
+   Pygments.
+
+__ https://pygments.org/docs/lexers
+
+.. rst:directive:: .. highlight:: language
+
+   Example::
+
+      .. highlight:: c
+
+   This language is used until the next ``highlight`` directive is encountered.
+   As discussed previously, *language* can be any lexer alias supported by
+   Pygments.
+
+   .. rubric:: options
+
+   .. rst:directive:option:: linenothreshold: threshold
+      :type: number (optional)
+
+      Enable to generate line numbers for code blocks.
+
+      This option takes an optional number as threshold parameter.  If any
+      threshold given, the directive will produce line numbers only for the code
+      blocks longer than N lines.  If not given, line numbers will be produced
+      for all of code blocks.
+
+      Example::
+
+         .. highlight:: python
+            :linenothreshold: 5
+
+   .. rst:directive:option:: force
+      :type: no value
+
+      If given, minor errors on highlighting are ignored.
+
+      .. versionadded:: 2.1
+
+.. rst:directive:: .. code-block:: [language]
+                   .. sourcecode:: [language]
+
+   Example::
+
+      .. code-block:: ruby
+
+         Some Ruby code.
+
+   The directive's alias name :rst:dir:`sourcecode` works as well.  This
+   directive takes a language name as an argument.  It can be `any lexer alias
+   supported by Pygments <https://pygments.org/docs/lexers/>`_.  If it is not
+   given, the setting of :rst:dir:`highlight` directive will be used.  If not
+   set, :confval:`highlight_language` will be used.  To display a code example
+   *inline* within other text, rather than as a separate block, you can use the
+   :rst:role:`code` role instead.
+
+   .. versionchanged:: 2.0
+      The ``language`` argument becomes optional.
+
+   .. rubric:: options
+
+   .. rst:directive:option:: linenos
+      :type: no value
+
+      Enable to generate line numbers for the code block::
+
+         .. code-block:: ruby
+            :linenos:
+
+            Some more Ruby code.
+
+   .. rst:directive:option:: lineno-start: number
+      :type: number
+
+      Set the first line number of the code block.  If present, ``linenos``
+      option is also automatically activated::
+
+         .. code-block:: ruby
+            :lineno-start: 10
+
+            Some more Ruby code, with line numbering starting at 10.
+
+      .. versionadded:: 1.3
+
+   .. rst:directive:option:: emphasize-lines: line numbers
+      :type: comma separated numbers
+
+      Emphasize particular lines of the code block::
+
+       .. code-block:: python
+          :emphasize-lines: 3,5
+
+          def some_function():
+              interesting = False
+              print 'This line is highlighted.'
+              print 'This one is not...'
+              print '...but this one is.'
+
+      .. versionadded:: 1.1
+      .. versionchanged:: 1.6.6
+         LaTeX supports the ``emphasize-lines`` option.
+
+   .. rst:directive:option: force
+      :type: no value
+
+      Ignore minor errors on highlighting
+
+      .. versionchanged:: 2.1
+
+   .. rst:directive:option:: caption: caption of code block
+      :type: text
+
+      Set a caption to the code block.
+
+      .. versionadded:: 1.3
+
+   .. rst:directive:option:: name: a label for hyperlink
+      :type: text
+
+      Define implicit target name that can be referenced by using
+      :rst:role:`ref`.  For example::
+
+        .. code-block:: python
+           :caption: this.py
+           :name: this-py
+
+           print 'Explicit is better than implicit.'
+
+      In order to cross-reference a code-block using either the
+      :rst:role:`ref` or the :rst:role:`numref` role, it is necessary
+      that both :strong:`name` and :strong:`caption` be defined. The
+      argument of :strong:`name` can then be given to :rst:role:`numref`
+      to generate the cross-reference. Example::
+
+        See :numref:`this-py` for an example.
+
+      When using :rst:role:`ref`, it is possible to generate a cross-reference
+      with only :strong:`name` defined, provided an explicit title is
+      given. Example::
+
+        See :ref:`this code snippet <this-py>` for an example.
+
+      .. versionadded:: 1.3
+
+   .. rst:directive:option:: class: class names
+      :type: a list of class names separated by spaces
+
+      The class name of the graph.
+
+      .. versionadded:: 1.4
+
+   .. rst:directive:option:: dedent: number
+      :type: number or no value
+
+      Strip indentation characters from the code block.  When number given,
+      leading N characters are removed.  When no argument given, leading spaces
+      are removed via :func:`textwrap.dedent()`.  For example::
+
+         .. code-block:: ruby
+            :linenos:
+            :dedent: 4
+
+                some ruby code
+
+      .. versionadded:: 1.3
+      .. versionchanged:: 3.5
+         Support automatic dedent.
+
+   .. rst:directive:option:: force
+      :type: no value
+
+      If given, minor errors on highlighting are ignored.
+
+      .. versionadded:: 2.1
+
+.. rst:directive:: .. literalinclude:: filename
+
+   Longer displays of verbatim text may be included by storing the example text
+   in an external file containing only plain text.  The file may be included
+   using the ``literalinclude`` directive. [#]_ For example, to include the
+   Python source file :file:`example.py`, use::
+
+      .. literalinclude:: example.py
+
+   The file name is usually relative to the current file's path.  However, if
+   it is absolute (starting with ``/``), it is relative to the top source
+   directory.
+
+   **Additional options**
+
+   Like :rst:dir:`code-block`, the directive supports the ``linenos`` flag
+   option to switch on line numbers, the ``lineno-start`` option to select the
+   first line number, the ``emphasize-lines`` option to emphasize particular
+   lines, the ``name`` option to provide an implicit target name, the
+   ``dedent`` option to strip indentation characters for the code block, and a
+   ``language`` option to select a language different from the current file's
+   standard language. In addition, it supports the ``caption`` option; however,
+   this can be provided with no argument to use the filename as the caption.
+   Example with options::
+
+      .. literalinclude:: example.rb
+         :language: ruby
+         :emphasize-lines: 12,15-18
+         :linenos:
+
+   Tabs in the input are expanded if you give a ``tab-width`` option with the
+   desired tab width.
+
+   Include files are assumed to be encoded in the :confval:`source_encoding`.
+   If the file has a different encoding, you can specify it with the
+   ``encoding`` option::
+
+      .. literalinclude:: example.py
+         :encoding: latin-1
+
+   The directive also supports including only parts of the file.  If it is a
+   Python module, you can select a class, function or method to include using
+   the ``pyobject`` option::
+
+      .. literalinclude:: example.py
+         :pyobject: Timer.start
+
+   This would only include the code lines belonging to the ``start()`` method
+   in the ``Timer`` class within the file.
+
+   Alternately, you can specify exactly which lines to include by giving a
+   ``lines`` option::
+
+      .. literalinclude:: example.py
+         :lines: 1,3,5-10,20-
+
+   This includes the lines 1, 3, 5 to 10 and lines 20 to the last line.
+
+   Another way to control which part of the file is included is to use the
+   ``start-after`` and ``end-before`` options (or only one of them).  If
+   ``start-after`` is given as a string option, only lines that follow the
+   first line containing that string are included.  If ``end-before`` is given
+   as a string option, only lines that precede the first lines containing that
+   string are included. The ``start-at`` and ``end-at`` options behave in a
+   similar way, but the lines containing the matched string are included.
+
+   ``start-after``/``start-at`` and ``end-before``/``end-at`` can have same string.
+   ``start-after``/``start-at`` filter lines before the line that contains
+   option string (``start-at`` will keep the line). Then ``end-before``/``end-at``
+   filter lines after the line that contains option string (``end-at`` will keep
+   the line and ``end-before`` skip the first line).
+
+   .. note::
+
+      If you want to select only ``[second-section]`` of ini file like the
+      following, you can use ``:start-at: [second-section]`` and
+      ``:end-before: [third-section]``:
+
+      .. code-block:: ini
+
+         [first-section]
+
+         var_in_first=true
+
+         [second-section]
+
+         var_in_second=true
+
+         [third-section]
+
+         var_in_third=true
+
+      Useful cases of these option is working with tag comments.
+      ``:start-after: [initialize]`` and ``:end-before: [initialized]`` options
+      keep lines between comments:
+
+      .. code-block:: py
+
+         if __name__ == "__main__":
+             # [initialize]
+             app.start(":8000")
+             # [initialized]
+
+
+   When lines have been selected in any of the ways described above, the line
+   numbers in ``emphasize-lines`` refer to those selected lines, counted
+   consecutively starting at ``1``.
+
+   When specifying particular parts of a file to display, it can be useful to
+   display the original line numbers. This can be done using the
+   ``lineno-match`` option, which is however allowed only when the selection
+   consists of contiguous lines.
+
+   You can prepend and/or append a line to the included code, using the
+   ``prepend`` and ``append`` option, respectively.  This is useful e.g. for
+   highlighting PHP code that doesn't include the ``<?php``/``?>`` markers.
+
+   If you want to show the diff of the code, you can specify the old file by
+   giving a ``diff`` option::
+
+      .. literalinclude:: example.py
+         :diff: example.py.orig
+
+   This shows the diff between ``example.py`` and ``example.py.orig`` with
+   unified diff format.
+
+   A ``force`` option can ignore minor errors on highlighting.
+
+   .. versionchanged:: 0.4.3
+      Added the ``encoding`` option.
+
+   .. versionchanged:: 0.6
+      Added the ``pyobject``, ``lines``, ``start-after`` and ``end-before``
+      options, as well as support for absolute filenames.
+
+   .. versionchanged:: 1.0
+      Added the ``prepend``, ``append``, and ``tab-width`` options.
+
+   .. versionchanged:: 1.3
+      Added the ``diff``, ``lineno-match``, ``caption``, ``name``, and
+      ``dedent`` options.
+
+   .. versionchanged:: 1.4
+      Added the ``class`` option.
+
+   .. versionchanged:: 1.5
+      Added the ``start-at``, and ``end-at`` options.
+
+   .. versionchanged:: 1.6
+      With both ``start-after`` and ``lines`` in use, the first line as per
+      ``start-after`` is considered to be with line number ``1`` for ``lines``.
+
+   .. versionchanged:: 2.1
+      Added the ``force`` option.
+
+   .. versionchanged:: 3.5
+      Support automatic dedent.
+
+.. _glossary-directive:
+
+Glossary
+--------
+
+.. rst:directive:: .. glossary::
+
+   This directive must contain a reST definition-list-like markup with terms and
+   definitions.  The definitions will then be referenceable with the
+   :rst:role:`term` role.  Example::
+
+      .. glossary::
+
+         environment
+            A structure where information about all documents under the root is
+            saved, and used for cross-referencing.  The environment is pickled
+            after the parsing stage, so that successive runs only need to read
+            and parse new and changed documents.
+
+         source directory
+            The directory which, including its subdirectories, contains all
+            source files for one Sphinx project.
+
+   In contrast to regular definition lists, *multiple* terms per entry are
+   allowed, and inline markup is allowed in terms.  You can link to all of the
+   terms.  For example::
+
+      .. glossary::
+
+         term 1
+         term 2
+            Definition of both terms.
+
+   (When the glossary is sorted, the first term determines the sort order.)
+
+   If you want to specify "grouping key" for general index entries, you can put
+   a "key" as "term : key". For example::
+
+      .. glossary::
+
+         term 1 : A
+         term 2 : B
+            Definition of both terms.
+
+   Note that "key" is used for grouping key as is.
+   The "key" isn't normalized; key "A" and "a" become different groups.
+   The whole characters in "key" is used instead of a first character; it is
+   used for "Combining Character Sequence" and "Surrogate Pairs" grouping key.
+
+   In i18n situation, you can specify "localized term : key" even if original
+   text only have "term" part. In this case, translated "localized term" will be
+   categorized in "key" group.
+
+   .. versionadded:: 0.6
+      You can now give the glossary directive a ``:sorted:`` flag that will
+      automatically sort the entries alphabetically.
+
+   .. versionchanged:: 1.1
+      Now supports multiple terms and inline markup in terms.
+
+   .. versionchanged:: 1.4
+      Index key for glossary term should be considered *experimental*.
+
+   .. versionchanged:: 4.4
+      In internationalized documentation, the ``:sorted:`` flag sorts
+      according to translated terms.
+
+Meta-information markup
+-----------------------
+
+.. rst:directive:: .. sectionauthor:: name <email>
+
+   Identifies the author of the current section.  The argument should include
+   the author's name such that it can be used for presentation and email
+   address.  The domain name portion of the address should be lower case.
+   Example::
+
+      .. sectionauthor:: Guido van Rossum <guido@python.org>
+
+   By default, this markup isn't reflected in the output in any way (it helps
+   keep track of contributions), but you can set the configuration value
+   :confval:`show_authors` to ``True`` to make them produce a paragraph in the
+   output.
+
+
+.. rst:directive:: .. codeauthor:: name <email>
+
+   The :rst:dir:`codeauthor` directive, which can appear multiple times, names
+   the authors of the described code, just like :rst:dir:`sectionauthor` names
+   the author(s) of a piece of documentation.  It too only produces output if
+   the :confval:`show_authors` configuration value is ``True``.
+
+
+Index-generating markup
+-----------------------
+
+Sphinx automatically creates index entries from all object descriptions (like
+functions, classes or attributes) like discussed in
+:doc:`/usage/restructuredtext/domains`.
+
+However, there is also explicit markup available, to make the index more
+comprehensive and enable index entries in documents where information is not
+mainly contained in information units, such as the language reference.
+
+.. rst:directive:: .. index:: <entries>
+
+   This directive contains one or more index entries.  Each entry consists of a
+   type and a value, separated by a colon.
+
+   For example::
+
+      .. index::
+         single: execution; context
+         pair: module; __main__
+         pair: module; sys
+         triple: module; search; path
+         seealso: scope
+
+      The execution context
+      ---------------------
+
+      ...
+
+   This directive contains five entries, which will be converted to entries in
+   the generated index which link to the exact location of the index statement
+   (or, in case of offline media, the corresponding page number).
+
+   Since index directives generate cross-reference targets at their location in
+   the source, it makes sense to put them *before* the thing they refer to --
+   e.g. a heading, as in the example above.
+
+   The possible entry types are:
+
+   single
+      Creates a single index entry.
+      Can be made a sub-entry by separating the sub-entry text with a semicolon
+      (this notation is also used below to describe what entries are created).
+      Examples:
+
+      .. code:: reStructuredText
+
+         .. index:: single: execution
+                    single: execution; context
+
+      - ``single: execution`` creates an index entry labelled ``execution``.
+      - ``single: execution; context`` creates an sub-entry of ``execution``
+        labelled ``context``.
+   pair
+      A shortcut to create two index entries.
+      The pair of values must be separated by a semicolon.
+      Example:
+
+      .. code:: reStructuredText
+
+         .. index:: pair: loop; statement
+
+      This would create two index entries; ``loop; statement`` and ``statement; loop``.
+   triple
+      A shortcut to create three index entries.
+      All three values must be separated by a semicolon.
+      Example:
+
+      .. code:: reStructuredText
+
+         .. index:: triple: module; search; path
+
+      This would create three index entries; ``module; search path``,
+      ``search; path, module``, and ``path; module search``.
+   see
+      A shortcut to create an index entry that refers to another entry.
+      Example:
+
+      .. code:: reStructuredText
+
+         .. index:: see: entry; other
+
+      This would create an index entry referring from ``entry`` to ``other``
+      (i.e. 'entry': See 'other').
+   seealso
+      Like ``see``, but inserts 'see also' instead of 'see'.
+   module, keyword, operator, object, exception, statement, builtin
+      These **deprecated** shortcuts all create two index entries.
+      For example, ``module: hashlib`` creates the entries ``module; hashlib``
+      and ``hashlib; module``.
+
+      .. deprecated:: 1.0
+         These Python-specific entry types are deprecated.
+
+      .. versionchanged:: 7.1
+         Removal version set to Sphinx 9.0.
+         Using these entry types will now emit warnings with the ``index`` category.
+
+   You can mark up "main" index entries by prefixing them with an exclamation
+   mark.  The references to "main" entries are emphasized in the generated
+   index.  For example, if two pages contain ::
+
+      .. index:: Python
+
+   and one page contains ::
+
+      .. index:: ! Python
+
+   then the backlink to the latter page is emphasized among the three backlinks.
+
+   For index directives containing only "single" entries, there is a shorthand
+   notation::
+
+      .. index:: BNF, grammar, syntax, notation
+
+   This creates four index entries.
+
+   .. versionchanged:: 1.1
+      Added ``see`` and ``seealso`` types, as well as marking main entries.
+
+   .. rubric:: options
+
+   .. rst:directive:option:: name: a label for hyperlink
+      :type: text
+
+      Define implicit target name that can be referenced by using
+      :rst:role:`ref`.  For example::
+
+        .. index:: Python
+           :name: py-index
+
+   .. versionadded:: 3.0
+
+.. rst:role:: index
+
+   While the :rst:dir:`index` directive is a block-level markup and links to the
+   beginning of the next paragraph, there is also a corresponding role that sets
+   the link target directly where it is used.
+
+   The content of the role can be a simple phrase, which is then kept in the
+   text and used as an index entry.  It can also be a combination of text and
+   index entry, styled like with explicit targets of cross-references.  In that
+   case, the "target" part can be a full entry as described for the directive
+   above.  For example::
+
+      This is a normal reST :index:`paragraph` that contains several
+      :index:`index entries <pair: index; entry>`.
+
+   .. versionadded:: 1.1
+
+
+.. _tags:
+
+Including content based on tags
+-------------------------------
+
+.. rst:directive:: .. only:: <expression>
+
+   Include the content of the directive only if the *expression* is true.  The
+   expression should consist of tags, like this::
+
+      .. only:: html and draft
+
+   Undefined tags are false, defined tags (via the ``-t`` command-line option or
+   within :file:`conf.py`, see :ref:`here <conf-tags>`) are true.  Boolean
+   expressions, also using parentheses (like ``html and (latex or draft)``) are
+   supported.
+
+   The *format* and the *name* of the current builder (``html``, ``latex`` or
+   ``text``) are always set as a tag [#]_.  To make the distinction between
+   format and name explicit, they are also added with the prefix ``format_`` and
+   ``builder_``, e.g. the epub builder defines the tags  ``html``, ``epub``,
+   ``format_html`` and ``builder_epub``.
+
+   These standard tags are set *after* the configuration file is read, so they
+   are not available there.
+
+   All tags must follow the standard Python identifier syntax as set out in
+   the `Identifiers and keywords
+   <https://docs.python.org/3/reference/lexical_analysis.html#identifiers>`_
+   documentation.  That is, a tag expression may only consist of tags that
+   conform to the syntax of Python variables.  In ASCII, this consists of the
+   uppercase and lowercase letters ``A`` through ``Z``, the underscore ``_``
+   and, except for the first character, the digits ``0`` through ``9``.
+
+   .. versionadded:: 0.6
+   .. versionchanged:: 1.2
+      Added the name of the builder and the prefixes.
+
+   .. warning::
+
+      This directive is designed to control only content of document.  It could
+      not control sections, labels and so on.
+
+.. _table-directives:
+
+Tables
+------
+
+Use :ref:`reStructuredText tables <rst-tables>`, i.e. either
+
+- grid table syntax (:duref:`ref <grid-tables>`),
+- simple table syntax (:duref:`ref <simple-tables>`),
+- :dudir:`csv-table` syntax,
+- or :dudir:`list-table` syntax.
+
+The :dudir:`table` directive serves as optional wrapper of the *grid* and
+*simple* syntaxes.
+
+They work fine in HTML output, but rendering tables to LaTeX is complex.
+Check the :confval:`latex_table_style`.
+
+.. versionchanged:: 1.6
+   Merged cells (multi-row, multi-column, both) from grid tables containing
+   complex contents such as multiple paragraphs, blockquotes, lists, literal
+   blocks, will render correctly to LaTeX output.
+
+.. rst:directive:: .. tabularcolumns:: column spec
+
+   This directive influences only the LaTeX output for the next table in
+   source.  The mandatory argument is a column specification (known as an
+   "alignment preamble" in LaTeX idiom).  Please refer to a LaTeX
+   documentation, such as the `wiki page`_, for basics of such a column
+   specification.
+
+   .. _wiki page: https://en.wikibooks.org/wiki/LaTeX/Tables
+
+   .. versionadded:: 0.3
+
+   .. note::
+
+      :rst:dir:`tabularcolumns` conflicts with ``:widths:`` option of table
+      directives.  If both are specified, ``:widths:`` option will be ignored.
+
+   Sphinx will render tables with more than 30 rows with ``longtable``.
+   Besides the ``l``, ``r``, ``c`` and ``p{width}`` column specifiers, one can
+   also use ``\X{a}{b}`` (new in version 1.5) which configures the column
+   width to be a fraction ``a/b`` of the total line width and ``\Y{f}`` (new
+   in version 1.6) where ``f`` is a decimal: for example ``\Y{0.2}`` means that
+   the column will occupy ``0.2`` times the line width.
+
+   When this directive is used for a table with at most 30 rows, Sphinx will
+   render it with ``tabulary``.  One can then use specific column types ``L``
+   (left), ``R`` (right), ``C`` (centered) and ``J`` (justified).  They have
+   the effect of a ``p{width}`` (i.e. each cell is a LaTeX ``\parbox``) with
+   the specified internal text alignment and an automatically computed
+   ``width``.
+
+   .. warning::
+
+      - Cells that contain list-like elements such as object descriptions,
+        blockquotes or any kind of lists are not compatible with the ``LRCJ``
+        column types.  The column type must then be some ``p{width}`` with an
+        explicit ``width`` (or ``\X{a}{b}`` or ``\Y{f}``).
+
+      - Literal blocks do not work with ``tabulary`` at all.  Sphinx will
+        fall back to ``tabular`` or ``longtable`` environments and generate a
+        suitable column specification.
+
+In absence of the :rst:dir:`tabularcolumns` directive, and for a table with at
+most 30 rows and no problematic cells as described in the above warning,
+Sphinx uses ``tabulary`` and the ``J`` column-type for every column.
+
+.. versionchanged:: 1.6
+
+   Formerly, the ``L`` column-type was used (text is flushed-left).  To revert
+   to this, include ``\newcolumntype{T}{L}`` in the LaTeX preamble, as in fact
+   Sphinx uses ``T`` and sets it by default to be an alias of ``J``.
+
+.. hint::
+
+   A frequent issue with ``tabulary`` is that columns with little contents
+   appear to be "squeezed".  One can add to the LaTeX preamble for example
+   ``\setlength{\tymin}{40pt}`` to ensure a minimal column width of ``40pt``,
+   the ``tabulary`` default of ``10pt`` being too small.
+
+.. hint::
+
+   To force usage of the LaTeX ``longtable`` environment pass ``longtable`` as
+   a ``:class:`` option to :dudir:`table`, :dudir:`csv-table`, or
+   :dudir:`list-table`.  Use :ref:`rst-class <rstclass>` for other tables.
+
+Math
+----
+
+The input language for mathematics is LaTeX markup.  This is the de-facto
+standard for plain-text math notation and has the added advantage that no
+further translation is necessary when building LaTeX output.
+
+Keep in mind that when you put math markup in **Python docstrings** read by
+:mod:`autodoc <sphinx.ext.autodoc>`, you either have to double all backslashes,
+or use Python raw strings (``r"raw"``).
+
+.. rst:directive:: math
+
+   Directive for displayed math (math that takes the whole line for itself).
+
+   The directive supports multiple equations, which should be separated by a
+   blank line::
+
+      .. math::
+
+         (a + b)^2 = a^2 + 2ab + b^2
+
+         (a - b)^2 = a^2 - 2ab + b^2
+
+   In addition, each single equation is set within a ``split`` environment,
+   which means that you can have multiple aligned lines in an equation,
+   aligned at ``&`` and separated by ``\\``::
+
+      .. math::
+
+         (a + b)^2  &=  (a + b)(a + b) \\
+                    &=  a^2 + 2ab + b^2
+
+   For more details, look into the documentation of the `AmSMath LaTeX
+   package`_.
+
+   When the math is only one line of text, it can also be given as a directive
+   argument::
+
+      .. math:: (a + b)^2 = a^2 + 2ab + b^2
+
+   Normally, equations are not numbered.  If you want your equation to get a
+   number, use the ``label`` option.  When given, it selects an internal label
+   for the equation, by which it can be cross-referenced, and causes an equation
+   number to be issued.  See :rst:role:`eq` for an example.  The numbering
+   style depends on the output format.
+
+   There is also an option ``nowrap`` that prevents any wrapping of the given
+   math in a math environment.  When you give this option, you must make sure
+   yourself that the math is properly set up.  For example::
+
+      .. math::
+         :nowrap:
+
+         \begin{eqnarray}
+            y    & = & ax^2 + bx + c \\
+            f(x) & = & x^2 + 2xy + y^2
+         \end{eqnarray}
+
+.. _AmSMath LaTeX package: https://www.ams.org/publications/authors/tex/amslatex
+
+.. seealso::
+
+   :ref:`math-support`
+      Rendering options for math with HTML builders.
+
+   :confval:`latex_engine`
+      Explains how to configure LaTeX builder to support Unicode literals in
+      math mark-up.
+
+
+Grammar production displays
+---------------------------
+
+Special markup is available for displaying the productions of a formal grammar.
+The markup is simple and does not attempt to model all aspects of BNF (or any
+derived forms), but provides enough to allow context-free grammars to be
+displayed in a way that causes uses of a symbol to be rendered as hyperlinks to
+the definition of the symbol.  There is this directive:
+
+.. rst:directive:: .. productionlist:: [productionGroup]
+
+   This directive is used to enclose a group of productions.  Each production
+   is given on a single line and consists of a name, separated by a colon from
+   the following definition.  If the definition spans multiple lines, each
+   continuation line must begin with a colon placed at the same column as in
+   the first line.
+   Blank lines are not allowed within ``productionlist`` directive arguments.
+
+   The definition can contain token names which are marked as interpreted text
+   (e.g., "``sum ::= `integer` "+" `integer```") -- this generates
+   cross-references to the productions of these tokens.  Outside of the
+   production list, you can reference to token productions using
+   :rst:role:`token`.
+
+   The *productionGroup* argument to :rst:dir:`productionlist` serves to
+   distinguish different sets of production lists that belong to different
+   grammars.  Multiple production lists with the same *productionGroup* thus
+   define rules in the same scope.
+
+   Inside of the production list, tokens implicitly refer to productions
+   from the current group. You can refer to the production of another
+   grammar by prefixing the token with its group name and a colon, e.g,
+   "``otherGroup:sum``". If the group of the token should not be shown in
+   the production, it can be prefixed by a tilde, e.g.,
+   "``~otherGroup:sum``". To refer to a production from an unnamed
+   grammar, the token should be prefixed by a colon, e.g., "``:sum``".
+
+   Outside of the production list,
+   if you have given a *productionGroup* argument you must prefix the
+   token name in the cross-reference with the group name and a colon,
+   e.g., "``myGroup:sum``" instead of just "``sum``".
+   If the group should not be shown in the title of the link either
+   an explicit title can be given (e.g., "``myTitle <myGroup:sum>``"),
+   or the target can be prefixed with a tilde (e.g., "``~myGroup:sum``").
+
+   Note that no further reST parsing is done in the production, so that you
+   don't have to escape ``*`` or ``|`` characters.
+
+The following is an example taken from the Python Reference Manual::
+
+   .. productionlist::
+      try_stmt: try1_stmt | try2_stmt
+      try1_stmt: "try" ":" `suite`
+               : ("except" [`expression` ["," `target`]] ":" `suite`)+
+               : ["else" ":" `suite`]
+               : ["finally" ":" `suite`]
+      try2_stmt: "try" ":" `suite`
+               : "finally" ":" `suite`
+
+
+.. rubric:: Footnotes
+
+.. [#] The LaTeX writer only refers the ``maxdepth`` option of first toctree
+       directive in the document.
+
+.. [#] A note on available globbing syntax: you can use the standard shell
+       constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that
+       these all don't match slashes.  A double star ``**`` can be used to
+       match any sequence of characters *including* slashes.
+
+.. [#] There is a standard ``.. include`` directive, but it raises errors if the
+       file is not found.  This one only emits a warning.
+
+.. [#] For most builders name and format are the same. At the moment only
+       builders derived from the html builder distinguish between the builder
+       format and the builder name.
+
+       Note that the current builder tag is not available in ``conf.py``, it is
+       only available after the builder is initialized.
diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst
new file mode 100644
index 0000000..729e651
--- /dev/null
+++ b/doc/usage/restructuredtext/domains.rst
@@ -0,0 +1,2303 @@
+.. highlight:: rst
+
+=======
+Domains
+=======
+
+.. versionadded:: 1.0
+
+Originally, Sphinx was conceived for a single project, the documentation of the
+Python language.  Shortly afterwards, it was made available for everyone as a
+documentation tool, but the documentation of Python modules remained deeply
+built in -- the most fundamental directives, like ``function``, were designed
+for Python objects.  Since Sphinx has become somewhat popular, interest
+developed in using it for many different purposes: C/C++ projects, JavaScript,
+or even reStructuredText markup (like in this documentation).
+
+While this was always possible, it is now much easier to easily support
+documentation of projects using different programming languages or even ones
+not supported by the main Sphinx distribution, by providing a **domain** for
+every such purpose.
+
+A domain is a collection of markup (reStructuredText :term:`directive`\ s and
+:term:`role`\ s) to describe and link to :term:`object`\ s belonging together,
+e.g. elements of a programming language.  Directive and role names in a domain
+have names like ``domain:name``, e.g. ``py:function``.  Domains can also
+provide custom indices (like the Python Module Index).
+
+Having domains means that there are no naming problems when one set of
+documentation wants to refer to e.g. C++ and Python classes.  It also means
+that extensions that support the documentation of whole new languages are much
+easier to write.
+
+This section describes what the domains that are included with Sphinx provide.
+The domain API is documented as well, in the section :ref:`domain-api`.
+
+
+.. _basic-domain-markup:
+
+Basic Markup
+------------
+
+Most domains provide a number of :dfn:`object description directives`, used to
+describe specific objects provided by modules.  Each directive requires one or
+more signatures to provide basic information about what is being described, and
+the content should be the description.
+
+A domain will typically keep an internal index of all entities to aid
+cross-referencing.
+Typically it will also add entries in the shown general index.
+If you want to suppress the addition of an entry in the shown index, you can
+give the directive option flag ``:no-index-entry:``.
+If you want to exclude the object description from the table of contents, you
+can give the directive option flag ``:no-contents-entry:``.
+If you want to typeset an object description, without even making it available
+for cross-referencing, you can give the directive option flag ``:no-index:``
+(which implies ``:no-index-entry:``).
+If you do not want to typeset anything, you can give the directive option flag
+``:no-typesetting:``.  This can for example be used to create only a target and
+index entry for later reference.
+Though, note that not every directive in every domain may support these
+options.
+
+.. versionadded:: 3.2
+   The directive option ``noindexentry`` in the Python, C, C++, and Javascript
+   domains.
+
+.. versionadded:: 5.2.3
+   The directive option ``:nocontentsentry:`` in the Python, C, C++, Javascript,
+   and reStructuredText domains.
+
+.. versionadded:: 7.2
+   The directive option ``no-typesetting`` in the Python, C, C++, Javascript,
+   and reStructuredText domains.
+
+.. versionchanged:: 7.2
+
+   *  The directive option ``:noindex:`` was renamed
+      to ``:no-index:``.
+   *  The directive option ``:noindexentry:`` was renamed
+      to ``:no-index-entry:``.
+   *  The directive option ``:nocontentsentry:`` was renamed
+      to ``:no-contents-entry:``.
+
+   The previous names are retained as aliases,
+   but will be deprecated and removed
+   in a future version of Sphinx.
+
+An example using a Python domain directive::
+
+   .. py:function:: spam(eggs)
+                    ham(eggs)
+
+      Spam or ham the foo.
+
+This describes the two Python functions ``spam`` and ``ham``.  (Note that when
+signatures become too long, you can break them if you add a backslash to lines
+that are continued in the next line.  Example::
+
+   .. py:function:: filterwarnings(action, message='', category=Warning, \
+                                   module='', lineno=0, append=False)
+      :no-index:
+
+(This example also shows how to use the ``:no-index:`` flag.)
+
+The domains also provide roles that link back to these object descriptions.
+For example, to link to one of the functions described in the example above,
+you could say ::
+
+   The function :py:func:`spam` does a similar thing.
+
+As you can see, both directive and role names contain the domain name and the
+directive name.
+
+The directive option ``:no-typesetting:`` can be used to create a target
+(and index entry) which can later be referenced
+by the roles provided by the domain.
+This is particularly useful for literate programming:
+
+.. code-block:: rst
+
+   .. py:function:: spam(eggs)
+      :no-typesetting:
+
+   .. code::
+
+      def spam(eggs):
+          pass
+
+   The function :py:func:`spam` does nothing.
+
+.. rubric:: Default Domain
+
+For documentation describing objects from solely one domain, authors will not
+have to state again its name at each directive, role, etc... after
+having specified a default. This can be done either via the config
+value :confval:`primary_domain` or via this directive:
+
+.. rst:directive:: .. default-domain:: name
+
+   Select a new default domain.  While the :confval:`primary_domain` selects a
+   global default, this only has an effect within the same file.
+
+If no other default is selected, the Python domain (named ``py``) is the
+default one, mostly for compatibility with documentation written for older
+versions of Sphinx.
+
+Directives and roles that belong to the default domain can be mentioned without
+giving the domain name, i.e. ::
+
+   .. function:: pyfunc()
+
+      Describes a Python function.
+
+   Reference to :func:`pyfunc`.
+
+Cross-referencing syntax
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+For cross-reference roles provided by domains, the same facilities exist as for
+general cross-references.  See :ref:`xref-syntax`.
+
+In short:
+
+* You may supply an explicit title and reference target: ``:role:`title
+  <target>``` will refer to *target*, but the link text will be *title*.
+
+* If you prefix the content with ``!``, no reference/hyperlink will be created.
+
+* If you prefix the content with ``~``, the link text will only be the last
+  component of the target.  For example, ``:py:meth:`~Queue.Queue.get``` will
+  refer to ``Queue.Queue.get`` but only display ``get`` as the link text.
+
+.. _python-domain:
+
+The Python Domain
+-----------------
+
+The Python domain (name **py**) provides the following directives for module
+declarations:
+
+.. rst:directive:: .. py:module:: name
+
+   This directive marks the beginning of the description of a module (or package
+   submodule, in which case the name should be fully qualified, including the
+   package name).  A description of the module such as the docstring can be
+   placed in the body of the directive.
+
+   This directive will also cause an entry in the global module index.
+
+   .. versionchanged:: 5.2
+
+      Module directives support body content.
+
+   .. rubric:: options
+
+   .. rst:directive:option:: platform: platforms
+      :type: comma separated list
+
+      Indicate platforms which the module is available (if it is available on
+      all platforms, the option should be omitted).  The keys are short
+      identifiers; examples that are in use include "IRIX", "Mac", "Windows"
+      and "Unix".  It is important to use a key which has already been used when
+      applicable.
+
+   .. rst:directive:option:: synopsis: purpose
+      :type: text
+
+      Consist of one sentence describing the module's purpose -- it is currently
+      only used in the Global Module Index.
+
+   .. rst:directive:option:: deprecated
+      :type: no argument
+
+      Mark a module as deprecated; it will be designated as such in various
+      locations then.
+
+
+
+.. rst:directive:: .. py:currentmodule:: name
+
+   This directive tells Sphinx that the classes, functions etc. documented from
+   here are in the given module (like :rst:dir:`py:module`), but it will not
+   create index entries, an entry in the Global Module Index, or a link target
+   for :rst:role:`py:mod`.  This is helpful in situations where documentation
+   for things in a module is spread over multiple files or sections -- one
+   location has the :rst:dir:`py:module` directive, the others only
+   :rst:dir:`py:currentmodule`.
+
+The following directives are provided for module and class contents:
+
+.. rst:directive:: .. py:function:: name(parameters)
+                   .. py:function:: name[type parameters](parameters)
+
+   Describes a module-level function.
+   The signature should include the parameters,
+   together with optional type parameters,
+   as given in the Python function definition, see :ref:`signatures`.
+   For example::
+
+      .. py:function:: Timer.repeat(repeat=3, number=1_000_000)
+      .. py:function:: add[T](a: T, b: T) -> T
+
+   For methods you should use :rst:dir:`py:method`.
+
+   The description normally includes information about the parameters required
+   and how they are used (especially whether mutable objects passed as
+   parameters are modified), side effects, and possible exceptions.
+
+   This information can (in any ``py`` directive) optionally be given in a
+   structured form, see :ref:`info-field-lists`.
+
+   .. rubric:: options
+
+   .. rst:directive:option:: async
+      :type: no value
+
+      Indicate the function is an async function.
+
+      .. versionadded:: 2.1
+
+   .. rst:directive:option:: canonical
+      :type: full qualified name including module name
+
+      Describe the location where the object is defined if the object is
+      imported from other modules
+
+      .. versionadded:: 4.0
+
+   .. rst::directive:option:: module
+      :type: text
+
+      Describe the location where the object is defined.  The default value is
+      the module specified by :rst:dir:`py:currentmodule`.
+
+   .. rst:directive:option:: single-line-parameter-list
+      :type: no value
+
+      Ensures that the function's arguments will be emitted on a single logical
+      line, overriding :confval:`python_maximum_signature_line_length` and
+      :confval:`maximum_signature_line_length`.
+
+      .. versionadded:: 7.1
+
+   .. rst:directive:option:: single-line-type-parameter-list
+      :type: no value
+
+      Ensure that the function's type parameters are emitted on a single
+      logical line, overriding :confval:`python_maximum_signature_line_length`
+      and :confval:`maximum_signature_line_length`.
+
+      .. versionadded:: 7.1
+
+
+.. rst:directive:: .. py:data:: name
+
+   Describes global data in a module, including both variables and values used
+   as "defined constants."  Class and object attributes are not documented
+   using this environment.
+
+   .. rubric:: options
+
+   .. rst:directive:option:: type: type of the variable
+      :type: text
+
+      .. versionadded:: 2.4
+
+   .. rst:directive:option:: value: initial value of the variable
+      :type: text
+
+      .. versionadded:: 2.4
+
+   .. rst:directive:option:: canonical
+      :type: full qualified name including module name
+
+      Describe the location where the object is defined if the object is
+      imported from other modules
+
+      .. versionadded:: 4.0
+
+   .. rst::directive:option:: module
+      :type: text
+
+      Describe the location where the object is defined.  The default value is
+      the module specified by :rst:dir:`py:currentmodule`.
+
+.. rst:directive:: .. py:exception:: name
+                   .. py:exception:: name(parameters)
+                   .. py:exception:: name[type parmeters](parameters)
+
+   Describes an exception class.
+   The signature can, but need not include parentheses with constructor arguments,
+   or may optionally include type parameters (see :pep:`695`).
+
+   .. rubric:: options
+
+   .. rst:directive:option:: final
+      :type: no value
+
+      Indicate the class is a final class.
+
+      .. versionadded:: 3.1
+
+   .. rst::directive:option:: module
+      :type: text
+
+      Describe the location where the object is defined.  The default value is
+      the module specified by :rst:dir:`py:currentmodule`.
+
+   .. rst:directive:option:: single-line-parameter-list
+      :type: no value
+
+      See :rst:dir:`py:class:single-line-parameter-list`.
+
+      .. versionadded:: 7.1
+
+   .. rst:directive:option:: single-line-type-parameter-list
+      :type: no value
+
+      See :rst:dir:`py:class:single-line-type-parameter-list`.
+
+      .. versionadded:: 7.1
+
+.. rst:directive:: .. py:class:: name
+                   .. py:class:: name(parameters)
+                   .. py:class:: name[type parmeters](parameters)
+
+   Describes a class.
+   The signature can optionally include type parameters (see :pep:`695`)
+   or parentheses with parameters which will be shown as the constructor arguments.
+   See also :ref:`signatures`.
+
+   Methods and attributes belonging to the class should be placed in this
+   directive's body.  If they are placed outside, the supplied name should
+   contain the class name so that cross-references still work.  Example::
+
+      .. py:class:: Foo
+
+         .. py:method:: quux()
+
+      -- or --
+
+      .. py:class:: Bar
+
+      .. py:method:: Bar.quux()
+
+   The first way is the preferred one.
+
+   .. rubric:: options
+
+   .. rst:directive:option:: canonical
+      :type: full qualified name including module name
+
+      Describe the location where the object is defined if the object is
+      imported from other modules
+
+      .. versionadded:: 4.0
+
+   .. rst:directive:option:: final
+      :type: no value
+
+      Indicate the class is a final class.
+
+      .. versionadded:: 3.1
+
+   .. rst::directive:option:: module
+      :type: text
+
+      Describe the location where the object is defined.  The default value is
+      the module specified by :rst:dir:`py:currentmodule`.
+
+   .. rst:directive:option:: single-line-parameter-list
+      :type: no value
+
+      Ensures that the class constructor's arguments will be emitted on a single
+      logical line, overriding :confval:`python_maximum_signature_line_length`
+      and :confval:`maximum_signature_line_length`.
+
+      .. versionadded:: 7.1
+
+   .. rst:directive:option:: single-line-type-parameter-list
+      :type: no value
+
+      Ensure that the class type parameters are emitted on a single logical
+      line, overriding :confval:`python_maximum_signature_line_length` and
+      :confval:`maximum_signature_line_length`.
+
+.. rst:directive:: .. py:attribute:: name
+
+   Describes an object data attribute.  The description should include
+   information about the type of the data to be expected and whether it may be
+   changed directly.
+
+   .. rubric:: options
+
+   .. rst:directive:option:: type: type of the attribute
+      :type: text
+
+      .. versionadded:: 2.4
+
+   .. rst:directive:option:: value: initial value of the attribute
+      :type: text
+
+      .. versionadded:: 2.4
+
+   .. rst:directive:option:: canonical
+      :type: full qualified name including module name
+
+      Describe the location where the object is defined if the object is
+      imported from other modules
+
+      .. versionadded:: 4.0
+
+   .. rst::directive:option:: module
+      :type: text
+
+      Describe the location where the object is defined.  The default value is
+      the module specified by :rst:dir:`py:currentmodule`.
+
+.. rst:directive:: .. py:property:: name
+
+   Describes an object property.
+
+   .. versionadded:: 4.0
+
+   .. rubric:: options
+
+   .. rst:directive:option:: abstractmethod
+      :type: no value
+
+      Indicate the property is abstract.
+
+   .. rst:directive:option:: classmethod
+      :type: no value
+
+      Indicate the property is a classmethod.
+
+      .. versionaddedd: 4.2
+
+   .. rst:directive:option:: type: type of the property
+      :type: text
+
+   .. rst::directive:option:: module
+      :type: text
+
+      Describe the location where the object is defined.  The default value is
+      the module specified by :rst:dir:`py:currentmodule`.
+
+.. rst:directive:: .. py:method:: name(parameters)
+                   .. py:method:: name[type parameters](parameters)
+
+   Describes an object method.  The parameters should not include the ``self``
+   parameter.  The description should include similar information to that
+   described for ``function``.  See also :ref:`signatures` and
+   :ref:`info-field-lists`.
+
+   .. rubric:: options
+
+   .. rst:directive:option:: abstractmethod
+      :type: no value
+
+      Indicate the method is an abstract method.
+
+      .. versionadded:: 2.1
+
+   .. rst:directive:option:: async
+      :type: no value
+
+      Indicate the method is an async method.
+
+      .. versionadded:: 2.1
+
+   .. rst:directive:option:: canonical
+      :type: full qualified name including module name
+
+      Describe the location where the object is defined if the object is
+      imported from other modules
+
+      .. versionadded:: 4.0
+
+   .. rst:directive:option:: classmethod
+      :type: no value
+
+      Indicate the method is a class method.
+
+      .. versionadded:: 2.1
+
+   .. rst:directive:option:: final
+      :type: no value
+
+      Indicate the class is a final method.
+
+      .. versionadded:: 3.1
+
+   .. rst::directive:option:: module
+      :type: text
+
+      Describe the location where the object is defined.  The default value is
+      the module specified by :rst:dir:`py:currentmodule`.
+
+   .. rst:directive:option:: single-line-parameter-list
+      :type: no value
+
+      Ensures that the method's arguments will be emitted on a single logical
+      line, overriding :confval:`python_maximum_signature_line_length` and
+      :confval:`maximum_signature_line_length`.
+
+      .. versionadded:: 7.1
+
+   .. rst:directive:option:: single-line-type-parameter-list
+      :type: no value
+
+      Ensure that the method's type parameters are emitted on a single logical
+      line, overriding :confval:`python_maximum_signature_line_length` and
+      :confval:`maximum_signature_line_length`.
+
+      .. versionadded:: 7.2
+
+   .. rst:directive:option:: staticmethod
+      :type: no value
+
+      Indicate the method is a static method.
+
+      .. versionadded:: 2.1
+
+
+.. rst:directive:: .. py:staticmethod:: name(parameters)
+                   .. py:staticmethod:: name[type parameters](parameters)
+
+   Like :rst:dir:`py:method`, but indicates that the method is a static method.
+
+   .. versionadded:: 0.4
+
+.. rst:directive:: .. py:classmethod:: name(parameters)
+                   .. py:classmethod:: name[type parameters](parameters)
+
+   Like :rst:dir:`py:method`, but indicates that the method is a class method.
+
+   .. versionadded:: 0.6
+
+.. rst:directive:: .. py:decorator:: name
+                   .. py:decorator:: name(parameters)
+                   .. py:decorator:: name[type parameters](parameters)
+
+   Describes a decorator function.  The signature should represent the usage as
+   a decorator.  For example, given the functions
+
+   .. code-block:: python
+
+      def removename(func):
+          func.__name__ = ''
+          return func
+
+      def setnewname(name):
+          def decorator(func):
+              func.__name__ = name
+              return func
+          return decorator
+
+   the descriptions should look like this::
+
+      .. py:decorator:: removename
+
+         Remove name of the decorated function.
+
+      .. py:decorator:: setnewname(name)
+
+         Set name of the decorated function to *name*.
+
+   (as opposed to ``.. py:decorator:: removename(func)``.)
+
+   There is no ``py:deco`` role to link to a decorator that is marked up with
+   this directive; rather, use the :rst:role:`py:func` role.
+
+   .. rst:directive:option:: single-line-parameter-list
+      :type: no value
+
+      Ensures that the decorator's arguments will be emitted on a single logical
+      line, overriding :confval:`python_maximum_signature_line_length` and
+      :confval:`maximum_signature_line_length`.
+
+      .. versionadded:: 7.1
+
+   .. rst:directive:option:: single-line-type-parameter-list
+      :type: no value
+
+      Ensure that the decorator's type parameters are emitted on a single
+      logical line, overriding :confval:`python_maximum_signature_line_length`
+      and :confval:`maximum_signature_line_length`.
+
+      .. versionadded:: 7.2
+
+.. rst:directive:: .. py:decoratormethod:: name
+                   .. py:decoratormethod:: name(signature)
+                   .. py:decoratormethod:: name[type parameters](signature)
+
+   Same as :rst:dir:`py:decorator`, but for decorators that are methods.
+
+   Refer to a decorator method using the :rst:role:`py:meth` role.
+
+.. _signatures:
+
+Python Signatures
+~~~~~~~~~~~~~~~~~
+
+Signatures of functions, methods and class constructors can be given like they
+would be written in Python.
+
+Default values for optional arguments can be given (but if they contain commas,
+they will confuse the signature parser).  Python 3-style argument annotations
+can also be given as well as return type annotations::
+
+   .. py:function:: compile(source : string, filename, symbol='file') -> ast object
+
+For functions with optional parameters that don't have default values
+(typically functions implemented in C extension modules without keyword
+argument support), you can use brackets to specify the optional parts:
+
+.. py:function:: compile(source[, filename[, symbol]])
+   :no-index:
+
+It is customary to put the opening bracket before the comma.
+
+Python 3.12 introduced *type parameters*, which are type variables
+declared directly  within the class or function definition:
+
+.. code:: python
+
+   class AnimalList[AnimalT](list[AnimalT]):
+      ...
+
+   def add[T](a: T, b: T) -> T:
+      return a + b
+
+The corresponding reStructuredText documentation would be:
+
+.. code:: rst
+
+   .. py:class:: AnimalList[AnimalT]
+
+   .. py:function:: add[T](a: T, b: T) -> T
+
+See :pep:`695` and :pep:`696` for details and the full specification.
+
+.. _info-field-lists:
+
+Info field lists
+~~~~~~~~~~~~~~~~
+
+.. versionadded:: 0.4
+.. versionchanged:: 3.0
+
+   meta fields are added.
+
+Inside Python object description directives, reST field lists with these fields
+are recognized and formatted nicely:
+
+* ``param``, ``parameter``, ``arg``, ``argument``, ``key``, ``keyword``:
+  Description of a parameter.
+* ``type``: Type of a parameter.  Creates a link if possible.
+* ``raises``, ``raise``, ``except``, ``exception``: That (and when) a specific
+  exception is raised.
+* ``var``, ``ivar``, ``cvar``: Description of a variable.
+* ``vartype``: Type of a variable.  Creates a link if possible.
+* ``returns``, ``return``: Description of the return value.
+* ``rtype``: Return type.  Creates a link if possible.
+* ``meta``: Add metadata to description of the python object.  The metadata will
+  not be shown on output document.  For example, ``:meta private:`` indicates
+  the python object is private member.  It is used in
+  :py:mod:`sphinx.ext.autodoc` for filtering members.
+
+.. note::
+
+   In current release, all ``var``, ``ivar`` and ``cvar`` are represented as
+   "Variable".  There is no difference at all.
+
+The field names must consist of one of these keywords and an argument (except
+for ``returns`` and ``rtype``, which do not need an argument).  This is best
+explained by an example::
+
+   .. py:function:: send_message(sender, recipient, message_body, [priority=1])
+
+      Send a message to a recipient
+
+      :param str sender: The person sending the message
+      :param str recipient: The recipient of the message
+      :param str message_body: The body of the message
+      :param priority: The priority of the message, can be a number 1-5
+      :type priority: integer or None
+      :return: the message id
+      :rtype: int
+      :raises ValueError: if the message_body exceeds 160 characters
+      :raises TypeError: if the message_body is not a basestring
+
+This will render like this:
+
+.. py:function:: send_message(sender, recipient, message_body, [priority=1])
+   :no-index:
+
+   Send a message to a recipient
+
+   :param str sender: The person sending the message
+   :param str recipient: The recipient of the message
+   :param str message_body: The body of the message
+   :param priority: The priority of the message, can be a number 1-5
+   :type priority: int or None
+   :return: the message id
+   :rtype: int
+   :raises ValueError: if the message_body exceeds 160 characters
+   :raises TypeError: if the message_body is not a basestring
+
+It is also possible to combine parameter type and description, if the type is a
+single word, like this::
+
+   :param int priority: The priority of the message, can be a number 1-5
+
+.. versionadded:: 1.5
+
+Container types such as lists and dictionaries can be linked automatically
+using the following syntax::
+
+   :type priorities: list(int)
+   :type priorities: list[int]
+   :type mapping: dict(str, int)
+   :type mapping: dict[str, int]
+   :type point: tuple(float, float)
+   :type point: tuple[float, float]
+
+Multiple types in a type field will be linked automatically if separated by the
+word "or"::
+
+   :type an_arg: int or None
+   :vartype a_var: str or int
+   :rtype: float or str
+
+.. _python-roles:
+
+Cross-referencing Python objects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following roles refer to objects in modules and are possibly hyperlinked if
+a matching identifier is found:
+
+.. rst:role:: py:mod
+
+   Reference a module; a dotted name may be used.  This should also be used for
+   package names.
+
+.. rst:role:: py:func
+
+   Reference a Python function; dotted names may be used.  The role text needs
+   not include trailing parentheses to enhance readability; they will be added
+   automatically by Sphinx if the :confval:`add_function_parentheses` config
+   value is ``True`` (the default).
+
+.. rst:role:: py:data
+
+   Reference a module-level variable.
+
+.. rst:role:: py:const
+
+   Reference a "defined" constant.  This may be a Python variable that is not
+   intended to be changed.
+
+.. rst:role:: py:class
+
+   Reference a class; a dotted name may be used.
+
+.. rst:role:: py:meth
+
+   Reference a method of an object.  The role text can include the type name
+   and the method name; if it occurs within the description of a type, the type
+   name can be omitted.  A dotted name may be used.
+
+.. rst:role:: py:attr
+
+   Reference a data attribute of an object.
+
+   .. note:: The role is also able to refer to property.
+
+.. rst:role:: py:exc
+
+   Reference an exception.  A dotted name may be used.
+
+.. rst:role:: py:obj
+
+   Reference an object of unspecified type.  Useful e.g. as the
+   :confval:`default_role`.
+
+   .. versionadded:: 0.4
+
+The name enclosed in this markup can include a module name and/or a class name.
+For example, ``:py:func:`filter``` could refer to a function named ``filter``
+in the current module, or the built-in function of that name.  In contrast,
+``:py:func:`foo.filter``` clearly refers to the ``filter`` function in the
+``foo`` module.
+
+Normally, names in these roles are searched first without any further
+qualification, then with the current module name prepended, then with the
+current module and class name (if any) prepended.  If you prefix the name with
+a dot, this order is reversed.  For example, in the documentation of Python's
+:mod:`codecs` module, ``:py:func:`open``` always refers to the built-in
+function, while ``:py:func:`.open``` refers to :func:`codecs.open`.
+
+A similar heuristic is used to determine whether the name is an attribute of
+the currently documented class.
+
+Also, if the name is prefixed with a dot, and no exact match is found, the
+target is taken as a suffix and all object names with that suffix are searched.
+For example, ``:py:meth:`.TarFile.close``` references the
+``tarfile.TarFile.close()`` function, even if the current module is not
+``tarfile``.  Since this can get ambiguous, if there is more than one possible
+match, you will get a warning from Sphinx.
+
+Note that you can combine the ``~`` and ``.`` prefixes:
+``:py:meth:`~.TarFile.close``` will reference the ``tarfile.TarFile.close()``
+method, but the visible link caption will only be ``close()``.
+
+
+.. _c-domain:
+
+The C Domain
+------------
+
+The C domain (name **c**) is suited for documentation of C API.
+
+.. rst:directive:: .. c:member:: declaration
+                   .. c:var:: declaration
+
+   Describes a C struct member or variable. Example signature::
+
+      .. c:member:: PyObject *PyTypeObject.tp_bases
+
+   The difference between the two directives is only cosmetic.
+
+.. rst:directive:: .. c:function:: function prototype
+
+   Describes a C function. The signature should be given as in C, e.g.::
+
+      .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
+   Note that you don't have to backslash-escape asterisks in the signature, as
+   it is not parsed by the reST inliner.
+
+   In the description of a function you can use the following info fields
+   (see also :ref:`info-field-lists`).
+
+   * ``param``, ``parameter``, ``arg``, ``argument``,
+     Description of a parameter.
+   * ``type``: Type of a parameter,
+     written as if passed to the :rst:role:`c:expr` role.
+   * ``returns``, ``return``: Description of the return value.
+   * ``rtype``: Return type,
+     written as if passed to the :rst:role:`c:expr` role.
+   * ``retval``, ``retvals``: An alternative to ``returns`` for describing
+     the result of the function.
+
+   .. versionadded:: 4.3
+      The ``retval`` field type.
+
+   For example::
+
+      .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
+         :param type: description of the first parameter.
+         :param nitems: description of the second parameter.
+         :returns: a result.
+         :retval NULL: under some conditions.
+         :retval NULL: under some other conditions as well.
+
+   which renders as
+
+   .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
+      ..
+         ** for some editors (e.g., vim) to stop bold-highlighting the source
+
+      :param type: description of the first parameter.
+      :param nitems: description of the second parameter.
+      :returns: a result.
+      :retval NULL: under some conditions.
+      :retval NULL: under some other conditions as well.
+
+   .. rst:directive:option:: single-line-parameter-list
+      :type: no value
+
+      Ensures that the function's parameters will be emitted on a single logical
+      line, overriding :confval:`c_maximum_signature_line_length` and
+      :confval:`maximum_signature_line_length`.
+
+      .. versionadded:: 7.1
+
+
+.. rst:directive:: .. c:macro:: name
+                   .. c:macro:: name(arg list)
+
+   Describes a C macro, i.e., a C-language ``#define``, without the replacement
+   text.
+
+   In the description of a macro you can use the same info fields as for the
+   :rst:dir:`c:function` directive.
+
+   .. versionadded:: 3.0
+      The function style variant.
+
+   .. rst:directive:option:: single-line-parameter-list
+      :type: no value
+
+      Ensures that the macro's parameters will be emitted on a single logical
+      line, overriding :confval:`c_maximum_signature_line_length` and
+      :confval:`maximum_signature_line_length`.
+
+      .. versionadded:: 7.1
+
+.. rst:directive:: .. c:struct:: name
+
+   Describes a C struct.
+
+   .. versionadded:: 3.0
+
+.. rst:directive:: .. c:union:: name
+
+   Describes a C union.
+
+   .. versionadded:: 3.0
+
+.. rst:directive:: .. c:enum:: name
+
+   Describes a C enum.
+
+   .. versionadded:: 3.0
+
+.. rst:directive:: .. c:enumerator:: name
+
+   Describes a C enumerator.
+
+   .. versionadded:: 3.0
+
+.. rst:directive:: .. c:type:: typedef-like declaration
+                   .. c:type:: name
+
+   Describes a C type, either as a typedef, or the alias for an unspecified
+   type.
+
+.. _c-roles:
+
+Cross-referencing C constructs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following roles create cross-references to C-language constructs if they
+are defined in the documentation:
+
+.. rst:role:: c:member
+              c:data
+              c:var
+              c:func
+              c:macro
+              c:struct
+              c:union
+              c:enum
+              c:enumerator
+              c:type
+
+   Reference a C declaration, as defined above.
+   Note that :rst:role:`c:member`, :rst:role:`c:data`, and
+   :rst:role:`c:var` are equivalent.
+
+   .. versionadded:: 3.0
+      The var, struct, union, enum, and enumerator roles.
+
+
+Anonymous Entities
+~~~~~~~~~~~~~~~~~~
+
+C supports anonymous structs, enums, and unions.
+For the sake of documentation they must be given some name that starts with
+``@``, e.g., ``@42`` or ``@data``.
+These names can also be used in cross-references,
+though nested symbols will be found even when omitted.
+The ``@...`` name will always be rendered as **[anonymous]** (possibly as a
+link).
+
+Example::
+
+   .. c:struct:: Data
+
+      .. c:union:: @data
+
+         .. c:var:: int a
+
+         .. c:var:: double b
+
+   Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`.
+
+This will be rendered as:
+
+.. c:struct:: Data
+   :no-contents-entry:
+   :no-index-entry:
+
+   .. c:union:: @data
+      :no-contents-entry:
+      :no-index-entry:
+
+      .. c:var:: int a
+         :no-contents-entry:
+         :no-index-entry:
+
+      .. c:var:: double b
+         :no-contents-entry:
+         :no-index-entry:
+
+Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`.
+
+.. versionadded:: 3.0
+
+
+Aliasing Declarations
+~~~~~~~~~~~~~~~~~~~~~
+
+.. c:namespace-push:: @alias
+
+Sometimes it may be helpful list declarations elsewhere than their main
+documentation, e.g., when creating a synopsis of an interface.
+The following directive can be used for this purpose.
+
+.. rst:directive:: .. c:alias:: name
+
+   Insert one or more alias declarations. Each entity can be specified
+   as they can in the :rst:role:`c:any` role.
+
+   For example::
+
+       .. c:var:: int data
+       .. c:function:: int f(double k)
+
+       .. c:alias:: data
+                    f
+
+   becomes
+
+   .. c:var:: int data
+   .. c:function:: int f(double k)
+
+   .. c:alias:: data
+                f
+
+   .. versionadded:: 3.2
+
+
+   .. rubric:: Options
+
+   .. rst:directive:option:: maxdepth: int
+
+      Insert nested declarations as well, up to the total depth given.
+      Use 0 for infinite depth and 1 for just the mentioned declaration.
+      Defaults to 1.
+
+      .. versionadded:: 3.3
+
+   .. rst:directive:option:: noroot
+
+      Skip the mentioned declarations and only render nested declarations.
+      Requires ``maxdepth`` either 0 or at least 2.
+
+      .. versionadded:: 3.5
+
+
+.. c:namespace-pop::
+
+
+Inline Expressions and Types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rst:role:: c:expr
+              c:texpr
+
+   Insert a C expression or type either as inline code (``cpp:expr``)
+   or inline text (``cpp:texpr``). For example::
+
+      .. c:var:: int a = 42
+
+      .. c:function:: int f(int i)
+
+      An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`).
+
+      A type: :c:expr:`const Data*`
+      (or as text :c:texpr:`const Data*`).
+
+   will be rendered as follows:
+
+   .. c:var:: int a = 42
+      :no-contents-entry:
+      :no-index-entry:
+
+   .. c:function:: int f(int i)
+      :no-contents-entry:
+      :no-index-entry:
+
+   An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`).
+
+   A type: :c:expr:`const Data*`
+   (or as text :c:texpr:`const Data*`).
+
+   .. versionadded:: 3.0
+
+
+Namespacing
+~~~~~~~~~~~
+
+.. versionadded:: 3.1
+
+The C language it self does not support namespacing, but it can sometimes be
+useful to emulate it in documentation, e.g., to show alternate declarations.
+The feature may also be used to document members of structs/unions/enums
+separate from their parent declaration.
+
+The current scope can be changed using three namespace directives.  They manage
+a stack declarations where ``c:namespace`` resets the stack and changes a given
+scope.
+
+The ``c:namespace-push`` directive changes the scope to a given inner scope
+of the current one.
+
+The ``c:namespace-pop`` directive undoes the most recent
+``c:namespace-push`` directive.
+
+.. rst:directive:: .. c:namespace:: scope specification
+
+   Changes the current scope for the subsequent objects to the given scope, and
+   resets the namespace directive stack. Note that nested scopes can be
+   specified by separating with a dot, e.g.::
+
+      .. c:namespace:: Namespace1.Namespace2.SomeStruct.AnInnerStruct
+
+   All subsequent objects will be defined as if their name were declared with
+   the scope prepended. The subsequent cross-references will be searched for
+   starting in the current scope.
+
+   Using ``NULL`` or ``0`` as the scope will change to global scope.
+
+.. rst:directive:: .. c:namespace-push:: scope specification
+
+   Change the scope relatively to the current scope. For example, after::
+
+      .. c:namespace:: A.B
+
+      .. c:namespace-push:: C.D
+
+   the current scope will be ``A.B.C.D``.
+
+.. rst:directive:: .. c:namespace-pop::
+
+   Undo the previous ``c:namespace-push`` directive (*not* just pop a scope).
+   For example, after::
+
+      .. c:namespace:: A.B
+
+      .. c:namespace-push:: C.D
+
+      .. c:namespace-pop::
+
+   the current scope will be ``A.B`` (*not* ``A.B.C``).
+
+   If no previous ``c:namespace-push`` directive has been used, but only a
+   ``c:namespace`` directive, then the current scope will be reset to global
+   scope.  That is, ``.. c:namespace:: A.B`` is equivalent to::
+
+      .. c:namespace:: NULL
+
+      .. c:namespace-push:: A.B
+
+Configuration Variables
+~~~~~~~~~~~~~~~~~~~~~~~
+
+See :ref:`c-config`.
+
+
+.. _cpp-domain:
+
+The C++ Domain
+--------------
+
+The C++ domain (name **cpp**) supports documenting C++ projects.
+
+Directives for Declaring Entities
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following directives are available. All declarations can start with a
+visibility statement (``public``, ``private`` or ``protected``).
+
+.. rst:directive:: .. cpp:class:: class specifier
+                   .. cpp:struct:: class specifier
+
+   Describe a class/struct, possibly with specification of inheritance, e.g.,::
+
+      .. cpp:class:: MyClass : public MyBase, MyOtherBase
+
+   The difference between :rst:dir:`cpp:class` and :rst:dir:`cpp:struct` is
+   only cosmetic: the prefix rendered in the output, and the specifier shown
+   in the index.
+
+   The class can be directly declared inside a nested scope, e.g.,::
+
+      .. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase
+
+   A class template can be declared::
+
+      .. cpp:class:: template<typename T, std::size_t N> std::array
+
+   or with a line break::
+
+      .. cpp:class:: template<typename T, std::size_t N> \
+                     std::array
+
+   Full and partial template specialisations can be declared::
+
+      .. cpp:class:: template<> \
+                     std::array<bool, 256>
+
+      .. cpp:class:: template<typename T> \
+                     std::array<T, 42>
+
+   .. versionadded:: 2.0
+      The :rst:dir:`cpp:struct` directive.
+
+.. rst:directive:: .. cpp:function:: (member) function prototype
+
+   Describe a function or member function, e.g.,::
+
+      .. cpp:function:: bool myMethod(int arg1, std::string arg2)
+
+         A function with parameters and types.
+
+      .. cpp:function:: bool myMethod(int, double)
+
+         A function with unnamed parameters.
+
+      .. cpp:function:: const T &MyClass::operator[](std::size_t i) const
+
+         An overload for the indexing operator.
+
+      .. cpp:function:: operator bool() const
+
+         A casting operator.
+
+      .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept
+
+         A constexpr function.
+
+      .. cpp:function:: MyClass::MyClass(const MyClass&) = default
+
+         A copy constructor with default implementation.
+
+   Function templates can also be described::
+
+      .. cpp:function:: template<typename U> \
+                        void print(U &&u)
+
+   and function template specialisations::
+
+      .. cpp:function:: template<> \
+                        void print(int i)
+
+   .. rst:directive:option:: single-line-parameter-list
+      :type: no value
+
+      Ensures that the function's parameters will be emitted on a single logical
+      line, overriding :confval:`cpp_maximum_signature_line_length` and
+      :confval:`maximum_signature_line_length`.
+
+      .. versionadded:: 7.1
+
+.. rst:directive:: .. cpp:member:: (member) variable declaration
+                   .. cpp:var:: (member) variable declaration
+
+   Describe a variable or member variable, e.g.,::
+
+      .. cpp:member:: std::string MyClass::myMember
+
+      .. cpp:var:: std::string MyClass::myOtherMember[N][M]
+
+      .. cpp:member:: int a = 42
+
+   Variable templates can also be described::
+
+      .. cpp:member:: template<class T> \
+                      constexpr T pi = T(3.1415926535897932385)
+
+.. rst:directive:: .. cpp:type:: typedef declaration
+                   .. cpp:type:: name
+                   .. cpp:type:: type alias declaration
+
+   Describe a type as in a typedef declaration, a type alias declaration, or
+   simply the name of a type with unspecified type, e.g.,::
+
+      .. cpp:type:: std::vector<int> MyList
+
+         A typedef-like declaration of a type.
+
+      .. cpp:type:: MyContainer::const_iterator
+
+         Declaration of a type alias with unspecified type.
+
+      .. cpp:type:: MyType = std::unordered_map<int, std::string>
+
+         Declaration of a type alias.
+
+   A type alias can also be templated::
+
+      .. cpp:type:: template<typename T> \
+                    MyContainer = std::vector<T>
+
+   The example are rendered as follows.
+
+   .. cpp:type:: std::vector<int> MyList
+      :no-contents-entry:
+      :no-index-entry:
+
+      A typedef-like declaration of a type.
+
+   .. cpp:type:: MyContainer::const_iterator
+      :no-contents-entry:
+      :no-index-entry:
+
+      Declaration of a type alias with unspecified type.
+
+   .. cpp:type:: MyType = std::unordered_map<int, std::string>
+      :no-contents-entry:
+      :no-index-entry:
+
+      Declaration of a type alias.
+
+   .. cpp:type:: template<typename T> \
+                 MyContainer = std::vector<T>
+      :no-contents-entry:
+      :no-index-entry:
+
+.. rst:directive:: .. cpp:enum:: unscoped enum declaration
+                   .. cpp:enum-struct:: scoped enum declaration
+                   .. cpp:enum-class:: scoped enum declaration
+
+   Describe a (scoped) enum, possibly with the underlying type specified.  Any
+   enumerators declared inside an unscoped enum will be declared both in the
+   enum scope and in the parent scope.  Examples::
+
+      .. cpp:enum:: MyEnum
+
+         An unscoped enum.
+
+      .. cpp:enum:: MySpecificEnum : long
+
+         An unscoped enum with specified underlying type.
+
+      .. cpp:enum-class:: MyScopedEnum
+
+         A scoped enum.
+
+      .. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type
+
+         A scoped enum with non-default visibility, and with a specified
+         underlying type.
+
+.. rst:directive:: .. cpp:enumerator:: name
+                   .. cpp:enumerator:: name = constant
+
+   Describe an enumerator, optionally with its value defined, e.g.,::
+
+      .. cpp:enumerator:: MyEnum::myEnumerator
+
+      .. cpp:enumerator:: MyEnum::myOtherEnumerator = 42
+
+.. rst:directive:: .. cpp:union:: name
+
+   Describe a union.
+
+   .. versionadded:: 1.8
+
+.. rst:directive:: .. cpp:concept:: template-parameter-list name
+
+   .. warning:: The support for concepts is experimental. It is based on the
+      current draft standard and the Concepts Technical Specification.
+      The features may change as they evolve.
+
+   Describe a concept. It must have exactly 1 template parameter list. The name
+   may be a nested name. Example::
+
+      .. cpp:concept:: template<typename It> std::Iterator
+
+         Proxy to an element of a notional sequence that can be compared,
+         indirected, or incremented.
+
+         **Notation**
+
+         .. cpp:var:: It r
+
+            An lvalue.
+
+         **Valid Expressions**
+
+         - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.
+         - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when
+           :cpp:expr:`r` is incrementable.
+
+   This will render as follows:
+
+   .. cpp:concept:: template<typename It> std::Iterator
+
+      Proxy to an element of a notional sequence that can be compared,
+      indirected, or incremented.
+
+      **Notation**
+
+      .. cpp:var:: It r
+
+         An lvalue.
+
+      **Valid Expressions**
+
+      - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.
+      - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when :cpp:expr:`r`
+        is incrementable.
+
+   .. versionadded:: 1.5
+
+
+Options
+^^^^^^^
+
+Some directives support options:
+
+- ``:no-index-entry:`` and ``:no-contents-entry:``, see :ref:`basic-domain-markup`.
+- ``:tparam-line-spec:``, for templated declarations.
+  If specified, each template parameter will be rendered on a separate line.
+
+  .. versionadded:: 1.6
+
+Anonymous Entities
+~~~~~~~~~~~~~~~~~~
+
+C++ supports anonymous namespaces, classes, enums, and unions.
+For the sake of documentation they must be given some name that starts with
+``@``, e.g., ``@42`` or ``@data``.
+These names can also be used in cross-references and (type) expressions,
+though nested symbols will be found even when omitted.
+The ``@...`` name will always be rendered as **[anonymous]** (possibly as a
+link).
+
+Example::
+
+   .. cpp:class:: Data
+
+      .. cpp:union:: @data
+
+         .. cpp:var:: int a
+
+         .. cpp:var:: double b
+
+   Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.
+
+This will be rendered as:
+
+.. cpp:class:: Data
+   :no-contents-entry:
+   :no-index-entry:
+
+   .. cpp:union:: @data
+      :no-contents-entry:
+      :no-index-entry:
+
+      .. cpp:var:: int a
+         :no-contents-entry:
+         :no-index-entry:
+
+      .. cpp:var:: double b
+         :no-contents-entry:
+         :no-index-entry:
+
+Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.
+
+.. versionadded:: 1.8
+
+
+Aliasing Declarations
+~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes it may be helpful list declarations elsewhere than their main
+documentation, e.g., when creating a synopsis of a class interface.
+The following directive can be used for this purpose.
+
+.. rst:directive:: .. cpp:alias:: name or function signature
+
+   Insert one or more alias declarations. Each entity can be specified
+   as they can in the :rst:role:`cpp:any` role.
+   If the name of a function is given (as opposed to the complete signature),
+   then all overloads of the function will be listed.
+
+   For example::
+
+       .. cpp:alias:: Data::a
+                      overload_example::C::f
+
+   becomes
+
+   .. cpp:alias:: Data::a
+                  overload_example::C::f
+
+   whereas::
+
+       .. cpp:alias:: void overload_example::C::f(double d) const
+                      void overload_example::C::f(double d)
+
+   becomes
+
+   .. cpp:alias:: void overload_example::C::f(double d) const
+                  void overload_example::C::f(double d)
+
+   .. versionadded:: 2.0
+
+
+   .. rubric:: Options
+
+   .. rst:directive:option:: maxdepth: int
+
+      Insert nested declarations as well, up to the total depth given.
+      Use 0 for infinite depth and 1 for just the mentioned declaration.
+      Defaults to 1.
+
+      .. versionadded:: 3.5
+
+   .. rst:directive:option:: noroot
+
+      Skip the mentioned declarations and only render nested declarations.
+      Requires ``maxdepth`` either 0 or at least 2.
+
+      .. versionadded:: 3.5
+
+
+Constrained Templates
+~~~~~~~~~~~~~~~~~~~~~
+
+.. warning:: The support for concepts is experimental. It is based on the
+  current draft standard and the Concepts Technical Specification.
+  The features may change as they evolve.
+
+.. note:: Sphinx does not currently support ``requires`` clauses.
+
+Placeholders
+^^^^^^^^^^^^
+
+Declarations may use the name of a concept to introduce constrained template
+parameters, or the keyword ``auto`` to introduce unconstrained template
+parameters::
+
+   .. cpp:function:: void f(auto &&arg)
+
+      A function template with a single unconstrained template parameter.
+
+   .. cpp:function:: void f(std::Iterator it)
+
+      A function template with a single template parameter, constrained by the
+      Iterator concept.
+
+Template Introductions
+^^^^^^^^^^^^^^^^^^^^^^
+
+Simple constrained function or class templates can be declared with a `template
+introduction` instead of a template parameter list::
+
+   .. cpp:function:: std::Iterator{It} void advance(It &it)
+
+       A function template with a template parameter constrained to be an
+       Iterator.
+
+   .. cpp:class:: std::LessThanComparable{T} MySortedContainer
+
+       A class template with a template parameter constrained to be
+       LessThanComparable.
+
+They are rendered as follows.
+
+.. cpp:function:: std::Iterator{It} void advance(It &it)
+   :no-contents-entry:
+   :no-index-entry:
+
+   A function template with a template parameter constrained to be an Iterator.
+
+.. cpp:class:: std::LessThanComparable{T} MySortedContainer
+   :no-contents-entry:
+   :no-index-entry:
+
+   A class template with a template parameter constrained to be
+   LessThanComparable.
+
+Note however that no checking is performed with respect to parameter
+compatibility. E.g., ``Iterator{A, B, C}`` will be accepted as an introduction
+even though it would not be valid C++.
+
+Inline Expressions and Types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rst:role:: cpp:expr
+              cpp:texpr
+
+   Insert a C++ expression or type either as inline code (``cpp:expr``)
+   or inline text (``cpp:texpr``). For example::
+
+      .. cpp:var:: int a = 42
+
+      .. cpp:function:: int f(int i)
+
+      An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`).
+
+      A type: :cpp:expr:`const MySortedContainer<int>&`
+      (or as text :cpp:texpr:`const MySortedContainer<int>&`).
+
+   will be rendered as follows:
+
+   .. cpp:var:: int a = 42
+      :no-contents-entry:
+      :no-index-entry:
+
+   .. cpp:function:: int f(int i)
+      :no-contents-entry:
+      :no-index-entry:
+
+   An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`).
+
+   A type: :cpp:expr:`const MySortedContainer<int>&`
+   (or as text :cpp:texpr:`const MySortedContainer<int>&`).
+
+   .. versionadded:: 1.7
+      The :rst:role:`cpp:expr` role.
+
+   .. versionadded:: 1.8
+      The :rst:role:`cpp:texpr` role.
+
+Namespacing
+~~~~~~~~~~~
+
+Declarations in the C++ domain are as default placed in global scope.  The
+current scope can be changed using three namespace directives.  They manage a
+stack declarations where ``cpp:namespace`` resets the stack and changes a given
+scope.
+
+The ``cpp:namespace-push`` directive changes the scope to a given inner scope
+of the current one.
+
+The ``cpp:namespace-pop`` directive undoes the most recent
+``cpp:namespace-push`` directive.
+
+.. rst:directive:: .. cpp:namespace:: scope specification
+
+   Changes the current scope for the subsequent objects to the given scope, and
+   resets the namespace directive stack.  Note that the namespace does not need
+   to correspond to C++ namespaces, but can end in names of classes, e.g.,::
+
+      .. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass
+
+   All subsequent objects will be defined as if their name were declared with
+   the scope prepended. The subsequent cross-references will be searched for
+   starting in the current scope.
+
+   Using ``NULL``, ``0``, or ``nullptr`` as the scope will change to global
+   scope.
+
+   A namespace declaration can also be templated, e.g.,::
+
+      .. cpp:class:: template<typename T> \
+                     std::vector
+
+      .. cpp:namespace:: template<typename T> std::vector
+
+      .. cpp:function:: std::size_t size() const
+
+   declares ``size`` as a member function of the class template
+   ``std::vector``.  Equivalently this could have been declared using::
+
+      .. cpp:class:: template<typename T> \
+                     std::vector
+
+         .. cpp:function:: std::size_t size() const
+
+   or::
+
+      .. cpp:class:: template<typename T> \
+                     std::vector
+
+.. rst:directive:: .. cpp:namespace-push:: scope specification
+
+   Change the scope relatively to the current scope. For example, after::
+
+      .. cpp:namespace:: A::B
+
+      .. cpp:namespace-push:: C::D
+
+   the current scope will be ``A::B::C::D``.
+
+   .. versionadded:: 1.4
+
+.. rst:directive:: .. cpp:namespace-pop::
+
+   Undo the previous ``cpp:namespace-push`` directive (*not* just pop a scope).
+   For example, after::
+
+      .. cpp:namespace:: A::B
+
+      .. cpp:namespace-push:: C::D
+
+      .. cpp:namespace-pop::
+
+   the current scope will be ``A::B`` (*not* ``A::B::C``).
+
+   If no previous ``cpp:namespace-push`` directive has been used, but only a
+   ``cpp:namespace`` directive, then the current scope will be reset to global
+   scope.  That is, ``.. cpp:namespace:: A::B`` is equivalent to::
+
+      .. cpp:namespace:: nullptr
+
+      .. cpp:namespace-push:: A::B
+
+   .. versionadded:: 1.4
+
+Info field lists
+~~~~~~~~~~~~~~~~~
+
+All the C++ directives for declaring entities support the following
+info fields (see also :ref:`info-field-lists`):
+
+* ``tparam``: Description of a template parameter.
+
+The :rst:dir:`cpp:function` directive additionally supports the
+following fields:
+
+* ``param``, ``parameter``, ``arg``, ``argument``: Description of a parameter.
+* ``returns``, ``return``: Description of a return value.
+* ``retval``, ``retvals``: An alternative to ``returns`` for describing
+  the result of the function.
+* `throws`, `throw`, `exception`: Description of a possibly thrown exception.
+
+.. versionadded:: 4.3
+   The ``retval`` field type.
+
+.. _cpp-roles:
+
+Cross-referencing
+~~~~~~~~~~~~~~~~~
+
+These roles link to the given declaration types:
+
+.. rst:role:: cpp:any
+              cpp:class
+              cpp:struct
+              cpp:func
+              cpp:member
+              cpp:var
+              cpp:type
+              cpp:concept
+              cpp:enum
+              cpp:enumerator
+
+   Reference a C++ declaration by name (see below for details).  The name must
+   be properly qualified relative to the position of the link.
+
+   .. versionadded:: 2.0
+      The :rst:role:`cpp:struct` role as alias for the :rst:role:`cpp:class`
+      role.
+
+.. admonition:: Note on References with Templates Parameters/Arguments
+
+   These roles follow the Sphinx :ref:`xref-syntax` rules. This means care must
+   be taken when referencing a (partial) template specialization, e.g. if the
+   link looks like this: ``:cpp:class:`MyClass<int>```.
+   This is interpreted as a link to ``int`` with a title of ``MyClass``.
+   In this case, escape the opening angle bracket with a backslash,
+   like this: ``:cpp:class:`MyClass\<int>```.
+
+   When a custom title is not needed it may be useful to use the roles for
+   inline expressions, :rst:role:`cpp:expr` and :rst:role:`cpp:texpr`, where
+   angle brackets do not need escaping.
+
+Declarations without template parameters and template arguments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For linking to non-templated declarations the name must be a nested name, e.g.,
+``f`` or ``MyClass::f``.
+
+
+Overloaded (member) functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When a (member) function is referenced using just its name, the reference
+will point to an arbitrary matching overload.
+The :rst:role:`cpp:any` and :rst:role:`cpp:func` roles use an alternative
+format, which simply is a complete function declaration.
+This will resolve to the exact matching overload.
+As example, consider the following class declaration:
+
+.. cpp:namespace-push:: overload_example
+.. cpp:class:: C
+
+   .. cpp:function:: void f(double d) const
+   .. cpp:function:: void f(double d)
+   .. cpp:function:: void f(int i)
+   .. cpp:function:: void f()
+
+References using the :rst:role:`cpp:func` role:
+
+- Arbitrary overload: ``C::f``, :cpp:func:`C::f`
+- Also arbitrary overload: ``C::f()``, :cpp:func:`C::f()`
+- Specific overload: ``void C::f()``, :cpp:func:`void C::f()`
+- Specific overload: ``void C::f(int)``, :cpp:func:`void C::f(int)`
+- Specific overload: ``void C::f(double)``, :cpp:func:`void C::f(double)`
+- Specific overload: ``void C::f(double) const``,
+  :cpp:func:`void C::f(double) const`
+
+Note that the :confval:`add_function_parentheses` configuration variable
+does not influence specific overload references.
+
+.. cpp:namespace-pop::
+
+
+Templated declarations
+^^^^^^^^^^^^^^^^^^^^^^
+
+Assume the following declarations.
+
+.. cpp:class:: Wrapper
+
+   .. cpp:class:: template<typename TOuter> \
+                  Outer
+
+      .. cpp:class:: template<typename TInner> \
+                     Inner
+
+In general the reference must include the template parameter declarations,
+and template arguments for the prefix of qualified names. For example:
+
+- ``template\<typename TOuter> Wrapper::Outer``
+  (:cpp:class:`template\<typename TOuter> Wrapper::Outer`)
+- ``template\<typename TOuter> template\<typename TInner> Wrapper::Outer<TOuter>::Inner``
+  (:cpp:class:`template\<typename TOuter> template\<typename TInner> Wrapper::Outer<TOuter>::Inner`)
+
+Currently the lookup only succeed if the template parameter identifiers are
+equal strings.  That is, ``template\<typename UOuter> Wrapper::Outer`` will not
+work.
+
+As a shorthand notation, if a template parameter list is omitted,
+then the lookup will assume either a primary template or a non-template,
+but not a partial template specialisation.
+This means the following references work as well:
+
+- ``Wrapper::Outer``
+  (:cpp:class:`Wrapper::Outer`)
+- ``Wrapper::Outer::Inner``
+  (:cpp:class:`Wrapper::Outer::Inner`)
+- ``template\<typename TInner> Wrapper::Outer::Inner``
+  (:cpp:class:`template\<typename TInner> Wrapper::Outer::Inner`)
+
+(Full) Template Specialisations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Assume the following declarations.
+
+.. cpp:class:: template<typename TOuter> \
+               Outer
+
+  .. cpp:class:: template<typename TInner> \
+                 Inner
+
+.. cpp:class:: template<> \
+               Outer<int>
+
+  .. cpp:class:: template<typename TInner> \
+                 Inner
+
+  .. cpp:class:: template<> \
+                 Inner<bool>
+
+In general the reference must include a template parameter list for each
+template argument list.  The full specialisation above can therefore be
+referenced with ``template\<> Outer\<int>`` (:cpp:class:`template\<>
+Outer\<int>`) and ``template\<> template\<> Outer\<int>::Inner\<bool>``
+(:cpp:class:`template\<> template\<> Outer\<int>::Inner\<bool>`).  As a
+shorthand the empty template parameter list can be omitted, e.g.,
+``Outer\<int>`` (:cpp:class:`Outer\<int>`) and ``Outer\<int>::Inner\<bool>``
+(:cpp:class:`Outer\<int>::Inner\<bool>`).
+
+Partial Template Specialisations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Assume the following declaration.
+
+.. cpp:class:: template<typename T> \
+               Outer<T*>
+
+References to partial specialisations must always include the template
+parameter lists, e.g., ``template\<typename T> Outer\<T*>``
+(:cpp:class:`template\<typename T> Outer\<T*>`).  Currently the lookup only
+succeed if the template parameter identifiers are equal strings.
+
+Configuration Variables
+~~~~~~~~~~~~~~~~~~~~~~~
+
+See :ref:`cpp-config`.
+
+.. _domains-std:
+
+The Standard Domain
+-------------------
+
+The so-called "standard" domain collects all markup that doesn't warrant a
+domain of its own.  Its directives and roles are not prefixed with a domain
+name.
+
+The standard domain is also where custom object descriptions, added using the
+:func:`~sphinx.application.Sphinx.add_object_type` API, are placed.
+
+There is a set of directives allowing documenting command-line programs:
+
+.. rst:directive:: .. option:: name args, name args, ...
+
+   Describes a command line argument or switch.  Option argument names should
+   be enclosed in angle brackets.  Examples::
+
+      .. option:: dest_dir
+
+         Destination directory.
+
+      .. option:: -m <module>, --module <module>
+
+         Run a module as a script.
+
+   The directive will create cross-reference targets for the given options,
+   referenceable by :rst:role:`option` (in the example case, you'd use something
+   like ``:option:`dest_dir```, ``:option:`-m```, or ``:option:`--module```).
+
+   .. versionchanged:: 5.3
+
+      One can cross-reference including an option value: ``:option:`--module=foobar```,
+      ,``:option:`--module[=foobar]``` or ``:option:`--module foobar```.
+
+   Use :confval:`option_emphasise_placeholders` for parsing of
+   "variable part" of a literal text (similarly to the :rst:role:`samp` role).
+
+   ``cmdoption`` directive is a deprecated alias for the ``option`` directive.
+
+.. rst:directive:: .. envvar:: name
+
+   Describes an environment variable that the documented code or program uses
+   or defines.  Referenceable by :rst:role:`envvar`.
+
+.. rst:directive:: .. program:: name
+
+   Like :rst:dir:`py:currentmodule`, this directive produces no output.
+   Instead, it serves to notify Sphinx that all following :rst:dir:`option`
+   directives document options for the program called *name*.
+
+   If you use :rst:dir:`program`, you have to qualify the references in your
+   :rst:role:`option` roles by the program name, so if you have the following
+   situation ::
+
+      .. program:: rm
+
+      .. option:: -r
+
+         Work recursively.
+
+      .. program:: svn
+
+      .. option:: -r <revision>
+
+         Specify the revision to work upon.
+
+   then ``:option:`rm -r``` would refer to the first option, while
+   ``:option:`svn -r``` would refer to the second one.
+
+   If ``None`` is passed to the argument, the directive will reset the
+   current program name.
+
+   The program name may contain spaces (in case you want to document
+   subcommands like ``svn add`` and ``svn commit`` separately).
+
+   .. versionadded:: 0.5
+
+There is also a very generic object description directive, which is not tied to
+any domain:
+
+.. rst:directive:: .. describe:: text
+               .. object:: text
+
+   This directive produces the same formatting as the specific ones provided by
+   domains, but does not create index entries or cross-referencing targets.
+   Example::
+
+      .. describe:: PAPER
+
+         You can set this variable to select a paper size.
+
+
+The JavaScript Domain
+---------------------
+
+The JavaScript domain (name **js**) provides the following directives:
+
+.. rst:directive:: .. js:module:: name
+
+   This directive sets the module name for object declarations that follow
+   after. The module name is used in the global module index and in cross
+   references. This directive does not create an object heading like
+   :rst:dir:`py:class` would, for example.
+
+   By default, this directive will create a linkable entity and will cause an
+   entry in the global module index, unless the ``no-index`` option is
+   specified.  If this option is specified, the directive will only update the
+   current module name.
+
+   .. versionadded:: 1.6
+   .. versionchanged:: 5.2
+
+      Module directives support body content.
+
+.. rst:directive:: .. js:function:: name(signature)
+
+   Describes a JavaScript function or method.  If you want to describe
+   arguments as optional use square brackets as :ref:`documented <signatures>`
+   for Python signatures.
+
+   You can use fields to give more details about arguments and their expected
+   types, errors which may be thrown by the function, and the value being
+   returned::
+
+      .. js:function:: $.getJSON(href, callback[, errback])
+
+         :param string href: An URI to the location of the resource.
+         :param callback: Gets called with the object.
+         :param errback:
+             Gets called in case the request fails. And a lot of other
+             text so we need multiple lines.
+         :throws SomeError: For whatever reason in that case.
+         :returns: Something.
+
+   This is rendered as:
+
+   .. js:function:: $.getJSON(href, callback[, errback])
+      :no-index:
+
+      :param string href: An URI to the location of the resource.
+      :param callback: Gets called with the object.
+      :param errback:
+          Gets called in case the request fails. And a lot of other
+          text so we need multiple lines.
+      :throws SomeError: For whatever reason in that case.
+      :returns: Something.
+
+   .. rst:directive:option:: single-line-parameter-list
+      :type: no value
+
+      Ensures that the function's parameters will be emitted on a single logical
+      line, overriding :confval:`javascript_maximum_signature_line_length` and
+      :confval:`maximum_signature_line_length`.
+
+      .. versionadded:: 7.1
+
+.. rst:directive:: .. js:method:: name(signature)
+
+   This directive is an alias for :rst:dir:`js:function`, however it describes
+   a function that is implemented as a method on a class object.
+
+   .. versionadded:: 1.6
+
+   .. rst:directive:option:: single-line-parameter-list
+      :type: no value
+
+      Ensures that the function's parameters will be emitted on a single logical
+      line, overriding :confval:`javascript_maximum_signature_line_length` and
+      :confval:`maximum_signature_line_length`.
+
+      .. versionadded:: 7.1
+
+.. rst:directive:: .. js:class:: name
+
+   Describes a constructor that creates an object.  This is basically like a
+   function but will show up with a `class` prefix::
+
+      .. js:class:: MyAnimal(name[, age])
+
+         :param string name: The name of the animal
+         :param number age: an optional age for the animal
+
+   This is rendered as:
+
+   .. js:class:: MyAnimal(name[, age])
+      :no-index:
+
+      :param string name: The name of the animal
+      :param number age: an optional age for the animal
+
+   .. rst:directive:option:: single-line-parameter-list
+      :type: no value
+
+      Ensures that the function's parameters will be emitted on a single logical
+      line, overriding :confval:`javascript_maximum_signature_line_length` and
+      :confval:`maximum_signature_line_length`.
+
+      .. versionadded:: 7.1
+
+.. rst:directive:: .. js:data:: name
+
+   Describes a global variable or constant.
+
+.. rst:directive:: .. js:attribute:: object.name
+
+   Describes the attribute *name* of *object*.
+
+.. _js-roles:
+
+These roles are provided to refer to the described objects:
+
+.. rst:role:: js:mod
+          js:func
+          js:meth
+          js:class
+          js:data
+          js:attr
+
+
+The reStructuredText domain
+---------------------------
+
+The reStructuredText domain (name **rst**) provides the following directives:
+
+.. rst:directive:: .. rst:directive:: name
+
+   Describes a reST directive.  The *name* can be a single directive name or
+   actual directive syntax (`..` prefix and `::` suffix) with arguments that
+   will be rendered differently.  For example::
+
+      .. rst:directive:: foo
+
+         Foo description.
+
+      .. rst:directive:: .. bar:: baz
+
+         Bar description.
+
+   will be rendered as:
+
+   .. rst:directive:: foo
+      :no-index:
+
+      Foo description.
+
+   .. rst:directive:: .. bar:: baz
+      :no-index:
+
+      Bar description.
+
+.. rst:directive:: .. rst:directive:option:: name
+
+   Describes an option for reST directive.  The *name* can be a single option
+   name or option name with arguments which separated with colon (``:``).
+   For example::
+
+       .. rst:directive:: toctree
+
+          .. rst:directive:option:: caption: caption of ToC
+
+          .. rst:directive:option:: glob
+
+   will be rendered as:
+
+   .. rst:directive:: toctree
+      :no-index:
+
+      .. rst:directive:option:: caption: caption of ToC
+         :no-index:
+
+      .. rst:directive:option:: glob
+         :no-index:
+
+   .. rubric:: options
+
+   .. rst:directive:option:: type: description of argument
+      :type: text
+
+      Describe the type of option value.
+
+      For example::
+
+         .. rst:directive:: toctree
+
+            .. rst:directive:option:: maxdepth
+               :type: integer or no value
+
+      .. versionadded:: 2.1
+
+.. rst:directive:: .. rst:role:: name
+
+   Describes a reST role.  For example::
+
+      .. rst:role:: foo
+
+         Foo description.
+
+   will be rendered as:
+
+   .. rst:role:: foo
+      :no-index:
+
+      Foo description.
+
+.. _rst-roles:
+
+These roles are provided to refer to the described objects:
+
+.. rst:role:: rst:dir
+              rst:role
+
+.. _math-domain:
+
+The Math Domain
+---------------
+
+The math domain (name **math**) provides the following roles:
+
+.. rst:role:: math:numref
+
+   Role for cross-referencing equations defined by :rst:dir:`math` directive
+   via their label.  Example::
+
+      .. math:: e^{i\pi} + 1 = 0
+         :label: euler
+
+      Euler's identity, equation :math:numref:`euler`, was elected one of the
+      most beautiful mathematical formulas.
+
+   .. versionadded:: 1.8
+
+More domains
+------------
+
+The sphinx-contrib_ repository contains more domains available as extensions;
+currently Ada_, CoffeeScript_, Erlang_, HTTP_, Lasso_, MATLAB_, PHP_, and Ruby_
+domains. Also available are domains for `Chapel`_, `Common Lisp`_, dqn_, Go_,
+Jinja_, Operation_, and Scala_.
+
+.. _sphinx-contrib: https://github.com/sphinx-contrib
+
+.. _Ada: https://pypi.org/project/sphinxcontrib-adadomain/
+.. _Chapel: https://pypi.org/project/sphinxcontrib-chapeldomain/
+.. _CoffeeScript: https://pypi.org/project/sphinxcontrib-coffee/
+.. _Common Lisp: https://pypi.org/project/sphinxcontrib-cldomain/
+.. _dqn: https://pypi.org/project/sphinxcontrib-dqndomain/
+.. _Erlang: https://pypi.org/project/sphinxcontrib-erlangdomain/
+.. _Go: https://pypi.org/project/sphinxcontrib-golangdomain/
+.. _HTTP: https://pypi.org/project/sphinxcontrib-httpdomain/
+.. _Jinja: https://pypi.org/project/sphinxcontrib-jinjadomain/
+.. _Lasso: https://pypi.org/project/sphinxcontrib-lassodomain/
+.. _MATLAB: https://pypi.org/project/sphinxcontrib-matlabdomain/
+.. _Operation: https://pypi.org/project/sphinxcontrib-operationdomain/
+.. _PHP: https://pypi.org/project/sphinxcontrib-phpdomain/
+.. _Ruby: https://github.com/sphinx-contrib/rubydomain
+.. _Scala: https://pypi.org/project/sphinxcontrib-scaladomain/
diff --git a/doc/usage/restructuredtext/field-lists.rst b/doc/usage/restructuredtext/field-lists.rst
new file mode 100644
index 0000000..5fc897d
--- /dev/null
+++ b/doc/usage/restructuredtext/field-lists.rst
@@ -0,0 +1,78 @@
+.. highlight:: rst
+
+===========
+Field Lists
+===========
+
+:ref:`As previously discussed <rst-field-lists>`, field lists are sequences of
+fields marked up like this::
+
+    :fieldname: Field content
+
+Sphinx extends standard docutils behavior for field lists and adds some extra
+functionality that is covered in this section.
+
+.. note::
+
+    The values of field lists will be parsed as
+    strings. You cannot use Python collections such as lists or dictionaries.
+
+
+.. _metadata:
+
+File-wide metadata
+------------------
+
+A field list near the top of a file is normally parsed by docutils as the
+*docinfo* and shown on the page.  However, in Sphinx, a field list preceding
+any other markup is moved from the *docinfo* to the Sphinx environment as
+document metadata, and is not displayed in the output.
+
+.. note::
+
+   A field list appearing after the document title *will* be part of the
+   *docinfo* as normal and will be displayed in the output.
+
+
+Special metadata fields
+-----------------------
+
+Sphinx provides custom behavior for bibliographic fields compared to docutils.
+
+At the moment, these metadata fields are recognized:
+
+``tocdepth``
+   The maximum depth for a table of contents of this file. ::
+
+       :tocdepth: 2
+
+   .. note::
+
+      This metadata effects to the depth of local toctree.  But it does not
+      effect to the depth of *global* toctree.  So this would not be change
+      the sidebar of some themes which uses global one.
+
+   .. versionadded:: 0.4
+
+``nocomments``
+   If set, the web application won't display a comment form for a page
+   generated from this source file. ::
+
+       :nocomments:
+
+``orphan``
+   If set, warnings about this file not being included in any toctree will be
+   suppressed. ::
+
+       :orphan:
+
+   .. versionadded:: 1.0
+
+``nosearch``
+   If set, full text search for this file is disabled. ::
+
+       :nosearch:
+
+   .. note:: object search is still available even if `nosearch` option is set.
+
+   .. versionadded:: 3.0
diff --git a/doc/usage/restructuredtext/index.rst b/doc/usage/restructuredtext/index.rst
new file mode 100644
index 0000000..87b6ed6
--- /dev/null
+++ b/doc/usage/restructuredtext/index.rst
@@ -0,0 +1,24 @@
+.. _rst-index:
+
+================
+reStructuredText
+================
+
+reStructuredText (reST) is the default plaintext markup language used by both
+Docutils and Sphinx. Docutils provides the basic reStructuredText syntax, while
+Sphinx extends this to support additional functionality.
+
+The below guides go through the most important aspects of reST. For the
+authoritative reStructuredText reference, refer to the `docutils
+documentation`__.
+
+__ https://docutils.sourceforge.io/rst.html
+
+.. toctree::
+   :maxdepth: 2
+
+   basics
+   roles
+   directives
+   field-lists
+   domains
diff --git a/doc/usage/restructuredtext/roles.rst b/doc/usage/restructuredtext/roles.rst
new file mode 100644
index 0000000..e468de9
--- /dev/null
+++ b/doc/usage/restructuredtext/roles.rst
@@ -0,0 +1,536 @@
+.. highlight:: rst
+
+=====
+Roles
+=====
+
+Sphinx uses interpreted text roles to insert semantic markup into documents.
+They are written as ``:rolename:`content```.
+
+.. note::
+
+   The default role (```content```) has no special meaning by default.  You are
+   free to use it for anything you like, e.g. variable names; use the
+   :confval:`default_role` config value to set it to a known role -- the
+   :rst:role:`any` role to find anything or the :rst:role:`py:obj` role to find
+   Python objects are very useful for this.
+
+See :doc:`/usage/restructuredtext/domains` for roles added by domains.
+
+
+.. _xref-syntax:
+
+Cross-referencing syntax
+------------------------
+
+Cross-references are generated by many semantic interpreted text roles.
+Basically, you only need to write ``:role:`target```, and a link will be
+created to the item named *target* of the type indicated by *role*.  The link's
+text will be the same as *target*.
+
+There are some additional facilities, however, that make cross-referencing
+roles more versatile:
+
+* You may supply an explicit title and reference target, like in reST direct
+  hyperlinks: ``:role:`title <target>``` will refer to *target*, but the link
+  text will be *title*.
+
+* If you prefix the content with ``!``, no reference/hyperlink will be created.
+
+* If you prefix the content with ``~``, the link text will only be the last
+  component of the target.  For example, ``:py:meth:`~Queue.Queue.get``` will
+  refer to ``Queue.Queue.get`` but only display ``get`` as the link text.  This
+  does not work with all cross-reference roles, but is domain specific.
+
+  In HTML output, the link's ``title`` attribute (that is e.g. shown as a
+  tool-tip on mouse-hover) will always be the full target name.
+
+
+.. _any-role:
+
+Cross-referencing anything
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. rst:role:: any
+
+   .. versionadded:: 1.3
+
+   This convenience role tries to do its best to find a valid target for its
+   reference text.
+
+   * First, it tries standard cross-reference targets that would be referenced
+     by :rst:role:`doc`, :rst:role:`ref` or :rst:role:`option`.
+
+     Custom objects added to the standard domain by extensions (see
+     :meth:`.Sphinx.add_object_type`) are also searched.
+
+   * Then, it looks for objects (targets) in all loaded domains.  It is up to
+     the domains how specific a match must be.  For example, in the Python
+     domain a reference of ``:any:`Builder``` would match the
+     ``sphinx.builders.Builder`` class.
+
+   If none or multiple targets are found, a warning will be emitted.  In the
+   case of multiple targets, you can change "any" to a specific role.
+
+   This role is a good candidate for setting :confval:`default_role`.  If you
+   do, you can write cross-references without a lot of markup overhead.  For
+   example, in this Python function documentation::
+
+      .. function:: install()
+
+         This function installs a `handler` for every signal known by the
+         `signal` module.  See the section `about-signals` for more information.
+
+   there could be references to a glossary term (usually ``:term:`handler```), a
+   Python module (usually ``:py:mod:`signal``` or ``:mod:`signal```) and a
+   section (usually ``:ref:`about-signals```).
+
+   The :rst:role:`any` role also works together with the
+   :mod:`~sphinx.ext.intersphinx` extension: when no local cross-reference is
+   found, all object types of intersphinx inventories are also searched.
+
+Cross-referencing objects
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These roles are described with their respective domains:
+
+* :ref:`Python <python-roles>`
+* :ref:`C <c-roles>`
+* :ref:`C++ <cpp-roles>`
+* :ref:`JavaScript <js-roles>`
+* :ref:`ReST <rst-roles>`
+
+
+.. _ref-role:
+
+Cross-referencing arbitrary locations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. rst:role:: ref
+
+   To support cross-referencing to arbitrary locations in any document, the
+   standard reST labels are used.  For this to work label names must be unique
+   throughout the entire documentation.  There are two ways in which you can
+   refer to labels:
+
+   * If you place a label directly before a section title, you can reference to
+     it with ``:ref:`label-name```.  For example::
+
+        .. _my-reference-label:
+
+        Section to cross-reference
+        --------------------------
+
+        This is the text of the section.
+
+        It refers to the section itself, see :ref:`my-reference-label`.
+
+     The ``:ref:`` role would then generate a link to the section, with the
+     link title being "Section to cross-reference".  This works just as well
+     when section and reference are in different source files.
+
+     Automatic labels also work with figures. For example::
+
+        .. _my-figure:
+
+        .. figure:: whatever
+
+           Figure caption
+
+     In this case, a  reference ``:ref:`my-figure``` would insert a reference
+     to the figure with link text "Figure caption".
+
+     The same works for tables that are given an explicit caption using the
+     :dudir:`table` directive.
+
+   * Labels that aren't placed before a section title can still be referenced,
+     but you must give the link an explicit title, using this syntax:
+     ``:ref:`Link title <label-name>```.
+
+   .. note::
+
+      Reference labels must start with an underscore. When referencing a label,
+      the underscore must be omitted (see examples above).
+
+   Using :rst:role:`ref` is advised over standard reStructuredText links to
+   sections (like ```Section title`_``) because it works across files, when
+   section headings are changed, will raise warnings if incorrect, and works
+   for all builders that support cross-references.
+
+
+Cross-referencing documents
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 0.6
+
+There is also a way to directly link to documents:
+
+.. rst:role:: doc
+
+   Link to the specified document; the document name can be specified in
+   absolute or relative fashion.  For example, if the reference
+   ``:doc:`parrot``` occurs in the document ``sketches/index``, then the link
+   refers to ``sketches/parrot``.  If the reference is ``:doc:`/people``` or
+   ``:doc:`../people```, the link refers to ``people``.
+
+   If no explicit link text is given (like usual: ``:doc:`Monty Python members
+   </people>```), the link caption will be the title of the given document.
+
+
+Referencing downloadable files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 0.6
+
+.. rst:role:: download
+
+   This role lets you link to files within your source tree that are not reST
+   documents that can be viewed, but files that can be downloaded.
+
+   When you use this role, the referenced file is automatically marked for
+   inclusion in the output when building (obviously, for HTML output only).
+   All downloadable files are put into a ``_downloads/<unique hash>/``
+   subdirectory of the output directory; duplicate filenames are handled.
+
+   An example::
+
+      See :download:`this example script <../example.py>`.
+
+   The given filename is usually relative to the directory the current source
+   file is contained in, but if it absolute (starting with ``/``), it is taken
+   as relative to the top source directory.
+
+   The ``example.py`` file will be copied to the output directory, and a
+   suitable link generated to it.
+
+   Not to show unavailable download links, you should wrap whole paragraphs that
+   have this role::
+
+      .. only:: builder_html
+
+         See :download:`this example script <../example.py>`.
+
+Cross-referencing figures by figure number
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 1.3
+
+.. versionchanged:: 1.5
+   `numref` role can also refer sections.
+   And `numref` allows `{name}` for the link text.
+
+.. rst:role:: numref
+
+   Link to the specified figures, tables, code-blocks and sections; the standard
+   reST labels are used.  When you use this role, it will insert a reference to
+   the figure with link text by its figure number like "Fig. 1.1".
+
+   If an explicit link text is given (as usual: ``:numref:`Image of Sphinx (Fig.
+   %s) <my-figure>```), the link caption will serve as title of the reference.
+   As placeholders, `%s` and `{number}` get replaced by the figure
+   number and  `{name}` by the figure caption.
+   If no explicit link text is given, the :confval:`numfig_format` setting is
+   used as fall-back default.
+
+   If :confval:`numfig` is ``False``, figures are not numbered,
+   so this role inserts not a reference but the label or the link text.
+
+Cross-referencing other items of interest
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following roles do possibly create a cross-reference, but do not refer to
+objects:
+
+.. rst:role:: envvar
+
+   An environment variable.  Index entries are generated.  Also generates a link
+   to the matching :rst:dir:`envvar` directive, if it exists.
+
+.. rst:role:: token
+
+   The name of a grammar token (used to create links between
+   :rst:dir:`productionlist` directives).
+
+.. rst:role:: keyword
+
+   The name of a keyword in Python.  This creates a link to a reference label
+   with that name, if it exists.
+
+.. rst:role:: option
+
+   A command-line option to an executable program.  This generates a link to
+   a :rst:dir:`option` directive, if it exists.
+
+
+The following role creates a cross-reference to a term in a
+:ref:`glossary <glossary-directive>`:
+
+.. rst:role:: term
+
+   Reference to a term in a glossary.  A glossary is created using the
+   ``glossary`` directive containing a definition list with terms and
+   definitions.  It does not have to be in the same file as the ``term`` markup,
+   for example the Python docs have one global glossary in the ``glossary.rst``
+   file.
+
+   If you use a term that's not explained in a glossary, you'll get a warning
+   during build.
+
+Inline code highlighting
+------------------------
+
+.. rst:role:: code
+
+   An *inline* code example.  When used directly, this role just displays the
+   text *without* syntax highlighting, as a literal.
+
+   .. code-block:: rst
+
+      By default, inline code such as :code:`1 + 2` just displays without
+      highlighting.
+
+   Displays: By default, inline code such as :code:`1 + 2` just displays without
+   highlighting.
+
+   Unlike the :rst:dir:`code-block` directive, this role does not respect the
+   default language set by the :rst:dir:`highlight` directive.
+
+   To enable syntax highlighting, you must first use the Docutils :dudir:`role`
+   directive to define a custom role associated with a specific language:
+
+   .. code-block:: rst
+
+      .. role:: python(code)
+         :language: python
+
+      In Python, :python:`1 + 2` is equal to :python:`3`.
+
+   To display a multi-line code example, use the :rst:dir:`code-block` directive
+   instead.
+
+Math
+----
+
+.. rst:role:: math
+
+   Role for inline math.  Use like this::
+
+      Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
+
+   Displays: Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
+
+.. rst:role:: eq
+
+   Same as :rst:role:`math:numref`.
+
+
+Other semantic markup
+---------------------
+
+The following roles don't do anything special except formatting the text in a
+different style:
+
+.. rst:role:: abbr
+
+   An abbreviation.  If the role content contains a parenthesized explanation,
+   it will be treated specially: it will be shown in a tool-tip in HTML, and
+   output only once in LaTeX.
+
+   For example: ``:abbr:`LIFO (last-in, first-out)``` displays
+   :abbr:`LIFO (last-in, first-out)`.
+
+   .. versionadded:: 0.6
+
+.. rst:role:: command
+
+   The name of an OS-level command, such as ``rm``.
+
+   For example: :command:`rm`
+
+.. rst:role:: dfn
+
+   Mark the defining instance of a term in the text.  (No index entries are
+   generated.)
+
+   For example: :dfn:`binary mode`
+
+.. rst:role:: file
+
+   The name of a file or directory.  Within the contents, you can use curly
+   braces to indicate a "variable" part, for example::
+
+      ... is installed in :file:`/usr/lib/python3.{x}/site-packages` ...
+
+   Displays: ... is installed in :file:`/usr/lib/python3.{x}/site-packages` ...
+
+   In the built documentation, the ``x`` will be displayed differently to
+   indicate that it is to be replaced by the Python minor version.
+
+.. rst:role:: guilabel
+
+   Labels presented as part of an interactive user interface should be marked
+   using ``guilabel``.  This includes labels from text-based interfaces such as
+   those created using :mod:`curses` or other text-based libraries.  Any label
+   used in the interface should be marked with this role, including button
+   labels, window titles, field names, menu and menu selection names, and even
+   values in selection lists.
+
+   .. versionchanged:: 1.0
+      An accelerator key for the GUI label can be included using an ampersand;
+      this will be stripped and displayed underlined in the output (for example:
+      ``:guilabel:`&Cancel``` displays :guilabel:`&Cancel`).  To include a literal
+      ampersand, double it.
+
+.. rst:role:: kbd
+
+   Mark a sequence of keystrokes.  What form the key sequence takes may depend
+   on platform- or application-specific conventions.  When there are no
+   relevant conventions, the names of modifier keys should be spelled out, to
+   improve accessibility for new users and non-native speakers.  For example,
+   an *xemacs* key sequence may be marked like ``:kbd:`C-x C-f```, but without
+   reference to a specific application or platform, the same sequence should be
+   marked as ``:kbd:`Control-x Control-f```, displaying :kbd:`C-x C-f` and
+   :kbd:`Control-x Control-f` respectively.
+
+.. rst:role:: mailheader
+
+   The name of an RFC 822-style mail header.  This markup does not imply that
+   the header is being used in an email message, but can be used to refer to
+   any header of the same "style."  This is also used for headers defined by
+   the various MIME specifications.  The header name should be entered in the
+   same way it would normally be found in practice, with the camel-casing
+   conventions being preferred where there is more than one common usage. For
+   example: ``:mailheader:`Content-Type``` displays :mailheader:`Content-Type`.
+
+.. rst:role:: makevar
+
+   The name of a :command:`make` variable.
+
+   For example: :makevar:`help`
+
+.. rst:role:: manpage
+
+   A reference to a Unix manual page including the section, e.g.
+   ``:manpage:`ls(1)``` displays :manpage:`ls(1)`. Creates a hyperlink to an
+   external site rendering the manpage if :confval:`manpages_url` is defined.
+
+.. rst:role:: menuselection
+
+   Menu selections should be marked using the ``menuselection`` role.  This is
+   used to mark a complete sequence of menu selections, including selecting
+   submenus and choosing a specific operation, or any subsequence of such a
+   sequence.  The names of individual selections should be separated by
+   ``-->``.
+
+   For example, to mark the selection "Start > Programs", use this markup::
+
+      :menuselection:`Start --> Programs`
+
+   Displays: :menuselection:`Start --> Programs`
+
+   When including a selection that includes some trailing indicator, such as
+   the ellipsis some operating systems use to indicate that the command opens a
+   dialog, the indicator should be omitted from the selection name.
+
+   ``menuselection`` also supports ampersand accelerators just like
+   :rst:role:`guilabel`.
+
+.. rst:role:: mimetype
+
+   The name of a MIME type, or a component of a MIME type (the major or minor
+   portion, taken alone).
+
+   For example: :mimetype:`text/plain`
+
+.. rst:role:: newsgroup
+
+   The name of a Usenet newsgroup.
+
+   For example: :newsgroup:`comp.lang.python`
+
+.. todo:: Is this not part of the standard domain?
+
+.. rst:role:: program
+
+   The name of an executable program.  This may differ from the file name for
+   the executable for some platforms.  In particular, the ``.exe`` (or other)
+   extension should be omitted for Windows programs.
+
+   For example: :program:`curl`
+
+.. rst:role:: regexp
+
+   A regular expression. Quotes should not be included.
+
+   For example: :regexp:`([abc])+`
+
+.. rst:role:: samp
+
+   A piece of literal text, such as code.  Within the contents, you can use
+   curly braces to indicate a "variable" part, as in :rst:role:`file`.  For
+   example, in ``:samp:`print 1+{variable}```, the part ``variable`` would be
+   emphasized: :samp:`print 1+{variable}`
+
+   If you don't need the "variable part" indication, use the standard
+   :rst:role:`code` role instead.
+
+   .. versionchanged:: 1.8
+      Allowed to escape curly braces with backslash
+
+There is also an :rst:role:`index` role to generate index entries.
+
+The following roles generate external links:
+
+.. rst:role:: pep
+
+   A reference to a Python Enhancement Proposal.  This generates appropriate
+   index entries. The text "PEP *number*\ " is generated; in the HTML output,
+   this text is a hyperlink to an online copy of the specified PEP.  You can
+   link to a specific section by saying ``:pep:`number#anchor```.
+
+   For example: :pep:`8`
+
+.. rst:role:: rfc
+
+   A reference to an Internet Request for Comments.  This generates appropriate
+   index entries. The text "RFC *number*\ " is generated; in the HTML output,
+   this text is a hyperlink to an online copy of the specified RFC.  You can
+   link to a specific section by saying ``:rfc:`number#anchor```.
+
+   For example: :rfc:`2324`
+
+Note that there are no special roles for including hyperlinks as you can use
+the standard reST markup for that purpose.
+
+
+.. _default-substitutions:
+
+Substitutions
+-------------
+
+The documentation system provides three substitutions that are defined by
+default. They are set in the build configuration file.
+
+.. describe:: |release|
+
+   Replaced by the project release the documentation refers to.  This is meant
+   to be the full version string including alpha/beta/release candidate tags,
+   e.g. ``2.5.2b3``.  Set by :confval:`release`.
+
+.. describe:: |version|
+
+   Replaced by the project version the documentation refers to. This is meant to
+   consist only of the major and minor version parts, e.g. ``2.5``, even for
+   version 2.5.1.  Set by :confval:`version`.
+
+.. describe:: |today|
+
+   Replaced by either today's date (the date on which the document is read), or
+   the date set in the build configuration file.  Normally has the format
+   ``April 14, 2007``.  Set by :confval:`today_fmt` and :confval:`today`.
+
+.. describe:: |translation progress|
+
+   Replaced by the translation progress of the document.
+   This substitution is intented for use by document translators
+   as a marker for the translation progress of the document.
diff --git a/doc/usage/theming.rst b/doc/usage/theming.rst
new file mode 100644
index 0000000..c33c7d4
--- /dev/null
+++ b/doc/usage/theming.rst
@@ -0,0 +1,364 @@
+.. highlight:: python
+
+.. _html-themes:
+
+HTML Theming
+============
+
+Sphinx provides a number of builders for HTML and HTML-based formats.
+
+Builders
+--------
+
+.. todo:: Populate when the 'builders' document is split up.
+
+
+Themes
+------
+
+.. versionadded:: 0.6
+
+.. note::
+
+   This section provides information about using pre-existing HTML themes. If
+   you wish to create your own theme, refer to
+   :doc:`/development/theming`.
+
+Sphinx supports changing the appearance of its HTML output via *themes*.  A
+theme is a collection of HTML templates, stylesheet(s) and other static files.
+Additionally, it has a configuration file which specifies from which theme to
+inherit, which highlighting style to use, and what options exist for customizing
+the theme's look and feel.
+
+Themes are meant to be project-unaware, so they can be used for different
+projects without change.
+
+Using a theme
+~~~~~~~~~~~~~
+
+Using a :ref:`theme provided with Sphinx <builtin-themes>` is easy. Since these
+do not need to be installed, you only need to set the :confval:`html_theme`
+config value. For example, to enable the ``classic`` theme, add the following
+to :file:`conf.py`::
+
+    html_theme = "classic"
+
+You can also set theme-specific options using the :confval:`html_theme_options`
+config value.  These options are generally used to change the look and feel of
+the theme. For example, to place the sidebar on the right side and a black
+background for the relation bar (the bar with the navigation links at the
+page's top and bottom), add the following :file:`conf.py`::
+
+    html_theme_options = {
+        "rightsidebar": "true",
+        "relbarbgcolor": "black"
+    }
+
+If the theme does not come with Sphinx, it can be in two static forms or as a
+Python package. For the static forms, either a directory (containing
+:file:`theme.conf` and other needed files), or a zip file with the same
+contents is supported. The directory or zipfile must be put where Sphinx can
+find it; for this there is the config value :confval:`html_theme_path`. This
+can be a list of directories, relative to the directory containing
+:file:`conf.py`, that can contain theme directories or zip files.  For example,
+if you have a theme in the file :file:`blue.zip`, you can put it right in the
+directory containing :file:`conf.py` and use this configuration::
+
+    html_theme = "blue"
+    html_theme_path = ["."]
+
+The third form is a Python package.  If a theme you want to use is distributed
+as a Python package, you can use it after installing
+
+.. code-block:: console
+
+    # installing theme package
+    $ pip install sphinxjp.themes.dotted
+
+Once installed, this can be used in the same manner as a directory or
+zipfile-based theme::
+
+    html_theme = "dotted"
+
+For more information on the design of themes, including information about
+writing your own themes, refer to :doc:`/development/theming`.
+
+.. _builtin-themes:
+
+Builtin themes
+~~~~~~~~~~~~~~
+
+.. cssclass:: longtable, standard
+
++--------------------+--------------------+
+| **Theme overview** |                    |
++--------------------+--------------------+
+| |alabaster|        | |classic|          |
+|                    |                    |
+| *alabaster*        | *classic*          |
++--------------------+--------------------+
+| |sphinxdoc|        | |scrolls|          |
+|                    |                    |
+| *sphinxdoc*        | *scrolls*          |
++--------------------+--------------------+
+| |agogo|            | |traditional|      |
+|                    |                    |
+| *agogo*            | *traditional*      |
++--------------------+--------------------+
+| |nature|           | |haiku|            |
+|                    |                    |
+| *nature*           | *haiku*            |
++--------------------+--------------------+
+| |pyramid|          | |bizstyle|         |
+|                    |                    |
+| *pyramid*          | *bizstyle*         |
++--------------------+--------------------+
+
+.. |alabaster|        image:: /_static/themes/alabaster.png
+.. |classic|          image:: /_static/themes/classic.png
+.. |sphinxdoc|        image:: /_static/themes/sphinxdoc.png
+.. |scrolls|          image:: /_static/themes/scrolls.png
+.. |agogo|            image:: /_static/themes/agogo.png
+.. |traditional|      image:: /_static/themes/traditional.png
+.. |nature|           image:: /_static/themes/nature.png
+.. |haiku|            image:: /_static/themes/haiku.png
+.. |pyramid|          image:: /_static/themes/pyramid.png
+.. |bizstyle|         image:: /_static/themes/bizstyle.png
+
+Sphinx comes with a selection of themes to choose from.
+
+Note that from these themes only the Alabaster and Scrolls themes are
+mobile-optimated, the other themes resort to horizontal scrolling
+if the screen is too narrow.
+
+.. cssclass:: clear
+
+These themes are:
+
+**basic**
+  This is a basically unstyled layout used as the base for the
+  other themes, and usable as the base for custom themes as well.  The HTML
+  contains all important elements like sidebar and relation bar.  There are
+  these options (which are inherited by the other themes):
+
+  - **nosidebar** (true or false): Don't include the sidebar.  Defaults to
+    ``False``.
+
+  - **sidebarwidth** (int or str): Width of the sidebar in pixels.
+    This can be an int, which is interpreted as pixels or a valid CSS
+    dimension string such as '70em' or '50%'.  Defaults to 230 pixels.
+
+  - **body_min_width** (int or str): Minimal width of the document body.
+    This can be an int, which is interpreted as pixels or a valid CSS
+    dimension string such as '70em' or '50%'. Use 0 if you don't want
+    a width limit. Defaults may depend on the theme (often 450px).
+
+  - **body_max_width** (int or str): Maximal width of the document body.
+    This can be an int, which is interpreted as pixels or a valid CSS
+    dimension string such as '70em' or '50%'. Use 'none' if you don't
+    want a width limit. Defaults may depend on the theme (often 800px).
+
+  - **navigation_with_keys** (true or false): Allow navigating
+    with the following keyboard shortcuts:
+
+    - :kbd:`Left arrow`: previous page
+    - :kbd:`Right arrow`: next page
+
+    Defaults to ``False``.
+
+  - **enable_search_shortcuts** (true or false): Allow jumping to the search box
+    with :kbd:`/` and allow removal of search highlighting with :kbd:`Esc`.
+
+    Defaults to ``True``.
+
+  - **globaltoc_collapse** (true or false): Only expand subsections
+    of the current document in ``globaltoc.html``
+    (see :confval:`html_sidebars`).
+    Defaults to ``True``.
+
+    .. versionadded:: 3.1
+
+  - **globaltoc_includehidden** (true or false): Show even those
+    subsections in ``globaltoc.html`` (see :confval:`html_sidebars`)
+    which have been included with the ``:hidden:`` flag of the
+    :rst:dir:`toctree` directive.
+    Defaults to ``False``.
+
+    .. versionadded:: 3.1
+
+  - **globaltoc_maxdepth** (int): The maximum depth of the toctree in
+    ``globaltoc.html`` (see :confval:`html_sidebars`).  Set it to -1 to allow
+    unlimited depth. Defaults to the max depth selected in the toctree directive.
+
+    .. versionadded:: 3.2
+
+**alabaster**
+  `Alabaster theme`_ is a modified "Kr" Sphinx theme from @kennethreitz
+  (especially as used in his Requests project), which was itself originally
+  based on @mitsuhiko's theme used for Flask & related projects.  Refer to its
+  `installation page`_ for information on how to configure
+  :confval:`html_sidebars` for its use.
+
+  .. _Alabaster theme: https://pypi.org/project/alabaster/
+  .. _installation page: https://alabaster.readthedocs.io/en/latest/installation.html
+
+**classic**
+  This is the classic theme, which looks like `the Python 2
+  documentation <https://docs.python.org/2/>`_.  It can be customized via
+  these options:
+
+  - **rightsidebar** (true or false): Put the sidebar on the right side.
+    Defaults to ``False``.
+
+  - **stickysidebar** (true or false): Make the sidebar "fixed" so that it
+    doesn't scroll out of view for long body content.  This may not work well
+    with all browsers.  Defaults to ``False``.
+
+  - **collapsiblesidebar** (true or false): Add an *experimental* JavaScript
+    snippet that makes the sidebar collapsible via a button on its side.
+    Defaults to ``False``.
+
+  - **externalrefs** (true or false): Display external links differently from
+    internal links.  Defaults to ``False``.
+
+  There are also various color and font options that can change the color scheme
+  without having to write a custom stylesheet:
+
+  - **footerbgcolor** (CSS color): Background color for the footer line.
+  - **footertextcolor** (CSS color): Text color for the footer line.
+  - **sidebarbgcolor** (CSS color): Background color for the sidebar.
+  - **sidebarbtncolor** (CSS color): Background color for the sidebar collapse
+    button (used when *collapsiblesidebar* is ``True``).
+  - **sidebartextcolor** (CSS color): Text color for the sidebar.
+  - **sidebarlinkcolor** (CSS color): Link color for the sidebar.
+  - **relbarbgcolor** (CSS color): Background color for the relation bar.
+  - **relbartextcolor** (CSS color): Text color for the relation bar.
+  - **relbarlinkcolor** (CSS color): Link color for the relation bar.
+  - **bgcolor** (CSS color): Body background color.
+  - **textcolor** (CSS color): Body text color.
+  - **linkcolor** (CSS color): Body link color.
+  - **visitedlinkcolor** (CSS color): Body color for visited links.
+  - **headbgcolor** (CSS color): Background color for headings.
+  - **headtextcolor** (CSS color): Text color for headings.
+  - **headlinkcolor** (CSS color): Link color for headings.
+  - **codebgcolor** (CSS color): Background color for code blocks.
+  - **codetextcolor** (CSS color): Default text color for code blocks, if not
+    set differently by the highlighting style.
+
+  - **bodyfont** (CSS font-family): Font for normal text.
+  - **headfont** (CSS font-family): Font for headings.
+
+**sphinxdoc**
+  The theme originally used by this documentation. It features
+  a sidebar on the right side. There are currently no options beyond
+  *nosidebar* and *sidebarwidth*.
+
+  .. note::
+
+    The Sphinx documentation now uses
+    `an adjusted version of the sphinxdoc theme
+    <https://github.com/sphinx-doc/sphinx/tree/master/doc/_themes/sphinx13>`_.
+
+**scrolls**
+  A more lightweight theme, based on `the Jinja documentation
+  <https://jinja.palletsprojects.com/>`_.  The following color options are
+  available:
+
+  - **headerbordercolor**
+  - **subheadlinecolor**
+  - **linkcolor**
+  - **visitedlinkcolor**
+  - **admonitioncolor**
+
+**agogo**
+  A theme created by Andi Albrecht.  The following options are supported:
+
+  - **bodyfont** (CSS font family): Font for normal text.
+  - **headerfont** (CSS font family): Font for headings.
+  - **pagewidth** (CSS length): Width of the page content, default 70em.
+  - **documentwidth** (CSS length): Width of the document (without sidebar),
+    default 50em.
+  - **sidebarwidth** (CSS length): Width of the sidebar, default 20em.
+  - **rightsidebar** (true or false): Put the sidebar on the right side.
+    Defaults to ``True``.
+  - **bgcolor** (CSS color): Background color.
+  - **headerbg** (CSS value for "background"): background for the header area,
+    default a grayish gradient.
+  - **footerbg** (CSS value for "background"): background for the footer area,
+    default a light gray gradient.
+  - **linkcolor** (CSS color): Body link color.
+  - **headercolor1**, **headercolor2** (CSS color): colors for <h1> and <h2>
+    headings.
+  - **headerlinkcolor** (CSS color): Color for the backreference link in
+    headings.
+  - **textalign** (CSS *text-align* value): Text alignment for the body, default
+    is ``justify``.
+
+**nature**
+  A greenish theme.  There are currently no options beyond
+  *nosidebar* and *sidebarwidth*.
+
+**pyramid**
+  A theme from the Pyramid web framework project, designed by Blaise Laflamme.
+  There are currently no options beyond *nosidebar* and *sidebarwidth*.
+
+**haiku**
+  A theme without sidebar inspired by the `Haiku OS user guide
+  <https://www.haiku-os.org/docs/userguide/en/contents.html>`_.  The following
+  options are supported:
+
+  - **full_logo** (true or false, default ``False``): If this is true, the
+    header will only show the :confval:`html_logo`.  Use this for large logos.
+    If this is false, the logo (if present) will be shown floating right, and
+    the documentation title will be put in the header.
+
+  - **textcolor**, **headingcolor**, **linkcolor**, **visitedlinkcolor**,
+    **hoverlinkcolor** (CSS colors): Colors for various body elements.
+
+**traditional**
+  A theme resembling the old Python documentation.  There are
+  currently no options beyond *nosidebar* and *sidebarwidth*.
+
+**epub**
+  A theme for the epub builder.  This theme tries to save visual
+  space which is a sparse resource on ebook readers.  The following options
+  are supported:
+
+  - **relbar1** (true or false, default ``True``): If this is true, the
+    `relbar1` block is inserted in the epub output, otherwise it is omitted.
+
+  - **footer**  (true or false, default ``True``): If this is true, the
+    `footer` block is inserted in the epub output, otherwise it is omitted.
+
+**bizstyle**
+  A simple bluish theme. The following options are supported
+  beyond *nosidebar* and *sidebarwidth*:
+
+  - **rightsidebar** (true or false): Put the sidebar on the right side.
+    Defaults to ``False``.
+
+.. versionadded:: 1.3
+   'alabaster', 'sphinx_rtd_theme' and 'bizstyle' theme.
+
+.. versionchanged:: 1.3
+   The 'default' theme has been renamed to 'classic'. 'default' is still
+   available, however it will emit a notice that it is an alias for the new
+   'alabaster' theme.
+
+.. _third-party-themes:
+
+Third Party Themes
+~~~~~~~~~~~~~~~~~~
+
+There are many third-party themes created for Sphinx. Some of these are for
+general use, while others are specific to an individual project.
+
+sphinx-themes.org__ is a gallery that showcases various themes for Sphinx,
+with demo documentation rendered under each theme. Themes can also be found
+on PyPI__ (using the classifier ``Framework :: Sphinx :: Theme``), GitHub__
+and GitLab__.
+
+.. __: https://sphinx-themes.org/
+.. __: https://pypi.org/search/?q=&o=&c=Framework+%3A%3A+Sphinx+%3A%3A+Theme
+.. __: https://github.com/search?utf8=%E2%9C%93&q=sphinx+theme
+.. __: https://gitlab.com/explore?name=sphinx+theme