summaryrefslogtreecommitdiffstats
path: root/doc/usage
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 17:25:40 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 17:25:40 +0000
commitcf7da1843c45a4c2df7a749f7886a2d2ba0ee92a (patch)
tree18dcde1a8d1f5570a77cd0c361de3b490d02c789 /doc/usage
parentInitial commit. (diff)
downloadsphinx-cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a.tar.xz
sphinx-cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a.zip
Adding upstream version 7.2.6.upstream/7.2.6
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/usage')
-rw-r--r--doc/usage/advanced/intl.rst372
-rw-r--r--doc/usage/advanced/websupport/api.rst80
-rw-r--r--doc/usage/advanced/websupport/index.rst16
-rw-r--r--doc/usage/advanced/websupport/quickstart.rst255
-rw-r--r--doc/usage/advanced/websupport/searchadapters.rst49
-rw-r--r--doc/usage/advanced/websupport/storagebackends.rst49
-rw-r--r--doc/usage/builders/index.rst565
-rw-r--r--doc/usage/configuration.rst3094
-rw-r--r--doc/usage/extensions/autodoc.rst853
-rw-r--r--doc/usage/extensions/autosectionlabel.rst56
-rw-r--r--doc/usage/extensions/autosummary.rst364
-rw-r--r--doc/usage/extensions/coverage.rst99
-rw-r--r--doc/usage/extensions/doctest.rst385
-rw-r--r--doc/usage/extensions/duration.rst11
-rw-r--r--doc/usage/extensions/example_google.py309
-rw-r--r--doc/usage/extensions/example_google.rst17
-rw-r--r--doc/usage/extensions/example_numpy.py350
-rw-r--r--doc/usage/extensions/example_numpy.rst17
-rw-r--r--doc/usage/extensions/extlinks.rst69
-rw-r--r--doc/usage/extensions/githubpages.rst16
-rw-r--r--doc/usage/extensions/graphviz.rst239
-rw-r--r--doc/usage/extensions/ifconfig.rst38
-rw-r--r--doc/usage/extensions/imgconverter.rst55
-rw-r--r--doc/usage/extensions/index.rst81
-rw-r--r--doc/usage/extensions/inheritance.rst174
-rw-r--r--doc/usage/extensions/intersphinx.rst250
-rw-r--r--doc/usage/extensions/linkcode.rst51
-rw-r--r--doc/usage/extensions/math.rst320
-rw-r--r--doc/usage/extensions/napoleon.rst574
-rw-r--r--doc/usage/extensions/todo.rst62
-rw-r--r--doc/usage/extensions/viewcode.rst106
-rw-r--r--doc/usage/index.rst20
-rw-r--r--doc/usage/installation.rst282
-rw-r--r--doc/usage/markdown.rst52
-rw-r--r--doc/usage/quickstart.rst348
-rw-r--r--doc/usage/restructuredtext/basics.rst631
-rw-r--r--doc/usage/restructuredtext/directives.rst1311
-rw-r--r--doc/usage/restructuredtext/domains.rst2303
-rw-r--r--doc/usage/restructuredtext/field-lists.rst78
-rw-r--r--doc/usage/restructuredtext/index.rst24
-rw-r--r--doc/usage/restructuredtext/roles.rst536
-rw-r--r--doc/usage/theming.rst364
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