summaryrefslogtreecommitdiffstats
path: root/doc
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
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')
-rw-r--r--doc/Makefile20
-rw-r--r--doc/_static/Makefile6
-rw-r--r--doc/_static/bookcover.pngbin0 -> 27523 bytes
-rw-r--r--doc/_static/conf.py.txt346
-rw-r--r--doc/_static/favicon.svg8
-rw-r--r--doc/_static/more.pngbin0 -> 1351 bytes
-rw-r--r--doc/_static/sphinx.pngbin0 -> 34213 bytes
-rw-r--r--doc/_static/themes/agogo.pngbin0 -> 25792 bytes
-rw-r--r--doc/_static/themes/alabaster.pngbin0 -> 32356 bytes
-rw-r--r--doc/_static/themes/bizstyle.pngbin0 -> 27139 bytes
-rw-r--r--doc/_static/themes/classic.pngbin0 -> 39927 bytes
-rw-r--r--doc/_static/themes/fullsize/agogo.pngbin0 -> 56954 bytes
-rw-r--r--doc/_static/themes/fullsize/alabaster.pngbin0 -> 40248 bytes
-rw-r--r--doc/_static/themes/fullsize/bizstyle.pngbin0 -> 75192 bytes
-rw-r--r--doc/_static/themes/fullsize/classic.pngbin0 -> 72597 bytes
-rw-r--r--doc/_static/themes/fullsize/haiku.pngbin0 -> 84200 bytes
-rw-r--r--doc/_static/themes/fullsize/nature.pngbin0 -> 32266 bytes
-rw-r--r--doc/_static/themes/fullsize/pyramid.pngbin0 -> 102717 bytes
-rw-r--r--doc/_static/themes/fullsize/scrolls.pngbin0 -> 88111 bytes
-rw-r--r--doc/_static/themes/fullsize/sphinx_rtd_theme.pngbin0 -> 39411 bytes
-rw-r--r--doc/_static/themes/fullsize/sphinxdoc.pngbin0 -> 84439 bytes
-rw-r--r--doc/_static/themes/fullsize/traditional.pngbin0 -> 91744 bytes
-rw-r--r--doc/_static/themes/haiku.pngbin0 -> 43184 bytes
-rw-r--r--doc/_static/themes/nature.pngbin0 -> 28536 bytes
-rw-r--r--doc/_static/themes/pyramid.pngbin0 -> 38805 bytes
-rw-r--r--doc/_static/themes/scrolls.pngbin0 -> 27800 bytes
-rw-r--r--doc/_static/themes/sphinx_rtd_theme.pngbin0 -> 29138 bytes
-rw-r--r--doc/_static/themes/sphinxdoc.pngbin0 -> 30225 bytes
-rw-r--r--doc/_static/themes/traditional.pngbin0 -> 32258 bytes
-rw-r--r--doc/_static/translation.pngbin0 -> 16371 bytes
-rw-r--r--doc/_static/translation.puml16
-rw-r--r--doc/_static/translation.svg42
-rw-r--r--doc/_static/tutorial/lumache-autosummary.pngbin0 -> 26500 bytes
-rw-r--r--doc/_static/tutorial/lumache-first-light.pngbin0 -> 52126 bytes
-rw-r--r--doc/_static/tutorial/lumache-furo.pngbin0 -> 51223 bytes
-rw-r--r--doc/_static/tutorial/lumache-py-function-full.pngbin0 -> 71741 bytes
-rw-r--r--doc/_static/tutorial/lumache-py-function.pngbin0 -> 41828 bytes
-rw-r--r--doc/_templates/contents.html8
-rw-r--r--doc/_themes/sphinx13/layout.html60
-rw-r--r--doc/_themes/sphinx13/static/sphinx13.css362
-rw-r--r--doc/_themes/sphinx13/static/sphinxheader.pngbin0 -> 11719 bytes
-rw-r--r--doc/_themes/sphinx13/theme.conf4
-rw-r--r--doc/authors.rst9
-rw-r--r--doc/changes.rst22
-rw-r--r--doc/conf.py244
-rw-r--r--doc/development/builders.rst34
-rw-r--r--doc/development/index.rst24
-rw-r--r--doc/development/overview.rst32
-rw-r--r--doc/development/templating.rst478
-rw-r--r--doc/development/theming.rst342
-rw-r--r--doc/development/tutorials/autodoc_ext.rst141
-rw-r--r--doc/development/tutorials/examples/README.rst11
-rw-r--r--doc/development/tutorials/examples/autodoc_intenum.py58
-rw-r--r--doc/development/tutorials/examples/helloworld.py19
-rw-r--r--doc/development/tutorials/examples/recipe.py159
-rw-r--r--doc/development/tutorials/examples/todo.py135
-rw-r--r--doc/development/tutorials/helloworld.rst189
-rw-r--r--doc/development/tutorials/index.rst17
-rw-r--r--doc/development/tutorials/recipe.rst227
-rw-r--r--doc/development/tutorials/todo.rst367
-rw-r--r--doc/examples.rst5
-rw-r--r--doc/extdev/appapi.rst473
-rw-r--r--doc/extdev/builderapi.rst46
-rw-r--r--doc/extdev/collectorapi.rst9
-rw-r--r--doc/extdev/deprecated.rst1911
-rw-r--r--doc/extdev/domainapi.rst32
-rw-r--r--doc/extdev/envapi.rst58
-rw-r--r--doc/extdev/i18n.rst97
-rw-r--r--doc/extdev/index.rst218
-rw-r--r--doc/extdev/logging.rst66
-rw-r--r--doc/extdev/markupapi.rst152
-rw-r--r--doc/extdev/nodes.rst103
-rw-r--r--doc/extdev/parserapi.rst38
-rw-r--r--doc/extdev/projectapi.rst9
-rw-r--r--doc/extdev/utils.rst37
-rw-r--r--doc/faq.rst354
-rw-r--r--doc/glossary.rst103
-rw-r--r--doc/index.rst117
-rw-r--r--doc/internals/code-of-conduct.rst5
-rw-r--r--doc/internals/contributing.rst332
-rw-r--r--doc/internals/index.rst15
-rw-r--r--doc/internals/organization.rst56
-rw-r--r--doc/internals/release-process.rst125
-rw-r--r--doc/latex.rst1841
-rw-r--r--doc/make.bat32
-rw-r--r--doc/man/index.rst22
-rw-r--r--doc/man/sphinx-apidoc.rst171
-rw-r--r--doc/man/sphinx-autogen.rst97
-rw-r--r--doc/man/sphinx-build.rst355
-rw-r--r--doc/man/sphinx-quickstart.rst169
-rw-r--r--doc/support.rst20
-rw-r--r--doc/tutorial/automatic-doc-generation.rst165
-rw-r--r--doc/tutorial/deploying.rst281
-rw-r--r--doc/tutorial/describing-code.rst276
-rw-r--r--doc/tutorial/end.rst6
-rw-r--r--doc/tutorial/first-steps.rst92
-rw-r--r--doc/tutorial/getting-started.rst120
-rw-r--r--doc/tutorial/index.rst39
-rw-r--r--doc/tutorial/more-sphinx-customization.rst78
-rw-r--r--doc/tutorial/narrative-documentation.rst130
-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
142 files changed, 26560 insertions, 0 deletions
diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..84eafdb
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,20 @@
+# Makefile for Sphinx documentation
+#
+PYTHON ?= python3
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = $(PYTHON) ../sphinx/cmd/build.py
+SOURCEDIR = .
+BUILDDIR = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/doc/_static/Makefile b/doc/_static/Makefile
new file mode 100644
index 0000000..8c880bc
--- /dev/null
+++ b/doc/_static/Makefile
@@ -0,0 +1,6 @@
+translation.png: translation.puml
+ plantuml -tpng $<
+translation.svg: translation.puml
+ plantuml -tsvg $<
+clean:
+ rm -f translation.png translation.svg
diff --git a/doc/_static/bookcover.png b/doc/_static/bookcover.png
new file mode 100644
index 0000000..0a8167f
--- /dev/null
+++ b/doc/_static/bookcover.png
Binary files differ
diff --git a/doc/_static/conf.py.txt b/doc/_static/conf.py.txt
new file mode 100644
index 0000000..c5e75e0
--- /dev/null
+++ b/doc/_static/conf.py.txt
@@ -0,0 +1,346 @@
+# test documentation build configuration file, created by
+# sphinx-quickstart on Sun Jun 26 00:00:43 2016.
+#
+# This file is executed through importlib.import_module with
+# the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The encoding of source files.
+#
+# source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+root_doc = 'index'
+
+# General information about the project.
+project = 'test'
+copyright = '2016, test'
+author = 'test'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = 'test'
+# The full version, including alpha/beta/rc tags.
+release = 'test'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#
+# today = ''
+#
+# Else, today_fmt is used as the format for a strftime call.
+#
+# today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# These patterns also affect html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#
+# default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#
+# add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#
+# add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#
+# show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+# modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+# keep_warnings = False
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+# html_theme_path = []
+
+# The name for this set of Sphinx documents.
+# "<project> v<release> documentation" by default.
+#
+# html_title = 'test vtest'
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#
+# html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#
+# html_logo = None
+
+# The name of an image file (relative to this directory) to use as a favicon of
+# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#
+# html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#
+# html_extra_path = []
+
+# If not None, a 'Last updated on:' timestamp is inserted at every page
+# bottom, using the given strftime format.
+# The empty string is equivalent to '%b %d, %Y'.
+#
+# html_last_updated_fmt = None
+
+# Custom sidebar templates, maps document names to template names.
+#
+# html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#
+# html_additional_pages = {}
+
+# If false, no module index is generated.
+#
+# html_domain_indices = True
+
+# If false, no index is generated.
+#
+# html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#
+# html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#
+# html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#
+# html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#
+# html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#
+# html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+# html_file_suffix = None
+
+# Language to be used for generating the HTML full-text search index.
+# Sphinx supports the following languages:
+# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
+# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
+#
+# html_search_language = 'en'
+
+# A dictionary with options for the search language support, empty by default.
+# 'ja' uses this config value.
+# 'zh' user can custom change `jieba` dictionary path.
+#
+# html_search_options = {'type': 'default'}
+
+# The name of a javascript file (relative to the configuration directory) that
+# implements a search results scorer. If empty, the default will be used.
+#
+# html_search_scorer = 'scorer.js'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'testdoc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+ # The paper size ('letterpaper' or 'a4paper').
+ #
+ # 'papersize': 'letterpaper',
+
+ # The font size ('10pt', '11pt' or '12pt').
+ #
+ # 'pointsize': '10pt',
+
+ # Additional stuff for the LaTeX preamble.
+ #
+ # 'preamble': '',
+
+ # Latex figure (float) alignment
+ #
+ # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+# author, documentclass [howto, manual, or own class]).
+latex_documents = [
+ (root_doc, 'test.tex', 'test Documentation',
+ 'test', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#
+# latex_logo = None
+
+# If true, show page references after internal links.
+#
+# latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#
+# latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#
+# latex_appendices = []
+
+# If false, no module index is generated.
+#
+# latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ (root_doc, 'test', 'test Documentation',
+ [author], 1)
+]
+
+# If true, show URL addresses after external links.
+#
+# man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+# dir menu entry, description, category)
+texinfo_documents = [
+ (root_doc, 'test', 'test Documentation',
+ author, 'test', 'One line description of project.',
+ 'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#
+# texinfo_appendices = []
+
+# If false, no module index is generated.
+#
+# texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#
+# texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#
+# texinfo_no_detailmenu = False
+
+# If false, do not generate in manual @ref nodes.
+#
+# texinfo_cross_references = False
+
+# -- A random example -----------------------------------------------------
+
+import sys, os
+sys.path.insert(0, os.path.abspath('.'))
+exclude_patterns = ['zzz']
+
+numfig = True
+#language = 'ja'
+
+extensions.append('sphinx.ext.todo')
+extensions.append('sphinx.ext.autodoc')
+#extensions.append('sphinx.ext.autosummary')
+extensions.append('sphinx.ext.intersphinx')
+extensions.append('sphinx.ext.mathjax')
+extensions.append('sphinx.ext.viewcode')
+extensions.append('sphinx.ext.graphviz')
+
+
+autosummary_generate = True
+html_theme = 'default'
+#source_suffix = ['.rst', '.txt']
diff --git a/doc/_static/favicon.svg b/doc/_static/favicon.svg
new file mode 100644
index 0000000..c3e1acd
--- /dev/null
+++ b/doc/_static/favicon.svg
@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+ <style>
+ @media (prefers-color-scheme: dark) {
+ svg { fill: white; }
+ }
+ </style>
+ <path d="m 67.780707,71.526216 c 0,-2.720856 0.735772,-7.633735 1.635035,-10.917507 2.076574,-7.582764 3.222746,-16.97568 2.071477,-16.97568 -0.485619,0 -3.994408,3.173002 -7.797313,7.051115 -14.448869,14.734603 -29.952812,23.068339 -42.915946,23.068339 -7.400211,0 -12.4298817,-1.871115 -17.2867007,-6.430912 -2.94436186,-2.764297 -3.47532146,-4.129685 -3.47532146,-8.936928 0,-4.94488 0.4862322,-6.108589 3.78321146,-9.054437 2.987989,-2.669773 4.875111,-3.380296 8.9779137,-3.380296 3.163221,0.711278 5.032659,0.664017 6.063532,1.917191 1.045041,1.231842 1.406892,5.262673 0.143323,7.623675 -0.674746,1.260763 -2.435471,2.043539 -4.5966,2.043539 -2.040303,0 -3.203991,-0.483702 -2.786976,-1.15844 1.31395,-2.126021 -0.560952,-3.566616 -2.9664067,-2.279256 -2.907025,1.555792 -2.957418,7.069066 -0.08839,9.665535 4.0345357,3.651203 15.1912207,5.023925 21.9019857,2.694828 7.250749,-2.516503 16.739014,-8.578986 24.30831,-15.531674 l 6.657407,-6.115083 -8.688303,-0.05007 C 43.622519,44.707714 37.702703,43.621524 18.54695,38.489741 12.175528,36.782852 6.0502733,35.306342 4.9352743,35.208608 3.6710803,35.097791 2.841723,34.067882 2.9080043,32.476074 3.0199286,29.788108 4.4800823,27.78768 6.2067673,27.033038 7.2437505,26.579828 14.43583,25.894406 22.0605,23.866486 c 29.699148,-7.899023 31.502043,-6.781254 51.28707,-1.772167 6.461504,1.635896 13.942408,3.414988 17.256961,3.474566 5.106245,0.09178 6.211825,0.514653 7.240255,2.76932 0.66758,1.46355 1.21378,2.858905 1.21378,3.10079 0,0.241884 -2.89333,1.764397 -6.429613,3.383363 -12.984983,5.944723 -17.083271,9.093943 -12.855172,15.130399 1.753219,2.503069 1.718037,2.768923 -0.57922,4.37799 -1.345193,0.942203 -2.457238,2.856456 -2.471232,4.253898 -0.03777,3.776976 -2.424786,11.884847 -5.893734,15.080164 l -3.048923,2.808424 z m 6.632814,-34.658372 c 5.169656,-1.440693 8.302047,-3.07045 14.72913,-6.500861 -5.292267,-1.548658 -18.570782,-3.724097 -18.570782,-3.724097 -9.796513,-1.964547 -8.76916,-1.865132 -9.21348,0.29669 -0.176673,0.859598 -0.702644,2.763948 -1.872329,4.596663 -2.251474,3.527711 -10.489307,4.271075 -15.214327,2.009703 -1.482367,-0.709454 -2.971272,-3.416276 -2.950606,-5.336922 0.02911,-2.705486 -1.505386,-3.336055 -2.486689,-2.975309 -0.796428,0.292781 -3.384665,0.330004 -9.071284,1.864262 -18.784765,5.068157 -21.3552119,4.487473 -9.110967,6.223299 1.472409,0.208739 9.252992,2.381926 13.052028,3.39412 9.318588,2.482796 11.064717,2.665087 23.125496,2.414247 8.385835,-0.174409 11.891174,-0.675356 17.58381,-2.261795 z M 3.0589449,14.916483 C 3.2921927,12.514245 3.424378,11.992797 10.100599,10.647894 13.924923,9.8774962 23.355266,7.3808108 31.056903,5.0997052 c 17.703937,-5.2436279 22.73392,-5.2565016 41.092202,-0.105175 7.923233,2.2232606 16.798382,4.047803 19.72254,4.054541 4.567242,0.01054 6.941892,2.0284768 6.941892,2.0284768 2.101843,4.825342 1.718463,5.158474 -6.484103,5.158474 -5.714193,0 -10.641875,-0.963081 -18.245438,-3.565943 C 68.300078,10.69012 60.060462,8.8316882 55.557963,8.4915615 47.342337,7.8709375 47.353713,7.8687835 21.963188,14.855617 17.503192,16.082896 11.34213,17.454164 8.2719268,17.902883 l -5.5821654,0.81585 z" />
+</svg>
diff --git a/doc/_static/more.png b/doc/_static/more.png
new file mode 100644
index 0000000..97553a8
--- /dev/null
+++ b/doc/_static/more.png
Binary files differ
diff --git a/doc/_static/sphinx.png b/doc/_static/sphinx.png
new file mode 100644
index 0000000..0a103cd
--- /dev/null
+++ b/doc/_static/sphinx.png
Binary files differ
diff --git a/doc/_static/themes/agogo.png b/doc/_static/themes/agogo.png
new file mode 100644
index 0000000..5a09cb9
--- /dev/null
+++ b/doc/_static/themes/agogo.png
Binary files differ
diff --git a/doc/_static/themes/alabaster.png b/doc/_static/themes/alabaster.png
new file mode 100644
index 0000000..4a49c1a
--- /dev/null
+++ b/doc/_static/themes/alabaster.png
Binary files differ
diff --git a/doc/_static/themes/bizstyle.png b/doc/_static/themes/bizstyle.png
new file mode 100644
index 0000000..e19fb6b
--- /dev/null
+++ b/doc/_static/themes/bizstyle.png
Binary files differ
diff --git a/doc/_static/themes/classic.png b/doc/_static/themes/classic.png
new file mode 100644
index 0000000..3b3c9cb
--- /dev/null
+++ b/doc/_static/themes/classic.png
Binary files differ
diff --git a/doc/_static/themes/fullsize/agogo.png b/doc/_static/themes/fullsize/agogo.png
new file mode 100644
index 0000000..106a16c
--- /dev/null
+++ b/doc/_static/themes/fullsize/agogo.png
Binary files differ
diff --git a/doc/_static/themes/fullsize/alabaster.png b/doc/_static/themes/fullsize/alabaster.png
new file mode 100644
index 0000000..5eca209
--- /dev/null
+++ b/doc/_static/themes/fullsize/alabaster.png
Binary files differ
diff --git a/doc/_static/themes/fullsize/bizstyle.png b/doc/_static/themes/fullsize/bizstyle.png
new file mode 100644
index 0000000..5860647
--- /dev/null
+++ b/doc/_static/themes/fullsize/bizstyle.png
Binary files differ
diff --git a/doc/_static/themes/fullsize/classic.png b/doc/_static/themes/fullsize/classic.png
new file mode 100644
index 0000000..269dab2
--- /dev/null
+++ b/doc/_static/themes/fullsize/classic.png
Binary files differ
diff --git a/doc/_static/themes/fullsize/haiku.png b/doc/_static/themes/fullsize/haiku.png
new file mode 100644
index 0000000..707d2bf
--- /dev/null
+++ b/doc/_static/themes/fullsize/haiku.png
Binary files differ
diff --git a/doc/_static/themes/fullsize/nature.png b/doc/_static/themes/fullsize/nature.png
new file mode 100644
index 0000000..00730c0
--- /dev/null
+++ b/doc/_static/themes/fullsize/nature.png
Binary files differ
diff --git a/doc/_static/themes/fullsize/pyramid.png b/doc/_static/themes/fullsize/pyramid.png
new file mode 100644
index 0000000..3b9d04d
--- /dev/null
+++ b/doc/_static/themes/fullsize/pyramid.png
Binary files differ
diff --git a/doc/_static/themes/fullsize/scrolls.png b/doc/_static/themes/fullsize/scrolls.png
new file mode 100644
index 0000000..8a1c1fa
--- /dev/null
+++ b/doc/_static/themes/fullsize/scrolls.png
Binary files differ
diff --git a/doc/_static/themes/fullsize/sphinx_rtd_theme.png b/doc/_static/themes/fullsize/sphinx_rtd_theme.png
new file mode 100644
index 0000000..95cff4c
--- /dev/null
+++ b/doc/_static/themes/fullsize/sphinx_rtd_theme.png
Binary files differ
diff --git a/doc/_static/themes/fullsize/sphinxdoc.png b/doc/_static/themes/fullsize/sphinxdoc.png
new file mode 100644
index 0000000..eb498e3
--- /dev/null
+++ b/doc/_static/themes/fullsize/sphinxdoc.png
Binary files differ
diff --git a/doc/_static/themes/fullsize/traditional.png b/doc/_static/themes/fullsize/traditional.png
new file mode 100644
index 0000000..07ad008
--- /dev/null
+++ b/doc/_static/themes/fullsize/traditional.png
Binary files differ
diff --git a/doc/_static/themes/haiku.png b/doc/_static/themes/haiku.png
new file mode 100644
index 0000000..4530deb
--- /dev/null
+++ b/doc/_static/themes/haiku.png
Binary files differ
diff --git a/doc/_static/themes/nature.png b/doc/_static/themes/nature.png
new file mode 100644
index 0000000..ad39b32
--- /dev/null
+++ b/doc/_static/themes/nature.png
Binary files differ
diff --git a/doc/_static/themes/pyramid.png b/doc/_static/themes/pyramid.png
new file mode 100644
index 0000000..72749dd
--- /dev/null
+++ b/doc/_static/themes/pyramid.png
Binary files differ
diff --git a/doc/_static/themes/scrolls.png b/doc/_static/themes/scrolls.png
new file mode 100644
index 0000000..1a11737
--- /dev/null
+++ b/doc/_static/themes/scrolls.png
Binary files differ
diff --git a/doc/_static/themes/sphinx_rtd_theme.png b/doc/_static/themes/sphinx_rtd_theme.png
new file mode 100644
index 0000000..7c3b7ae
--- /dev/null
+++ b/doc/_static/themes/sphinx_rtd_theme.png
Binary files differ
diff --git a/doc/_static/themes/sphinxdoc.png b/doc/_static/themes/sphinxdoc.png
new file mode 100644
index 0000000..587363e
--- /dev/null
+++ b/doc/_static/themes/sphinxdoc.png
Binary files differ
diff --git a/doc/_static/themes/traditional.png b/doc/_static/themes/traditional.png
new file mode 100644
index 0000000..9820fd0
--- /dev/null
+++ b/doc/_static/themes/traditional.png
Binary files differ
diff --git a/doc/_static/translation.png b/doc/_static/translation.png
new file mode 100644
index 0000000..002b3d1
--- /dev/null
+++ b/doc/_static/translation.png
Binary files differ
diff --git a/doc/_static/translation.puml b/doc/_static/translation.puml
new file mode 100644
index 0000000..7b8fc9f
--- /dev/null
+++ b/doc/_static/translation.puml
@@ -0,0 +1,16 @@
+@startuml
+file "SphinxProject"
+file ".rst"
+database ".pot"
+database ".po"
+database ".mo"
+actor translator
+file TranslatedBuild
+translator -l-> .po
+SphinxProject -r-> .rst
+.rst -r-> .pot : sphinx-build gettext
+.pot -r-> .po : Pootle
+.po -d-> .mo : msgfmt
+.mo -l-> TranslatedBuild
+.rst -d-> TranslatedBuild : "sphinx-build -Dlanguage="
+@enduml
diff --git a/doc/_static/translation.svg b/doc/_static/translation.svg
new file mode 100644
index 0000000..4e3ab5a
--- /dev/null
+++ b/doc/_static/translation.svg
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentScriptType="application/ecmascript" contentStyleType="text/css" height="223px" preserveAspectRatio="none" style="width:637px;height:223px;" version="1.1" viewBox="0 0 637 223" width="637px" zoomAndPan="magnify"><defs><filter height="300%" id="fh7abla96c8rb" width="300%" x="-1" y="-1"><feGaussianBlur result="blurOut" stdDeviation="2.0"/><feColorMatrix in="blurOut" result="blurOut2" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .4 0"/><feOffset dx="4.0" dy="4.0" in="blurOut2" result="blurOut3"/><feBlend in="SourceGraphic" in2="blurOut3" mode="normal"/></filter></defs><g><!--MD5=[631d54569d64dd7be7afb1602a233020]
+entity SphinxProject--><polygon fill="#FEFECE" filter="url(#fh7abla96c8rb)" points="6,30.5,6,66.7969,120,66.7969,120,40.5,110,30.5,6,30.5" style="stroke: #000000; stroke-width: 1.5;"/><path d="M110,30.5 L110,40.5 L120,40.5 " fill="#FEFECE" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="94" x="16" y="53.4951">SphinxProject</text><!--MD5=[61096c0d57626e43fed95496d4441932]
+entity .rst--><polygon fill="#FEFECE" filter="url(#fh7abla96c8rb)" points="155,30.5,155,66.7969,197,66.7969,197,40.5,187,30.5,155,30.5" style="stroke: #000000; stroke-width: 1.5;"/><path d="M187,30.5 L187,40.5 L197,40.5 " fill="#FEFECE" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="22" x="165" y="53.4951">.rst</text><!--MD5=[08ed079d9b091f9ed2d220f9f6abc033]
+entity .pot--><path d="M359.5,36 C359.5,26 383,26 383,26 C383,26 406.5,26 406.5,36 L406.5,61.2969 C406.5,71.2969 383,71.2969 383,71.2969 C383,71.2969 359.5,71.2969 359.5,61.2969 L359.5,36 " fill="#FEFECE" filter="url(#fh7abla96c8rb)" style="stroke: #000000; stroke-width: 1.5;"/><path d="M359.5,36 C359.5,46 383,46 383,46 C383,46 406.5,46 406.5,36 " fill="none" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="27" x="369.5" y="62.9951">.pot</text><!--MD5=[66eca29884632d3929c321eae20b9288]
+entity .po--><path d="M483,36 C483,26 504,26 504,26 C504,26 525,26 525,36 L525,61.2969 C525,71.2969 504,71.2969 504,71.2969 C504,71.2969 483,71.2969 483,61.2969 L483,36 " fill="#FEFECE" filter="url(#fh7abla96c8rb)" style="stroke: #000000; stroke-width: 1.5;"/><path d="M483,36 C483,46 504,46 504,46 C504,46 525,46 525,36 " fill="none" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="22" x="493" y="62.9951">.po</text><!--MD5=[fad5092d1b513ed9e4cd2391fb0fb212]
+entity .mo--><path d="M398,176 C398,166 421,166 421,166 C421,166 444,166 444,176 L444,201.2969 C444,211.2969 421,211.2969 421,211.2969 C421,211.2969 398,211.2969 398,201.2969 L398,176 " fill="#FEFECE" filter="url(#fh7abla96c8rb)" style="stroke: #000000; stroke-width: 1.5;"/><path d="M398,176 C398,186 421,186 421,186 C421,186 444,186 444,176 " fill="none" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="26" x="408" y="202.9951">.mo</text><!--MD5=[8f276d451ff344d4b5b89d896332ffcd]
+entity translator--><ellipse cx="593" cy="17.5" fill="#FEFECE" filter="url(#fh7abla96c8rb)" rx="8" ry="8" style="stroke: #A80036; stroke-width: 1.5;"/><path d="M593,25.5 L593,52.5 M580,33.5 L606,33.5 M593,52.5 L580,67.5 M593,52.5 L606,67.5 " fill="none" filter="url(#fh7abla96c8rb)" style="stroke: #A80036; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="65" x="560.5" y="85.9951">translator</text><!--MD5=[ba0f3816bcb6df458d88626e193b44ee]
+entity TranslatedBuild--><polygon fill="#FEFECE" filter="url(#fh7abla96c8rb)" points="214.5,170.5,214.5,206.7969,341.5,206.7969,341.5,180.5,331.5,170.5,214.5,170.5" style="stroke: #000000; stroke-width: 1.5;"/><path d="M331.5,170.5 L331.5,180.5 L341.5,180.5 " fill="#FEFECE" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="107" x="224.5" y="193.4951">TranslatedBuild</text><!--MD5=[2a0f0d8c54238b3eb600ae284aca39d2]
+reverse link .po to translator--><path d="M530.44,48.5 C540.43,48.5 550.43,48.5 560.43,48.5 " fill="none" id=".po&lt;-translator" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="525.21,48.5,534.21,52.5,530.21,48.5,534.21,44.5,525.21,48.5" style="stroke: #A80036; stroke-width: 1.0;"/><!--MD5=[25ad71f3d3609323ec521914d1dc498d]
+link SphinxProject to .rst--><path d="M120.38,48.5 C130.13,48.5 139.87,48.5 149.61,48.5 " fill="none" id="SphinxProject-&gt;.rst" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="154.71,48.5,145.71,44.5,149.71,48.5,145.71,52.5,154.71,48.5" style="stroke: #A80036; stroke-width: 1.0;"/><!--MD5=[1109e8764a7297dc8aca732b1794aa90]
+link .rst to .pot--><path d="M197.37,48.5 C234.72,48.5 311.88,48.5 354,48.5 " fill="none" id=".rst-&gt;.pot" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="359.21,48.5,350.21,44.5,354.21,48.5,350.21,52.5,359.21,48.5" style="stroke: #A80036; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="126" x="215.25" y="41.5669">sphinx-build gettext</text><!--MD5=[c2d0ba229470f335ea07ab2ed6b28ec0]
+link .pot to .po--><path d="M406.62,48.5 C427.03,48.5 456.51,48.5 477.68,48.5 " fill="none" id=".pot-&gt;.po" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="482.87,48.5,473.87,44.5,477.87,48.5,473.87,52.5,482.87,48.5" style="stroke: #A80036; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="40" x="424.75" y="41.5669">Pootle</text><!--MD5=[06651b5914fbf4764a077bbac7efe19a]
+link .po to .mo--><path d="M491.03,71.06 C476.38,95.43 452.52,135.09 436.8,161.24 " fill="none" id=".po-&gt;.mo" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="434.15,165.63,442.2104,159.9705,436.7225,161.3425,435.3505,155.8546,434.15,165.63" style="stroke: #A80036; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="50" x="462" y="132.0669">msgfmt</text><!--MD5=[02fa75427086f2cebad4a5f1b2dd96dd]
+reverse link TranslatedBuild to .mo--><path d="M346.94,188.5 C363.88,188.5 380.82,188.5 397.76,188.5 " fill="none" id="TranslatedBuild&lt;-.mo" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="341.68,188.5,350.68,192.5,346.68,188.5,350.68,184.5,341.68,188.5" style="stroke: #A80036; stroke-width: 1.0;"/><!--MD5=[e72b6258a50343d4926d984a36170cf2]
+link .rst to TranslatedBuild--><path d="M188.71,66.7 C207.27,91.8 241.75,138.46 262,165.86 " fill="none" id=".rst-&gt;TranslatedBuild" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="265.13,170.08,262.9905,160.4663,262.1552,166.0612,256.5604,165.226,265.13,170.08" style="stroke: #A80036; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="165" x="241" y="132.0669">sphinx-build -Dlanguage=</text><!--MD5=[30dba34f254541587149d90abdb00688]
+@startuml
+file "SphinxProject"
+file ".rst"
+database ".pot"
+database ".po"
+database ".mo"
+actor translator
+file TranslatedBuild
+translator -l-> .po
+SphinxProject -r-> .rst
+.rst -r-> .pot : sphinx-build gettext
+.pot -r-> .po : Pootle
+.po -d-> .mo : msgfmt
+.mo -l-> TranslatedBuild
+.rst -d-> TranslatedBuild : "sphinx-build -Dlanguage="
+@enduml
+
+PlantUML version 1.2020.00(Sat Jan 11 12:30:53 GMT 2020)
+(GPL source distribution)
+Java Runtime: OpenJDK Runtime Environment
+JVM: OpenJDK 64-Bit Server VM
+Java Version: 1.8.0_252-b09
+Operating System: Linux
+Default Encoding: UTF-8
+Language: en
+Country: null
+--></g></svg> \ No newline at end of file
diff --git a/doc/_static/tutorial/lumache-autosummary.png b/doc/_static/tutorial/lumache-autosummary.png
new file mode 100644
index 0000000..ed54ea3
--- /dev/null
+++ b/doc/_static/tutorial/lumache-autosummary.png
Binary files differ
diff --git a/doc/_static/tutorial/lumache-first-light.png b/doc/_static/tutorial/lumache-first-light.png
new file mode 100644
index 0000000..fbf4aec
--- /dev/null
+++ b/doc/_static/tutorial/lumache-first-light.png
Binary files differ
diff --git a/doc/_static/tutorial/lumache-furo.png b/doc/_static/tutorial/lumache-furo.png
new file mode 100644
index 0000000..c7aaee7
--- /dev/null
+++ b/doc/_static/tutorial/lumache-furo.png
Binary files differ
diff --git a/doc/_static/tutorial/lumache-py-function-full.png b/doc/_static/tutorial/lumache-py-function-full.png
new file mode 100644
index 0000000..d13b637
--- /dev/null
+++ b/doc/_static/tutorial/lumache-py-function-full.png
Binary files differ
diff --git a/doc/_static/tutorial/lumache-py-function.png b/doc/_static/tutorial/lumache-py-function.png
new file mode 100644
index 0000000..06129d5
--- /dev/null
+++ b/doc/_static/tutorial/lumache-py-function.png
Binary files differ
diff --git a/doc/_templates/contents.html b/doc/_templates/contents.html
new file mode 100644
index 0000000..5eefe4e
--- /dev/null
+++ b/doc/_templates/contents.html
@@ -0,0 +1,8 @@
+{% extends "layout.html" %}
+{% set title = _('Sphinx documentation contents') %}
+{% block body %}
+<h1>{{ _('Sphinx documentation contents') }}</h1>
+<div class="toctree-wrapper compound">
+{{ toctree(includehidden=True, collapse=False, maxdepth=3) }}
+</div>
+{% endblock %}
diff --git a/doc/_themes/sphinx13/layout.html b/doc/_themes/sphinx13/layout.html
new file mode 100644
index 0000000..86a7943
--- /dev/null
+++ b/doc/_themes/sphinx13/layout.html
@@ -0,0 +1,60 @@
+{# Sphinx layout template for the sphinxdoc theme. #}
+{%- extends "basic/layout.html" %}
+
+{% block extrahead %}
+{{ super() }}
+{%- if not embedded and pagename == 'index' %}
+<style>.related { display: none; }</style>
+{%- endif %}
+{% endblock %}
+
+{% block header %}
+<div class="pageheader">
+<a href="{{ pathto('index') }}">
+ <img src="{{ pathto('_static/sphinxheader.png', 1) }}" alt="SPHINX" />
+</a>
+</div>
+{% endblock %}
+
+{%- block relbar1 %}
+<div class="related" role="navigation" aria-label="related navigation">
+ <h3>{{ _('Navigation') }}</h3>
+ <ul>
+ <li><a href="{{ pathto('index') }}">Documentation</a> &raquo;</li>
+ {%- for parent in parents %}
+ <li class="nav-item nav-item-{{ loop.index }}"><a href="{{ parent.link|e }}" {% if loop.last %}{{ accesskey("U") }}{% endif %}>{{ parent.title }}</a>{{ reldelim1 }}</li>
+ {%- endfor %}
+ <li class="nav-item nav-item-this"><a href="{{ link|e }}">{{ title }}</a></li>
+ </ul>
+</div>
+{% endblock %}
+
+{%- block content %}
+<div class="document">
+ <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+ {%- include "searchfield.html" %}
+ <div class="sphinxsidebar-navigation__contents">
+ <h3>{{ _('On this page') }}</h3>
+ {{ toc }}
+ </div>
+ <div class="sphinxsidebar-navigation__pages">
+ <h3>{{ _('Site navigation') }}</h3>
+ {{ toctree(includehidden=True, maxdepth=3, titles_only=True) }}
+ </div>
+ </div>
+ {%- block document %}
+ <div class="body" role="main">
+ {% block body %}{% endblock %}
+ </div>
+ {%- endblock %}
+</div>
+{%- endblock %}
+
+{%- block relbar2 %}{% endblock %}
+
+{%- block footer %}
+<div class="footer" role="contentinfo">
+ {{ copyright_block() }}
+ {% trans sphinx_version=sphinx_version|e %}Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %}
+</div>
+{%- endblock %}
diff --git a/doc/_themes/sphinx13/static/sphinx13.css b/doc/_themes/sphinx13/static/sphinx13.css
new file mode 100644
index 0000000..674d211
--- /dev/null
+++ b/doc/_themes/sphinx13/static/sphinx13.css
@@ -0,0 +1,362 @@
+/* Stylesheet for Sphinx's documentation */
+
+/* Set master colours */
+:root {
+ --fonts-sans-serif: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
+ --colour-sphinx-blue: #0A507A;
+ --colour-text: #333;
+ --colour-links-light: #057;
+}
+
+body {
+ font-family: var(--fonts-sans-serif);
+ margin: 0 auto;
+ color: var(--colour-text);
+}
+
+.pageheader {
+ background-color: var(--colour-sphinx-blue);
+ padding: 10px 15px;
+}
+
+div.document {
+ display: flex;
+ margin: 0 0.5em;
+}
+
+div.body {
+ border-left: 1px solid var(--colour-sphinx-blue);
+ margin: 0;
+ padding: 0.5em 1.75em;
+ min-width: 0;
+ max-width: 800px;
+}
+
+div.related {
+ display: flex;
+ color: white;
+ background-color: var(--colour-sphinx-blue);
+ border-top: 1px solid #002e50;
+}
+
+div.related ul li {
+ margin: 0 5px 0 0;
+ float: left;
+}
+
+div.related ul li a {
+ padding: 0 5px 0 5px;
+ line-height: 1.75em;
+ color: white;
+}
+
+div.related ul li a:hover {
+ text-shadow: 0 0 1px rgba(255, 255, 255, 0.5);
+}
+
+div.sphinxsidebarwrapper {
+ padding: 0;
+}
+
+div.sphinxsidebar {
+ position: sticky;
+ top: 0;
+ align-self: flex-start;
+ height: 100vh;
+ width: 250px;
+ overflow-y: auto;
+ overflow-wrap: break-word;
+ margin: 0;
+ padding-right: 15px;
+ padding-top: 0.5em;
+ font-size: 1em;
+}
+
+div.sphinxsidebar h3 {
+ font-size: 1.5em;
+ margin-top: 0;
+ margin-bottom: 0.5em;
+ padding-top: 0.5em;
+}
+
+div.sphinxsidebar h4 {
+ font-size: 1.2em;
+ margin-bottom: 0;
+}
+
+div.sphinxsidebar h3, div.sphinxsidebar h4 {
+ margin-right: -15px;
+ margin-left: -15px;
+ padding-right: 14px;
+ padding-left: 14px;
+ color: #333;
+ font-weight: 300;
+}
+
+div.sphinxsidebar h3 a {
+ color: #333;
+}
+
+div.sphinxsidebar ul {
+ color: #444;
+ margin-top: 7px;
+ padding: 0;
+ line-height: 130%;
+}
+
+div.sphinxsidebar ul ul {
+ margin-left: 1rem;
+ list-style-type: none;
+ font-size: .9em;
+}
+
+/* De-dent the first list because we hide the top-level item */
+.sphinxsidebar .sphinxsidebar-navigation__contents > ul > li > ul {
+ margin-left: 0;
+}
+
+div.sphinxsidebar p.caption {
+ font-weight: 300;
+ font-size: 1.2rem;
+}
+
+div.sphinxsidebar li.current > a {
+ font-weight: 600;
+}
+
+.sphinxsidebar-navigation__contents > ul > li > a {
+ display: none;
+}
+
+div.sphinxsidebar #searchbox {
+ margin: 12px 0 20px 0;
+}
+
+div.footer {
+ background-color: var(--colour-sphinx-blue);
+ color: #ccc;
+ text-shadow: 0 0 .2px rgba(255, 255, 255, 0.8);
+ padding: 3px 8px 3px 8px;
+ clear: both;
+ font-size: 0.8em;
+}
+
+/* no need to make a visible link to Sphinx on the Sphinx page */
+div.footer a {
+ color: #ccc;
+}
+
+/* -- body styles ----------------------------------------------------------- */
+
+p {
+ margin: 0.8em 0 0.5em 0;
+}
+
+a {
+ color: var(--colour-links-light);
+ text-decoration: none;
+}
+
+div.body a {
+ text-decoration: underline;
+}
+
+h1 {
+ margin: 10px 0 0 0;
+ font-size: 2.4em;
+ color: var(--colour-sphinx-blue);
+ font-weight: 300;
+}
+
+h1 span.pre {
+ /* for code in titles */
+ word-break: break-all;
+ white-space: normal;
+}
+
+h2 {
+ margin: 1em 0 0.2em 0;
+ font-size: 1.5em;
+ font-weight: 300;
+ padding: 0;
+ color: #174967;
+}
+
+h3 {
+ margin: 1em 0 -0.3em 0;
+ font-size: 1.3em;
+ font-weight: 300;
+}
+
+div.body h1 a, div.body h2 a, div.body h3 a, div.body h4 a, div.body h5 a, div.body h6 a {
+ text-decoration: none;
+}
+
+div.body h1 a tt, div.body h2 a tt, div.body h3 a tt, div.body h4 a tt, div.body h5 a tt, div.body h6 a tt {
+ color: var(--colour-sphinx-blue) !important;
+ font-size: inherit !important;
+}
+
+a.headerlink {
+ color: var(--colour-sphinx-blue) !important;
+ font-size: .8em;
+ margin-left: 6px;
+ padding: 0 4px 0 4px;
+ text-decoration: none !important;
+}
+
+a.headerlink:hover {
+ background-color: #ccc;
+ color: white!important;
+}
+
+/* avoid font-size when :mod: role in headings */
+h1 code, h2 code, h3 code, h4 code {
+ font-size: inherit;
+}
+
+cite, code, tt {
+ font-family: 'Consolas', 'DejaVu Sans Mono',
+ 'Bitstream Vera Sans Mono', monospace;
+ font-size: 1em;
+ letter-spacing: -0.02em;
+}
+
+table.deprecated code.literal {
+ word-break: break-all;
+}
+
+tt {
+ background-color: #f2f2f2;
+ border: 1px solid #ddd;
+ border-radius: 2px;
+ color: #333;
+ padding: 1px 0.2em;
+}
+
+tt.descname, tt.descclassname, tt.xref {
+ border: 0;
+}
+
+hr {
+ border: 1px solid #abc;
+ margin: 2em;
+}
+
+a tt {
+ border: 0;
+ color: var(--colour-links-light);
+}
+
+pre {
+ font-family: 'Consolas', 'Courier New', 'DejaVu Sans Mono',
+ 'Bitstream Vera Sans Mono', monospace;
+ font-size: 1em;
+ letter-spacing: 0.015em;
+ line-height: 120%;
+ padding: 0.5em;
+ border: 1px solid #ccc;
+ border-radius: 2px;
+ background-color: #f8f8f8;
+}
+
+pre a {
+ color: inherit;
+ text-decoration: underline;
+}
+
+td.linenos pre {
+ padding: 0.5em 0;
+}
+
+div.quotebar {
+ background-color: #f8f8f8;
+ max-width: 250px;
+ float: right;
+ padding: 0px 7px;
+ border: 1px solid #ccc;
+ margin-left: 1em;
+}
+
+blockquote.epigraph {
+ font-size: 1.5em;
+ padding-left: 1rem;
+ margin-left: 0;
+}
+
+nav.contents,
+div.topic,
+aside.topic {
+ background-color: #f8f8f8;
+}
+
+table {
+ border-collapse: collapse;
+ margin: 0 -0.5em 0 -0.5em;
+}
+
+table td, table th {
+ padding: 0.2em 0.5em 0.2em 0.5em;
+}
+
+div.admonition, div.warning {
+ font-size: 0.9em;
+ margin: 1em 0 1em 0;
+ border: 1px solid #86989B;
+ border-radius: 2px;
+ background-color: #f7f7f7;
+ padding: 1rem;
+}
+
+div.admonition > p, div.warning > p {
+ margin: 0;
+ padding: 0;
+}
+
+div.admonition > pre, div.warning > pre {
+ margin: 0.4em 1em 0.4em 1em;
+}
+
+div.admonition > p.admonition-title,
+div.warning > p.admonition-title {
+ font-weight: bold;
+}
+
+div.warning {
+ border: 1px solid #940000;
+}
+
+div.admonition > ul,
+div.admonition > ol,
+div.warning > ul,
+div.warning > ol {
+ margin: 0.1em 0.5em 0.5em 3em;
+ padding: 0;
+}
+
+div.admonition div.highlight {
+ background: none;
+}
+
+.viewcode-back {
+ font-family: var(--fonts-sans-serif);
+}
+
+div.viewcode-block:target {
+ background-color: #f4debf;
+ border-top: 1px solid #ac9;
+ border-bottom: 1px solid #ac9;
+}
+
+
+/* media queries */
+
+/* Reduce padding & margins for smaller screens */
+@media (max-width: 750px) {
+ .sphinxsidebar {
+ display: none;
+ }
+ div.body {
+ border-left: none;
+ }
+}
diff --git a/doc/_themes/sphinx13/static/sphinxheader.png b/doc/_themes/sphinx13/static/sphinxheader.png
new file mode 100644
index 0000000..845da4a
--- /dev/null
+++ b/doc/_themes/sphinx13/static/sphinxheader.png
Binary files differ
diff --git a/doc/_themes/sphinx13/theme.conf b/doc/_themes/sphinx13/theme.conf
new file mode 100644
index 0000000..78bb78f
--- /dev/null
+++ b/doc/_themes/sphinx13/theme.conf
@@ -0,0 +1,4 @@
+[theme]
+inherit = basic
+pygments_style = default
+sidebars =
diff --git a/doc/authors.rst b/doc/authors.rst
new file mode 100644
index 0000000..411835b
--- /dev/null
+++ b/doc/authors.rst
@@ -0,0 +1,9 @@
+:tocdepth: 2
+
+.. _authors:
+
+==============
+Sphinx authors
+==============
+
+.. include:: ../AUTHORS
diff --git a/doc/changes.rst b/doc/changes.rst
new file mode 100644
index 0000000..96853fe
--- /dev/null
+++ b/doc/changes.rst
@@ -0,0 +1,22 @@
+:tocdepth: 1
+
+.. default-role:: any
+
+.. _changes:
+
+=========
+Changelog
+=========
+
+.. raw:: latex
+
+ \addtocontents{toc}{\protect\setcounter{tocdepth}{1}}%
+ \makeatletter
+ \addtocontents{toc}%
+ {\def\string\l@section{\string\@dottedtocline{1}{1.5em}{3.3em}}}
+ \addtocontents{toc}%
+ {\def\string\l@subsection{\string\@dottedtocline{2}{4.8em}{4em}}}
+ \makeatother
+
+
+.. include:: ../CHANGES
diff --git a/doc/conf.py b/doc/conf.py
new file mode 100644
index 0000000..d4915aa
--- /dev/null
+++ b/doc/conf.py
@@ -0,0 +1,244 @@
+# Sphinx documentation build configuration file
+
+import os
+import re
+import time
+
+import sphinx
+
+os.environ['SPHINX_AUTODOC_RELOAD_MODULES'] = '1'
+
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo',
+ 'sphinx.ext.autosummary', 'sphinx.ext.extlinks',
+ 'sphinx.ext.intersphinx',
+ 'sphinx.ext.viewcode', 'sphinx.ext.inheritance_diagram',
+ 'sphinx.ext.coverage']
+coverage_statistics_to_report = coverage_statistics_to_stdout = True
+templates_path = ['_templates']
+exclude_patterns = ['_build']
+
+project = 'Sphinx'
+copyright = f'2007-{time.strftime("%Y")}, the Sphinx developers'
+version = sphinx.__display_version__
+release = version
+show_authors = True
+
+html_theme = 'sphinx13'
+html_theme_path = ['_themes']
+html_css_files = [
+ # 'basic.css', # included through inheritance from the basic theme
+ 'sphinx13.css',
+]
+modindex_common_prefix = ['sphinx.']
+html_static_path = ['_static']
+html_title = 'Sphinx documentation'
+html_additional_pages = {'contents': 'contents.html'}
+html_use_opensearch = 'https://www.sphinx-doc.org/en/master'
+html_baseurl = 'https://www.sphinx-doc.org/en/master/'
+html_favicon = '_static/favicon.svg'
+
+htmlhelp_basename = 'Sphinxdoc'
+
+epub_theme = 'epub'
+epub_basename = 'sphinx'
+epub_author = 'the Sphinx developers'
+epub_publisher = 'https://www.sphinx-doc.org/'
+epub_uid = 'web-site'
+epub_scheme = 'url'
+epub_identifier = epub_publisher
+epub_pre_files = [('index.xhtml', 'Welcome')]
+epub_post_files = [('usage/installation.xhtml', 'Installing Sphinx'),
+ ('develop.xhtml', 'Sphinx development')]
+epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js',
+ '_static/searchtools.js',
+ '_static/sphinx_highlight.js',
+ '_static/basic.css',
+ '_static/language_data.js',
+ 'search.html', '_static/websupport.js']
+epub_fix_images = False
+epub_max_image_width = 0
+epub_show_urls = 'inline'
+epub_use_index = False
+epub_description = 'Sphinx documentation generator system manual'
+
+latex_documents = [('index', 'sphinx.tex', 'Sphinx Documentation',
+ 'the Sphinx developers', 'manual', 1)]
+latex_logo = '_static/sphinx.png'
+latex_elements = {
+ 'fontenc': r'\usepackage[LGR,X2,T1]{fontenc}',
+ 'passoptionstopackages': r'''
+\PassOptionsToPackage{svgnames}{xcolor}
+''',
+ 'preamble': r'''
+\DeclareUnicodeCharacter{229E}{\ensuremath{\boxplus}}
+\setcounter{tocdepth}{3}% depth of what main TOC shows (3=subsubsection)
+\setcounter{secnumdepth}{1}% depth of section numbering
+\setlength{\tymin}{2cm}% avoid too cramped table columns
+''',
+ # fix missing index entry due to RTD doing only once pdflatex after makeindex
+ 'printindex': r'''
+\IfFileExists{\jobname.ind}
+ {\footnotesize\raggedright\printindex}
+ {\begin{sphinxtheindex}\end{sphinxtheindex}}
+''',
+}
+latex_show_urls = 'footnote'
+latex_use_xindy = True
+
+linkcheck_timeout = 5
+
+autodoc_member_order = 'groupwise'
+autosummary_generate = False
+todo_include_todos = True
+extlinks = {'duref': ('https://docutils.sourceforge.io/docs/ref/rst/'
+ 'restructuredtext.html#%s', '%s'),
+ 'durole': ('https://docutils.sourceforge.io/docs/ref/rst/'
+ 'roles.html#%s', '%s'),
+ 'dudir': ('https://docutils.sourceforge.io/docs/ref/rst/'
+ 'directives.html#%s', '%s')}
+
+man_pages = [
+ ('index', 'sphinx-all', 'Sphinx documentation generator system manual',
+ 'the Sphinx developers', 1),
+ ('man/sphinx-build', 'sphinx-build', 'Sphinx documentation generator tool',
+ '', 1),
+ ('man/sphinx-quickstart', 'sphinx-quickstart', 'Sphinx documentation '
+ 'template generator', '', 1),
+ ('man/sphinx-apidoc', 'sphinx-apidoc', 'Sphinx API doc generator tool',
+ '', 1),
+ ('man/sphinx-autogen', 'sphinx-autogen', 'Generate autodoc stub pages',
+ '', 1),
+]
+
+texinfo_documents = [
+ ('index', 'sphinx', 'Sphinx Documentation', 'the Sphinx developers',
+ 'Sphinx', 'The Sphinx documentation builder.', 'Documentation tools',
+ 1),
+]
+
+intersphinx_mapping = {
+ 'python': ('https://docs.python.org/3/', None),
+ 'requests': ('https://requests.readthedocs.io/en/latest/', None),
+ 'readthedocs': ('https://docs.readthedocs.io/en/stable', None),
+}
+
+# Sphinx document translation with sphinx gettext feature uses these settings:
+locale_dirs = ['locale/']
+gettext_compact = False
+
+nitpick_ignore = {
+ ('cpp:class', 'template<typename TOuter> template<typename TInner> Wrapper::Outer<TOuter>::Inner'), # NoQA: E501
+ ('cpp:identifier', 'MyContainer'),
+ ('js:func', 'SomeError'),
+ ('js:func', 'number'),
+ ('js:func', 'string'),
+ ('py:attr', 'srcline'),
+ ('py:class', 'Element'), # sphinx.domains.Domain
+ ('py:class', 'IndexEntry'), # sphinx.domains.IndexEntry
+ ('py:class', 'Node'), # sphinx.domains.Domain
+ ('py:class', 'NullTranslations'), # gettext.NullTranslations
+ ('py:class', 'RoleFunction'), # sphinx.domains.Domain
+ ('py:class', 'Theme'), # sphinx.application.TemplateBridge
+ ('py:class', 'TitleGetter'), # sphinx.domains.Domain
+ ('py:class', 'XRefRole'), # sphinx.domains.Domain
+ ('py:class', 'docutils.nodes.Element'),
+ ('py:class', 'docutils.nodes.Node'),
+ ('py:class', 'docutils.nodes.NodeVisitor'),
+ ('py:class', 'docutils.nodes.TextElement'),
+ ('py:class', 'docutils.nodes.document'),
+ ('py:class', 'docutils.nodes.system_message'),
+ ('py:class', 'docutils.parsers.Parser'),
+ ('py:class', 'docutils.parsers.rst.states.Inliner'),
+ ('py:class', 'docutils.transforms.Transform'),
+ ('py:class', 'nodes.NodeVisitor'),
+ ('py:class', 'nodes.document'),
+ ('py:class', 'nodes.reference'),
+ ('py:class', 'pygments.lexer.Lexer'),
+ ('py:class', 'sphinx.directives.ObjDescT'),
+ ('py:class', 'sphinx.domains.IndexEntry'),
+ ('py:class', 'sphinx.ext.autodoc.Documenter'),
+ ('py:class', 'sphinx.errors.NoUri'),
+ ('py:class', 'sphinx.roles.XRefRole'),
+ ('py:class', 'sphinx.search.SearchLanguage'),
+ ('py:class', 'sphinx.theming.Theme'),
+ ('py:class', 'sphinxcontrib.websupport.errors.DocumentNotFoundError'),
+ ('py:class', 'sphinxcontrib.websupport.errors.UserNotAuthorizedError'),
+ ('py:exc', 'docutils.nodes.SkipNode'),
+ ('py:exc', 'sphinx.environment.NoUri'),
+ ('py:func', 'setup'),
+ ('py:func', 'sphinx.util.nodes.nested_parse_with_titles'),
+ # Error in sphinxcontrib.websupport.core::WebSupport.add_comment
+ ('py:meth', 'get_comments'),
+ ('py:mod', 'autodoc'),
+ ('py:mod', 'docutils.nodes'),
+ ('py:mod', 'docutils.parsers.rst.directives'),
+ ('py:mod', 'sphinx.ext'),
+ ('py:obj', 'sphinx.util.relative_uri'),
+ ('rst:role', 'c:any'),
+ ('std:confval', 'autodoc_inherit_docstring'),
+ ('std:confval', 'automodule_skip_lines'),
+ ('std:confval', 'autossummary_imported_members'),
+ ('std:confval', 'gettext_language_team'),
+ ('std:confval', 'gettext_last_translator'),
+ ('std:confval', 'globaltoc_collapse'),
+ ('std:confval', 'globaltoc_includehidden'),
+ ('std:confval', 'globaltoc_maxdepth'),
+}
+
+
+# -- Extension interface -------------------------------------------------------
+
+from sphinx import addnodes # noqa: E402
+
+event_sig_re = re.compile(r'([a-zA-Z-]+)\s*\((.*)\)')
+
+
+def parse_event(env, sig, signode):
+ m = event_sig_re.match(sig)
+ if not m:
+ signode += addnodes.desc_name(sig, sig)
+ return sig
+ name, args = m.groups()
+ signode += addnodes.desc_name(name, name)
+ plist = addnodes.desc_parameterlist()
+ for arg in args.split(','):
+ arg = arg.strip()
+ plist += addnodes.desc_parameter(arg, arg)
+ signode += plist
+ return name
+
+
+def linkify_issues_in_changelog(app, docname, source):
+ """ Linkify issue references like #123 in changelog to GitHub. """
+
+ if docname == 'changes':
+ changelog_path = os.path.join(os.path.dirname(__file__), "../CHANGES")
+ # this path trickery is needed because this script can
+ # be invoked with different working directories:
+ # * running make in docs/
+ # * running tox -e docs in the repo root dir
+
+ with open(changelog_path, encoding="utf-8") as f:
+ changelog = f.read()
+
+ def linkify(match):
+ url = 'https://github.com/sphinx-doc/sphinx/issues/' + match[1]
+ return f'`{match[0]} <{url}>`_'
+
+ linkified_changelog = re.sub(r'(?:PR)?#([0-9]+)\b', linkify, changelog)
+
+ source[0] = source[0].replace('.. include:: ../CHANGES', linkified_changelog)
+
+
+def setup(app):
+ from sphinx.ext.autodoc import cut_lines
+ from sphinx.util.docfields import GroupedField
+ app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
+ app.connect('source-read', linkify_issues_in_changelog)
+ app.add_object_type('confval', 'confval',
+ objname='configuration value',
+ indextemplate='pair: %s; configuration value')
+ fdesc = GroupedField('parameter', label='Parameters',
+ names=['param'], can_collapse=True)
+ app.add_object_type('event', 'event', 'pair: %s; event', parse_event,
+ doc_field_types=[fdesc])
diff --git a/doc/development/builders.rst b/doc/development/builders.rst
new file mode 100644
index 0000000..bb67770
--- /dev/null
+++ b/doc/development/builders.rst
@@ -0,0 +1,34 @@
+Configuring builders
+====================
+
+Discover builders by entry point
+--------------------------------
+
+.. versionadded:: 1.6
+
+:term:`builder` extensions can be discovered by means of `entry points`_ so
+that they do not have to be listed in the :confval:`extensions` configuration
+value.
+
+Builder extensions should define an entry point in the ``sphinx.builders``
+group. The name of the entry point needs to match your builder's
+:attr:`~.Builder.name` attribute, which is the name passed to the
+:option:`sphinx-build -b` option. The entry point value should equal the
+dotted name of the extension module. Here is an example of how an entry point
+for 'mybuilder' can be defined in the extension's ``setup.py``
+
+.. code-block:: python
+
+ setup(
+ # ...
+ entry_points={
+ 'sphinx.builders': [
+ 'mybuilder = my.extension.module',
+ ],
+ }
+ )
+
+Note that it is still necessary to register the builder using
+:meth:`~.Sphinx.add_builder` in the extension's :func:`setup` function.
+
+.. _entry points: https://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins
diff --git a/doc/development/index.rst b/doc/development/index.rst
new file mode 100644
index 0000000..55a31a0
--- /dev/null
+++ b/doc/development/index.rst
@@ -0,0 +1,24 @@
+=========================
+Writing Sphinx Extensions
+=========================
+
+This guide is aimed at giving a quick introduction for those wishing to
+develop their own extensions for Sphinx. Sphinx possesses significant
+extensibility capabilities including the ability to hook into almost every
+point of the build process. If you simply wish to use Sphinx with existing
+extensions, refer to :doc:`/usage/index`. For a more detailed discussion of
+the extension interface see :doc:`/extdev/index`.
+
+.. toctree::
+ :maxdepth: 2
+
+ overview
+ tutorials/index
+ builders
+
+.. toctree::
+ :caption: Theming
+ :maxdepth: 2
+
+ templating
+ theming
diff --git a/doc/development/overview.rst b/doc/development/overview.rst
new file mode 100644
index 0000000..df8f5bb
--- /dev/null
+++ b/doc/development/overview.rst
@@ -0,0 +1,32 @@
+Developing extensions overview
+==============================
+
+This page contains general information about developing Sphinx extensions.
+
+Make an extension depend on another extension
+---------------------------------------------
+
+Sometimes your extension depends on the functionality of another
+Sphinx extension. Most Sphinx extensions are activated in a
+project's :file:`conf.py` file, but this is not available to you as an
+extension developer.
+
+.. module:: sphinx.application
+ :no-index:
+
+To ensure that another extension is activated as a part of your own extension,
+use the :meth:`sphinx.application.Sphinx.setup_extension` method. This will
+activate another extension at run-time, ensuring that you have access to its
+functionality.
+
+For example, the following code activates the ``recommonmark`` extension:
+
+.. code-block:: python
+
+ def setup(app):
+ app.setup_extension("recommonmark")
+
+.. note::
+
+ Since your extension will depend on another, make sure to include
+ it as a part of your extension's installation requirements.
diff --git a/doc/development/templating.rst b/doc/development/templating.rst
new file mode 100644
index 0000000..73ae6e5
--- /dev/null
+++ b/doc/development/templating.rst
@@ -0,0 +1,478 @@
+.. highlight:: html+jinja
+
+.. _templating:
+
+==========
+Templating
+==========
+
+Sphinx uses the `Jinja <https://jinja.palletsprojects.com/>`_ templating engine
+for its HTML templates. Jinja is a text-based engine, inspired by Django
+templates, so anyone having used Django will already be familiar with it. It
+also has excellent documentation for those who need to make themselves familiar
+with it.
+
+
+Do I need to use Sphinx's templates to produce HTML?
+----------------------------------------------------
+
+No. You have several other options:
+
+* You can write a :class:`~sphinx.application.TemplateBridge` subclass that
+ calls your template engine of choice, and set the :confval:`template_bridge`
+ configuration value accordingly.
+
+* You can :ref:`write a custom builder <writing-builders>` that derives from
+ :class:`~sphinx.builders.html.StandaloneHTMLBuilder` and calls your template
+ engine of choice.
+
+* You can use the :class:`~sphinxcontrib.serializinghtml.PickleHTMLBuilder` that
+ produces pickle files with the page contents, and postprocess them using a
+ custom tool, or use them in your Web application.
+
+
+Jinja/Sphinx Templating Primer
+------------------------------
+
+The default templating language in Sphinx is Jinja. It's Django/Smarty inspired
+and easy to understand. The most important concept in Jinja is :dfn:`template
+inheritance`, which means that you can overwrite only specific blocks within a
+template, customizing it while also keeping the changes at a minimum.
+
+To customize the output of your documentation you can override all the templates
+(both the layout templates and the child templates) by adding files with the
+same name as the original filename into the template directory of the structure
+the Sphinx quickstart generated for you.
+
+Sphinx will look for templates in the folders of :confval:`templates_path`
+first, and if it can't find the template it's looking for there, it falls back
+to the selected theme's templates.
+
+A template contains **variables**, which are replaced with values when the
+template is evaluated, **tags**, which control the logic of the template and
+**blocks** which are used for template inheritance.
+
+Sphinx's *basic* theme provides base templates with a couple of blocks it will
+fill with data. These are located in the :file:`themes/basic` subdirectory of
+the Sphinx installation directory, and used by all builtin Sphinx themes.
+Templates with the same name in the :confval:`templates_path` override templates
+supplied by the selected theme.
+
+For example, to add a new link to the template area containing related links all
+you have to do is to add a new template called ``layout.html`` with the
+following contents::
+
+ {% extends "!layout.html" %}
+ {% block rootrellink %}
+ <li><a href="https://project.invalid/">Project Homepage</a> &raquo;</li>
+ {{ super() }}
+ {% endblock %}
+
+By prefixing the name of the overridden template with an exclamation mark,
+Sphinx will load the layout template from the underlying HTML theme.
+
+.. important::
+ If you override a block, call ``{{ super() }}`` somewhere to render the
+ block's original content in the extended template -- unless you don't want
+ that content to show up.
+
+
+Working with the builtin templates
+----------------------------------
+
+The builtin **basic** theme supplies the templates that all builtin Sphinx
+themes are based on. It has the following elements you can override or use:
+
+Blocks
+~~~~~~
+
+The following blocks exist in the ``layout.html`` template:
+
+``doctype``
+ The doctype of the output format. By default this is XHTML 1.0 Transitional
+ as this is the closest to what Sphinx and Docutils generate and it's a good
+ idea not to change it unless you want to switch to HTML 5 or a different but
+ compatible XHTML doctype.
+
+``linktags``
+ This block adds a couple of ``<link>`` tags to the head section of the
+ template.
+
+``extrahead``
+ This block is empty by default and can be used to add extra contents into
+ the ``<head>`` tag of the generated HTML file. This is the right place to
+ add references to JavaScript or extra CSS files.
+
+``relbar1``, ``relbar2``
+ This block contains the *relation bar*, the list of related links (the
+ parent documents on the left, and the links to index, modules etc. on the
+ right). ``relbar1`` appears before the document, ``relbar2`` after the
+ document. By default, both blocks are filled; to show the relbar only
+ before the document, you would override `relbar2` like this::
+
+ {% block relbar2 %}{% endblock %}
+
+``rootrellink``, ``relbaritems``
+ Inside the relbar there are three sections: The ``rootrellink``, the links
+ from the documentation and the custom ``relbaritems``. The ``rootrellink``
+ is a block that by default contains a list item pointing to the root
+ document by default, the ``relbaritems`` is an empty block. If you
+ override them to add extra links into the bar make sure that they are list
+ items and end with the :data:`reldelim1`.
+
+``document``
+ The contents of the document itself. It contains the block "body" where
+ the individual content is put by subtemplates like ``page.html``.
+
+ .. note::
+ In order for the built-in JavaScript search to show a page preview on
+ the results page, the document or body content should be wrapped in an
+ HTML element containing the ``role="main"`` attribute. For example::
+
+ <div role="main">
+ {% block document %}{% endblock %}
+ </div>
+
+``sidebar1``, ``sidebar2``
+ A possible location for a sidebar. ``sidebar1`` appears before the document
+ and is empty by default, ``sidebar2`` after the document and contains the
+ default sidebar. If you want to swap the sidebar location override this and
+ call the ``sidebar`` helper::
+
+ {% block sidebar1 %}{{ sidebar() }}{% endblock %}
+ {% block sidebar2 %}{% endblock %}
+
+ (The ``sidebar2`` location for the sidebar is needed by the ``sphinxdoc.css``
+ stylesheet, for example.)
+
+``sidebarlogo``
+ The logo location within the sidebar. Override this if you want to place
+ some content at the top of the sidebar.
+
+``footer``
+ The block for the footer div. If you want a custom footer or markup before
+ or after it, override this one.
+
+The following four blocks are *only* used for pages that do not have assigned a
+list of custom sidebars in the :confval:`html_sidebars` config value. Their use
+is deprecated in favor of separate sidebar templates, which can be included via
+:confval:`html_sidebars`.
+
+``sidebartoc``
+ The table of contents within the sidebar.
+
+ .. deprecated:: 1.0
+
+``sidebarrel``
+ The relation links (previous, next document) within the sidebar.
+
+ .. deprecated:: 1.0
+
+``sidebarsourcelink``
+ The "Show source" link within the sidebar (normally only shown if this is
+ enabled by :confval:`html_show_sourcelink`).
+
+ .. deprecated:: 1.0
+
+``sidebarsearch``
+ The search box within the sidebar. Override this if you want to place some
+ content at the bottom of the sidebar.
+
+ .. deprecated:: 1.0
+
+
+Configuration Variables
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Inside templates you can set a couple of variables used by the layout template
+using the ``{% set %}`` tag:
+
+.. data:: reldelim1
+
+ The delimiter for the items on the left side of the related bar. This
+ defaults to ``' &raquo;'`` Each item in the related bar ends with the value
+ of this variable.
+
+.. data:: reldelim2
+
+ The delimiter for the items on the right side of the related bar. This
+ defaults to ``' |'``. Each item except of the last one in the related bar
+ ends with the value of this variable.
+
+Overriding works like this::
+
+ {% extends "!layout.html" %}
+ {% set reldelim1 = ' &gt;' %}
+
+.. data:: script_files
+
+ Add additional script files here, like this::
+
+ {% set script_files = script_files + ["_static/myscript.js"] %}
+
+ .. deprecated:: 1.8.0
+
+ Please use ``.Sphinx.add_js_file()`` instead.
+
+Helper Functions
+~~~~~~~~~~~~~~~~
+
+Sphinx provides various Jinja functions as helpers in the template. You can use
+them to generate links or output multiply used elements.
+
+.. function:: pathto(document)
+
+ Return the path to a Sphinx document as a URL. Use this to refer to built
+ documents.
+
+.. function:: pathto(file, 1)
+ :no-index:
+
+ Return the path to a *file* which is a filename relative to the root of the
+ generated output. Use this to refer to static files.
+
+.. function:: hasdoc(document)
+
+ Check if a document with the name *document* exists.
+
+.. function:: sidebar()
+
+ Return the rendered sidebar.
+
+.. function:: relbar()
+
+ Return the rendered relation bar.
+
+.. function:: warning(message)
+
+ Emit a warning message.
+
+Global Variables
+~~~~~~~~~~~~~~~~
+
+These global variables are available in every template and are safe to use.
+There are more, but most of them are an implementation detail and might change
+in the future.
+
+.. data:: builder
+
+ The name of the builder (e.g. ``html`` or ``htmlhelp``).
+
+.. data:: copyright
+
+ The value of :confval:`copyright`.
+
+.. data:: docstitle
+
+ The title of the documentation (the value of :confval:`html_title`), except
+ when the "single-file" builder is used, when it is set to ``None``.
+
+.. data:: embedded
+
+ True if the built HTML is meant to be embedded in some viewing application
+ that handles navigation, not the web browser, such as for HTML help or Qt
+ help formats. In this case, the sidebar is not included.
+
+.. data:: favicon_url
+
+ The relative path to the HTML favicon image from the current document, or
+ URL to the favicon, or ``''``.
+
+ .. versionadded:: 4.0
+
+.. data:: file_suffix
+
+ The value of the builder's :attr:`~.SerializingHTMLBuilder.out_suffix`
+ attribute, i.e. the file name extension that the output files will get. For
+ a standard HTML builder, this is usually ``.html``.
+
+.. data:: has_source
+
+ True if the reST document sources are copied (if :confval:`html_copy_source`
+ is ``True``).
+
+.. data:: language
+
+ The value of :confval:`language`.
+
+.. data:: last_updated
+
+ The build date.
+
+.. data:: logo_url
+
+ The relative path to the HTML logo image from the current document, or URL
+ to the logo, or ``''``.
+
+ .. versionadded:: 4.0
+
+.. data:: master_doc
+
+ Same as :data:`root_doc`.
+
+ .. versionchanged:: 4.0
+
+ Renamed to ``root_doc``.
+
+.. data:: root_doc
+
+ The value of :confval:`root_doc`, for usage with :func:`pathto`.
+
+ .. versionchanged:: 4.0
+
+ Renamed from ``master_doc``.
+
+.. data:: pagename
+
+ The "page name" of the current file, i.e. either the document name if the
+ file is generated from a reST source, or the equivalent hierarchical name
+ relative to the output directory
+ (``[directory/]filename_without_extension``).
+
+.. data:: project
+
+ The value of :confval:`project`.
+
+.. data:: release
+
+ The value of :confval:`release`.
+
+.. data:: rellinks
+
+ A list of links to put at the left side of the relbar, next to "next" and
+ "prev". This usually contains links to the general index and other indices,
+ such as the Python module index. If you add something yourself, it must be a
+ tuple ``(pagename, link title, accesskey, link text)``.
+
+.. data:: shorttitle
+
+ The value of :confval:`html_short_title`.
+
+.. data:: show_source
+
+ True if :confval:`html_show_sourcelink` is ``True``.
+
+.. data:: sphinx_version
+
+ The version of Sphinx used to build represented as a string for example "3.5.1".
+
+.. data:: sphinx_version_tuple
+
+ The version of Sphinx used to build represented as a tuple of five elements.
+ For Sphinx version 3.5.1 beta 3 this would be ``(3, 5, 1, 'beta', 3)``.
+ The fourth element can be one of: ``alpha``, ``beta``, ``rc``, ``final``.
+ ``final`` always has 0 as the last element.
+
+ .. versionadded:: 4.2
+
+.. data:: docutils_version_info
+
+ The version of Docutils used to build represented as a tuple of five elements.
+ For Docutils version 0.16.1 beta 2 this would be ``(0, 16, 1, 'beta', 2)``.
+ The fourth element can be one of: ``alpha``, ``beta``, ``candidate``, ``final``.
+ ``final`` always has 0 as the last element.
+
+ .. versionadded:: 5.0.2
+
+.. data:: styles
+
+ A list of the names of the main stylesheets as given by the theme or
+ :confval:`html_style`.
+
+ .. versionadded:: 5.1
+
+.. data:: title
+
+ The title of the current document, as used in the ``<title>`` tag.
+
+.. data:: use_opensearch
+
+ The value of :confval:`html_use_opensearch`.
+
+.. data:: version
+
+ The value of :confval:`version`.
+
+
+In addition to these values, there are also all **theme options** available
+(prefixed by ``theme_``), as well as the values given by the user in
+:confval:`html_context`.
+
+In documents that are created from source files (as opposed to
+automatically-generated files like the module index, or documents that already
+are in HTML form), these variables are also available:
+
+.. data:: body
+
+ A string containing the content of the page in HTML form as produced by the
+ HTML builder, before the theme is applied.
+
+.. data:: display_toc
+
+ A boolean that is True if the toc contains more than one entry.
+
+.. data:: meta
+
+ Document metadata (a dictionary), see :ref:`metadata`.
+
+.. data:: metatags
+
+ A string containing the page's HTML :dudir:`meta` tags.
+
+.. data:: next
+
+ The next document for the navigation. This variable is either false or has
+ two attributes `link` and `title`. The title contains HTML markup. For
+ example, to generate a link to the next page, you can use this snippet::
+
+ {% if next %}
+ <a href="{{ next.link|e }}">{{ next.title }}</a>
+ {% endif %}
+
+.. data:: page_source_suffix
+
+ The suffix of the file that was rendered. Since we support a list of
+ :confval:`source_suffix`, this will allow you to properly link to the
+ original source file.
+
+.. data:: parents
+
+ A list of parent documents for navigation, structured like the :data:`next`
+ item.
+
+.. data:: prev
+
+ Like :data:`next`, but for the previous page.
+
+.. data:: sourcename
+
+ The name of the copied source file for the current document. This is only
+ nonempty if the :confval:`html_copy_source` value is ``True``.
+ This has empty value on creating automatically-generated files.
+
+.. data:: toc
+
+ The local table of contents for the current page, rendered as HTML bullet
+ lists.
+
+.. data:: toctree
+
+ A callable yielding the global TOC tree containing the current page, rendered
+ as HTML bullet lists. Optional keyword arguments:
+
+ ``collapse``
+ If true, all TOC entries that are not ancestors of the current page are
+ collapsed.
+ ``True`` by default.
+
+ ``maxdepth``
+ The maximum depth of the tree. Set it to ``-1`` to allow unlimited depth.
+ Defaults to the max depth selected in the toctree directive.
+
+ ``titles_only``
+ If true, put only top-level document titles in the tree.
+ ``False`` by default.
+
+ ``includehidden``
+ If true, the ToC tree will also contain hidden entries.
+ ``False`` by default.
diff --git a/doc/development/theming.rst b/doc/development/theming.rst
new file mode 100644
index 0000000..538dcaf
--- /dev/null
+++ b/doc/development/theming.rst
@@ -0,0 +1,342 @@
+HTML theme development
+======================
+
+.. versionadded:: 0.6
+
+.. note::
+
+ This document provides information about creating your own theme. If you
+ simply wish to use a pre-existing HTML themes, refer to
+ :doc:`/usage/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.
+
+.. note::
+
+ See :ref:`dev-extensions` for more information that may
+ be helpful in developing themes.
+
+
+Creating themes
+---------------
+
+Themes take the form of either a directory or a zipfile (whose name is the
+theme name), containing the following:
+
+* A :file:`theme.conf` file.
+* HTML templates, if needed.
+* A ``static/`` directory containing any static files that will be copied to the
+ output static directory on build. These can be images, styles, script files.
+
+The :file:`theme.conf` file is in INI format [1]_ (readable by the standard
+Python :mod:`configparser` module) and has the following structure:
+
+.. sourcecode:: ini
+
+ [theme]
+ inherit = base theme
+ stylesheet = main CSS name
+ pygments_style = stylename
+ sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html
+
+ [options]
+ variable = default value
+
+* The **inherit** setting gives the name of a "base theme", or ``none``. The
+ base theme will be used to locate missing templates (most themes will not have
+ to supply most templates if they use ``basic`` as the base theme), its options
+ will be inherited, and all of its static files will be used as well. If you
+ want to also inherit the stylesheet, include it via CSS' ``@import`` in your
+ own.
+
+* The **stylesheet** setting gives a list of CSS filenames separated commas which
+ will be referenced in the HTML header. You can also use CSS' ``@import``
+ technique to include one from the other, or use a custom HTML template that
+ adds ``<link rel="stylesheet">`` tags as necessary. Setting the
+ :confval:`html_style` config value will override this setting.
+
+* The **pygments_style** setting gives the name of a Pygments style to use for
+ highlighting. This can be overridden by the user in the
+ :confval:`pygments_style` config value.
+
+* The **pygments_dark_style** setting gives the name of a Pygments style to use
+ for highlighting when the CSS media query ``(prefers-color-scheme: dark)``
+ evaluates to true. It is injected into the page using
+ :meth:`~sphinx.application.Sphinx.add_css_file()`.
+
+* The **sidebars** setting gives the comma separated list of sidebar templates
+ for constructing sidebars. This can be overridden by the user in the
+ :confval:`html_sidebars` config value.
+
+* The **options** section contains pairs of variable names and default values.
+ These options can be overridden by the user in :confval:`html_theme_options`
+ and are accessible from all templates as ``theme_<name>``.
+
+.. versionadded:: 1.7
+ sidebar settings
+
+.. versionchanged:: 5.1
+
+ The stylesheet setting accepts multiple CSS filenames
+
+.. _distribute-your-theme:
+
+Distribute your theme as a Python package
+-----------------------------------------
+
+As a way to distribute your theme, you can use a Python package. This makes it
+easier for users to set up your theme.
+
+To distribute your theme as a Python package, please define an entry point
+called ``sphinx.html_themes`` in your ``setup.py`` file, and write a ``setup()``
+function to register your themes using ``add_html_theme()`` API in it::
+
+ # 'setup.py'
+ setup(
+ ...
+ entry_points = {
+ 'sphinx.html_themes': [
+ 'name_of_theme = your_package',
+ ]
+ },
+ ...
+ )
+
+ # 'your_package.py'
+ from os import path
+
+ def setup(app):
+ app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__)))
+
+If your theme package contains two or more themes, please call
+``add_html_theme()`` twice or more.
+
+.. versionadded:: 1.2
+ 'sphinx_themes' entry_points feature.
+
+.. deprecated:: 1.6
+ ``sphinx_themes`` entry_points has been deprecated.
+
+.. versionadded:: 1.6
+ ``sphinx.html_themes`` entry_points feature.
+
+
+Templating
+----------
+
+The :doc:`guide to templating <templating>` is helpful if you want to write your
+own templates. What is important to keep in mind is the order in which Sphinx
+searches for templates:
+
+* First, in the user's ``templates_path`` directories.
+* Then, in the selected theme.
+* Then, in its base theme, its base's base theme, etc.
+
+When extending a template in the base theme with the same name, use the theme
+name as an explicit directory: ``{% extends "basic/layout.html" %}``. From a
+user ``templates_path`` template, you can still use the "exclamation mark"
+syntax as described in the templating document.
+
+
+.. _theming-static-templates:
+
+Static templates
+~~~~~~~~~~~~~~~~
+
+Since theme options are meant for the user to configure a theme more easily,
+without having to write a custom stylesheet, it is necessary to be able to
+template static files as well as HTML files. Therefore, Sphinx supports
+so-called "static templates", like this:
+
+If the name of a file in the ``static/`` directory of a theme (or in the user's
+static path, for that matter) ends with ``_t``, it will be processed by the
+template engine. The ``_t`` will be left from the final file name. For
+example, the *classic* theme has a file ``static/classic.css_t`` which uses
+templating to put the color options into the stylesheet. When a documentation
+project is built with the classic theme, the output directory will contain a
+``_static/classic.css`` file where all template tags have been processed.
+
+
+Use custom page metadata in HTML templates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Any key / value pairs in :doc:`field lists </usage/restructuredtext/field-lists>`
+that are placed *before* the page's title will be available to the Jinja
+template when building the page within the :data:`meta` attribute. For example,
+if a page had the following text before its first title:
+
+.. code-block:: rst
+
+ :mykey: My value
+
+ My first title
+ --------------
+
+Then it could be accessed within a Jinja template like so:
+
+.. code-block:: jinja
+
+ {%- if meta is mapping %}
+ {{ meta.get("mykey") }}
+ {%- endif %}
+
+Note the check that ``meta`` is a dictionary ("mapping" in Jinja
+terminology) to ensure that using it in this way is valid.
+
+
+Defining custom template functions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes it is useful to define your own function in Python that you wish to
+then use in a template. For example, if you'd like to insert a template value
+with logic that depends on the user's configuration in the project, or if you'd
+like to include non-trivial checks and provide friendly error messages for
+incorrect configuration in the template.
+
+To define your own template function, you'll need to define two functions
+inside your module:
+
+* A **page context event handler** (or **registration**) function. This is
+ connected to the :class:`.Sphinx` application via an event callback.
+* A **template function** that you will use in your Jinja template.
+
+First, define the registration function, which accepts the arguments for
+:event:`html-page-context`.
+
+Within the registration function, define the template function that you'd like to
+use within Jinja. The template function should return a string or Python objects
+(lists, dictionaries) with strings inside that Jinja uses in the templating process
+
+.. note::
+
+ The template function will have access to all of the variables that
+ are passed to the registration function.
+
+At the end of the registration function, add the template function to the
+Sphinx application's context with ``context['template_func'] = template_func``.
+
+Finally, in your extension's ``setup()`` function, add your registration
+function as a callback for :event:`html-page-context`.
+
+.. code-block:: python
+
+ # The registration function
+ def setup_my_func(app, pagename, templatename, context, doctree):
+ # The template function
+ def my_func(mystring):
+ return "Your string is %s" % mystring
+ # Add it to the page's context
+ context['my_func'] = my_func
+
+ # Your extension's setup function
+ def setup(app):
+ app.connect("html-page-context", setup_my_func)
+
+Now, you will have access to this function in jinja like so:
+
+.. code-block:: jinja
+
+ <div>
+ {{ my_func("some string") }}
+ </div>
+
+
+Add your own static files to the build assets
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, Sphinx copies static files on the ``static/`` directory of the template
+directory. However, if your package needs to place static files outside of the
+``static/`` directory for some reasons, you need to copy them to the ``_static/``
+directory of HTML outputs manually at the build via an event hook. Here is an
+example of code to accomplish this:
+
+.. code-block:: python
+
+ from os import path
+ from sphinx.util.fileutil import copy_asset_file
+
+ def copy_custom_files(app, exc):
+ if app.builder.format == 'html' and not exc:
+ staticdir = path.join(app.builder.outdir, '_static')
+ copy_asset_file('path/to/myextension/_static/myjsfile.js', staticdir)
+
+ def setup(app):
+ app.connect('build-finished', copy_custom_files)
+
+
+Inject JavaScript based on user configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your extension makes use of JavaScript, it can be useful to allow users
+to control its behavior using their Sphinx configuration. However, this can
+be difficult to do if your JavaScript comes in the form of a static library
+(which will not be built with Jinja).
+
+There are two ways to inject variables into the JavaScript space based on user
+configuration.
+
+First, you may append ``_t`` to the end of any static files included with your
+extension. This will cause Sphinx to process these files with the templating
+engine, allowing you to embed variables and control behavior.
+
+For example, the following JavaScript structure:
+
+.. code-block:: none
+
+ mymodule/
+ ├── _static
+ │   └── myjsfile.js_t
+ └── mymodule.py
+
+Will result in the following static file placed in your HTML's build output:
+
+.. code-block:: none
+
+ _build/
+ └── html
+ └── _static
+    └── myjsfile.js
+
+See :ref:`theming-static-templates` for more information.
+
+Second, you may use the :meth:`.Sphinx.add_js_file` method without pointing it
+to a file. Normally, this method is used to insert a new JavaScript file
+into your site. However, if you do *not* pass a file path, but instead pass
+a string to the "body" argument, then this text will be inserted as JavaScript
+into your site's head. This allows you to insert variables into your project's
+JavaScript from Python.
+
+For example, the following code will read in a user-configured value and then
+insert this value as a JavaScript variable, which your extension's JavaScript
+code may use:
+
+.. code-block:: python
+
+ # This function reads in a variable and inserts it into JavaScript
+ def add_js_variable(app):
+ # This is a configuration that you've specified for users in `conf.py`
+ js_variable = app.config['my_javascript_variable']
+ js_text = "var my_variable = '%s';" % js_variable
+ app.add_js_file(None, body=js_text)
+ # We connect this function to the step after the builder is initialized
+ def setup(app):
+ # Tell Sphinx about this configuration variable
+ app.add_config_value('my_javascript_variable', 0, 'html')
+ # Run the function after the builder is initialized
+ app.connect('builder-inited', add_js_variable)
+
+As a result, in your theme you can use code that depends on the presence of
+this variable. Users can control the variable's value by defining it in their
+:file:`conf.py` file.
+
+
+.. [1] It is not an executable Python file, as opposed to :file:`conf.py`,
+ because that would pose an unnecessary security risk if themes are
+ shared.
diff --git a/doc/development/tutorials/autodoc_ext.rst b/doc/development/tutorials/autodoc_ext.rst
new file mode 100644
index 0000000..cfd23e7
--- /dev/null
+++ b/doc/development/tutorials/autodoc_ext.rst
@@ -0,0 +1,141 @@
+.. _autodoc_ext_tutorial:
+
+Developing autodoc extension for IntEnum
+========================================
+
+The objective of this tutorial is to create an extension that adds
+support for new type for autodoc. This autodoc extension will format
+the ``IntEnum`` class from Python standard library. (module ``enum``)
+
+Overview
+--------
+
+We want the extension that will create auto-documentation for IntEnum.
+``IntEnum`` is the integer enum class from standard library ``enum`` module.
+
+Currently this class has no special auto documentation behavior.
+
+We want to add following to autodoc:
+
+* A new ``autointenum`` directive that will document the ``IntEnum`` class.
+* The generated documentation will have all the enum possible values
+ with names.
+* The ``autointenum`` directive will have an option ``:hex:`` which will
+ cause the integers be printed in hexadecimal form.
+
+
+Prerequisites
+-------------
+
+We need the same setup as in :doc:`the previous extensions <todo>`. This time,
+we will be putting out extension in a file called :file:`autodoc_intenum.py`.
+The :file:`my_enums.py` will contain the sample enums we will document.
+
+Here is an example of the folder structure you might obtain:
+
+.. code-block:: text
+
+ └── source
+    ├── _ext
+ │   └── autodoc_intenum.py
+    ├── conf.py
+    ├── index.rst
+    └── my_enums.py
+
+
+Writing the extension
+---------------------
+
+Start with ``setup`` function for the extension.
+
+.. literalinclude:: examples/autodoc_intenum.py
+ :language: python
+ :linenos:
+ :pyobject: setup
+
+
+The :meth:`~sphinx.application.Sphinx.setup_extension` method will pull the
+autodoc extension because our new extension depends on autodoc.
+:meth:`~sphinx.application.Sphinx.add_autodocumenter` is the method that
+registers our new auto documenter class.
+
+We want to import certain objects from the autodoc extension:
+
+.. literalinclude:: examples/autodoc_intenum.py
+ :language: python
+ :linenos:
+ :lines: 1-7
+
+
+There are several different documenter classes such as ``MethodDocumenter``
+or ``AttributeDocumenter`` available in the autodoc extension but
+our new class is the subclass of ``ClassDocumenter`` which a
+documenter class used by autodoc to document classes.
+
+This is the definition of our new the auto-documenter class:
+
+.. literalinclude:: examples/autodoc_intenum.py
+ :language: python
+ :linenos:
+ :pyobject: IntEnumDocumenter
+
+
+Important attributes of the new class:
+
+**objtype**
+ This attribute determines the ``auto`` directive name. In
+ this case the auto directive will be ``autointenum``.
+
+**directivetype**
+ This attribute sets the generated directive name. In
+ this example the generated directive will be ``.. :py:class::``.
+
+**priority**
+ the larger the number the higher is the priority. We want our
+ documenter be higher priority than the parent.
+
+**option_spec**
+ option specifications. We copy the parent class options and
+ add a new option *hex*.
+
+
+Overridden members:
+
+**can_document_member**
+ This member is important to override. It should
+ return *True* when the passed object can be documented by this class.
+
+**add_directive_header**
+ This method generates the directive header. We add
+ **:final:** directive option. Remember to call **super** or no directive
+ will be generated.
+
+**add_content**
+ This method generates the body of the class documentation.
+ After calling the super method we generate lines for enum description.
+
+
+Using the extension
+-------------------
+
+You can now use the new autodoc directive to document any ``IntEnum``.
+
+For example, you have the following ``IntEnum``:
+
+.. code-block:: python
+ :caption: my_enums.py
+
+ class Colors(IntEnum):
+ """Colors enumerator"""
+ NONE = 0
+ RED = 1
+ GREEN = 2
+ BLUE = 3
+
+
+This will be the documentation file with auto-documentation directive:
+
+.. code-block:: rst
+ :caption: index.rst
+
+ .. autointenum:: my_enums.Colors
diff --git a/doc/development/tutorials/examples/README.rst b/doc/development/tutorials/examples/README.rst
new file mode 100644
index 0000000..2b9c01b
--- /dev/null
+++ b/doc/development/tutorials/examples/README.rst
@@ -0,0 +1,11 @@
+:orphan:
+
+Tutorial examples
+=================
+
+This directory contains a number of examples used in the tutorials. These are
+intended to be increasingly complex to demonstrate the various features of
+Sphinx, but should aim to be as complicated as necessary but no more.
+Individual sections are referenced by line numbers, meaning if you make changes
+to the source files, you should update the references in the documentation
+accordingly.
diff --git a/doc/development/tutorials/examples/autodoc_intenum.py b/doc/development/tutorials/examples/autodoc_intenum.py
new file mode 100644
index 0000000..75fa204
--- /dev/null
+++ b/doc/development/tutorials/examples/autodoc_intenum.py
@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from enum import IntEnum
+from typing import TYPE_CHECKING, Any
+
+from sphinx.ext.autodoc import ClassDocumenter, bool_option
+
+if TYPE_CHECKING:
+ from docutils.statemachine import StringList
+
+ from sphinx.application import Sphinx
+
+
+class IntEnumDocumenter(ClassDocumenter):
+ objtype = 'intenum'
+ directivetype = ClassDocumenter.objtype
+ priority = 10 + ClassDocumenter.priority
+ option_spec = dict(ClassDocumenter.option_spec)
+ option_spec['hex'] = bool_option
+
+ @classmethod
+ def can_document_member(cls,
+ member: Any, membername: str,
+ isattr: bool, parent: Any) -> bool:
+ try:
+ return issubclass(member, IntEnum)
+ except TypeError:
+ return False
+
+ def add_directive_header(self, sig: str) -> None:
+ super().add_directive_header(sig)
+ self.add_line(' :final:', self.get_sourcename())
+
+ def add_content(self,
+ more_content: StringList | None,
+ no_docstring: bool = False,
+ ) -> None:
+
+ super().add_content(more_content, no_docstring)
+
+ source_name = self.get_sourcename()
+ enum_object: IntEnum = self.object
+ use_hex = self.options.hex
+ self.add_line('', source_name)
+
+ for the_member_name, enum_member in enum_object.__members__.items():
+ the_member_value = enum_member.value
+ if use_hex:
+ the_member_value = hex(the_member_value)
+
+ self.add_line(
+ f"**{the_member_name}**: {the_member_value}", source_name)
+ self.add_line('', source_name)
+
+
+def setup(app: Sphinx) -> None:
+ app.setup_extension('sphinx.ext.autodoc') # Require autodoc extension
+ app.add_autodocumenter(IntEnumDocumenter)
diff --git a/doc/development/tutorials/examples/helloworld.py b/doc/development/tutorials/examples/helloworld.py
new file mode 100644
index 0000000..d6d81fd
--- /dev/null
+++ b/doc/development/tutorials/examples/helloworld.py
@@ -0,0 +1,19 @@
+from docutils import nodes
+from docutils.parsers.rst import Directive
+
+
+class HelloWorld(Directive):
+
+ def run(self):
+ paragraph_node = nodes.paragraph(text='Hello World!')
+ return [paragraph_node]
+
+
+def setup(app):
+ app.add_directive("helloworld", HelloWorld)
+
+ return {
+ 'version': '0.1',
+ 'parallel_read_safe': True,
+ 'parallel_write_safe': True,
+ }
diff --git a/doc/development/tutorials/examples/recipe.py b/doc/development/tutorials/examples/recipe.py
new file mode 100644
index 0000000..c7ebf2a
--- /dev/null
+++ b/doc/development/tutorials/examples/recipe.py
@@ -0,0 +1,159 @@
+from collections import defaultdict
+
+from docutils.parsers.rst import directives
+
+from sphinx import addnodes
+from sphinx.directives import ObjectDescription
+from sphinx.domains import Domain, Index
+from sphinx.roles import XRefRole
+from sphinx.util.nodes import make_refnode
+
+
+class RecipeDirective(ObjectDescription):
+ """A custom directive that describes a recipe."""
+
+ has_content = True
+ required_arguments = 1
+ option_spec = {
+ 'contains': directives.unchanged_required,
+ }
+
+ def handle_signature(self, sig, signode):
+ signode += addnodes.desc_name(text=sig)
+ return sig
+
+ def add_target_and_index(self, name_cls, sig, signode):
+ signode['ids'].append('recipe' + '-' + sig)
+ if 'contains' in self.options:
+ ingredients = [
+ x.strip() for x in self.options.get('contains').split(',')]
+
+ recipes = self.env.get_domain('recipe')
+ recipes.add_recipe(sig, ingredients)
+
+
+class IngredientIndex(Index):
+ """A custom index that creates an ingredient matrix."""
+
+ name = 'ingredient'
+ localname = 'Ingredient Index'
+ shortname = 'Ingredient'
+
+ def generate(self, docnames=None):
+ content = defaultdict(list)
+
+ recipes = {name: (dispname, typ, docname, anchor)
+ for name, dispname, typ, docname, anchor, _
+ in self.domain.get_objects()}
+ recipe_ingredients = self.domain.data['recipe_ingredients']
+ ingredient_recipes = defaultdict(list)
+
+ # flip from recipe_ingredients to ingredient_recipes
+ for recipe_name, ingredients in recipe_ingredients.items():
+ for ingredient in ingredients:
+ ingredient_recipes[ingredient].append(recipe_name)
+
+ # convert the mapping of ingredient to recipes to produce the expected
+ # output, shown below, using the ingredient name as a key to group
+ #
+ # name, subtype, docname, anchor, extra, qualifier, description
+ for ingredient, recipe_names in ingredient_recipes.items():
+ for recipe_name in recipe_names:
+ dispname, typ, docname, anchor = recipes[recipe_name]
+ content[ingredient].append(
+ (dispname, 0, docname, anchor, docname, '', typ))
+
+ # convert the dict to the sorted list of tuples expected
+ content = sorted(content.items())
+
+ return content, True
+
+
+class RecipeIndex(Index):
+ """A custom index that creates an recipe matrix."""
+
+ name = 'recipe'
+ localname = 'Recipe Index'
+ shortname = 'Recipe'
+
+ def generate(self, docnames=None):
+ content = defaultdict(list)
+
+ # sort the list of recipes in alphabetical order
+ recipes = self.domain.get_objects()
+ recipes = sorted(recipes, key=lambda recipe: recipe[0])
+
+ # generate the expected output, shown below, from the above using the
+ # first letter of the recipe as a key to group thing
+ #
+ # name, subtype, docname, anchor, extra, qualifier, description
+ for _name, dispname, typ, docname, anchor, _priority in recipes:
+ content[dispname[0].lower()].append(
+ (dispname, 0, docname, anchor, docname, '', typ))
+
+ # convert the dict to the sorted list of tuples expected
+ content = sorted(content.items())
+
+ return content, True
+
+
+class RecipeDomain(Domain):
+
+ name = 'recipe'
+ label = 'Recipe Sample'
+ roles = {
+ 'ref': XRefRole(),
+ }
+ directives = {
+ 'recipe': RecipeDirective,
+ }
+ indices = {
+ RecipeIndex,
+ IngredientIndex,
+ }
+ initial_data = {
+ 'recipes': [], # object list
+ 'recipe_ingredients': {}, # name -> object
+ }
+
+ def get_full_qualified_name(self, node):
+ return f'recipe.{node.arguments[0]}'
+
+ def get_objects(self):
+ yield from self.data['recipes']
+
+ def resolve_xref(self, env, fromdocname, builder, typ, target, node,
+ contnode):
+ match = [(docname, anchor)
+ for name, sig, typ, docname, anchor, prio
+ in self.get_objects() if sig == target]
+
+ if len(match) > 0:
+ todocname = match[0][0]
+ targ = match[0][1]
+
+ return make_refnode(builder, fromdocname, todocname, targ,
+ contnode, targ)
+ else:
+ print('Awww, found nothing')
+ return None
+
+ def add_recipe(self, signature, ingredients):
+ """Add a new recipe to the domain."""
+ name = f'recipe.{signature}'
+ anchor = f'recipe-{signature}'
+
+ self.data['recipe_ingredients'][name] = ingredients
+ # name, dispname, type, docname, anchor, priority
+ self.data['recipes'].append(
+ (name, signature, 'Recipe', self.env.docname, anchor, 0))
+
+
+def setup(app):
+ app.add_domain(RecipeDomain)
+
+ return {
+ 'version': '0.1',
+ 'parallel_read_safe': True,
+ 'parallel_write_safe': True,
+ }
diff --git a/doc/development/tutorials/examples/todo.py b/doc/development/tutorials/examples/todo.py
new file mode 100644
index 0000000..15368f4
--- /dev/null
+++ b/doc/development/tutorials/examples/todo.py
@@ -0,0 +1,135 @@
+from docutils import nodes
+from docutils.parsers.rst import Directive
+
+from sphinx.locale import _
+from sphinx.util.docutils import SphinxDirective
+
+
+class todo(nodes.Admonition, nodes.Element):
+ pass
+
+
+class todolist(nodes.General, nodes.Element):
+ pass
+
+
+def visit_todo_node(self, node):
+ self.visit_admonition(node)
+
+
+def depart_todo_node(self, node):
+ self.depart_admonition(node)
+
+
+class TodolistDirective(Directive):
+
+ def run(self):
+ return [todolist('')]
+
+
+class TodoDirective(SphinxDirective):
+
+ # this enables content in the directive
+ has_content = True
+
+ def run(self):
+ targetid = 'todo-%d' % self.env.new_serialno('todo')
+ targetnode = nodes.target('', '', ids=[targetid])
+
+ todo_node = todo('\n'.join(self.content))
+ todo_node += nodes.title(_('Todo'), _('Todo'))
+ self.state.nested_parse(self.content, self.content_offset, todo_node)
+
+ if not hasattr(self.env, 'todo_all_todos'):
+ self.env.todo_all_todos = []
+
+ self.env.todo_all_todos.append({
+ 'docname': self.env.docname,
+ 'lineno': self.lineno,
+ 'todo': todo_node.deepcopy(),
+ 'target': targetnode,
+ })
+
+ return [targetnode, todo_node]
+
+
+def purge_todos(app, env, docname):
+ if not hasattr(env, 'todo_all_todos'):
+ return
+
+ env.todo_all_todos = [todo for todo in env.todo_all_todos
+ if todo['docname'] != docname]
+
+
+def merge_todos(app, env, docnames, other):
+ if not hasattr(env, 'todo_all_todos'):
+ env.todo_all_todos = []
+ if hasattr(other, 'todo_all_todos'):
+ env.todo_all_todos.extend(other.todo_all_todos)
+
+
+def process_todo_nodes(app, doctree, fromdocname):
+ if not app.config.todo_include_todos:
+ for node in doctree.findall(todo):
+ node.parent.remove(node)
+
+ # Replace all todolist nodes with a list of the collected todos.
+ # Augment each todo with a backlink to the original location.
+ env = app.builder.env
+
+ if not hasattr(env, 'todo_all_todos'):
+ env.todo_all_todos = []
+
+ for node in doctree.findall(todolist):
+ if not app.config.todo_include_todos:
+ node.replace_self([])
+ continue
+
+ content = []
+
+ for todo_info in env.todo_all_todos:
+ para = nodes.paragraph()
+ filename = env.doc2path(todo_info['docname'], base=None)
+ description = (
+ _('(The original entry is located in %s, line %d and can be found ') %
+ (filename, todo_info['lineno']))
+ para += nodes.Text(description)
+
+ # Create a reference
+ newnode = nodes.reference('', '')
+ innernode = nodes.emphasis(_('here'), _('here'))
+ newnode['refdocname'] = todo_info['docname']
+ newnode['refuri'] = app.builder.get_relative_uri(
+ fromdocname, todo_info['docname'])
+ newnode['refuri'] += '#' + todo_info['target']['refid']
+ newnode.append(innernode)
+ para += newnode
+ para += nodes.Text('.)')
+
+ # Insert into the todolist
+ content.append(todo_info['todo'])
+ content.append(para)
+
+ node.replace_self(content)
+
+
+def setup(app):
+ app.add_config_value('todo_include_todos', False, 'html')
+
+ app.add_node(todolist)
+ app.add_node(todo,
+ html=(visit_todo_node, depart_todo_node),
+ latex=(visit_todo_node, depart_todo_node),
+ text=(visit_todo_node, depart_todo_node))
+
+ app.add_directive('todo', TodoDirective)
+ app.add_directive('todolist', TodolistDirective)
+ app.connect('doctree-resolved', process_todo_nodes)
+ app.connect('env-purge-doc', purge_todos)
+ app.connect('env-merge-info', merge_todos)
+
+ return {
+ 'version': '0.1',
+ 'parallel_read_safe': True,
+ 'parallel_write_safe': True,
+ }
diff --git a/doc/development/tutorials/helloworld.rst b/doc/development/tutorials/helloworld.rst
new file mode 100644
index 0000000..8940e3d
--- /dev/null
+++ b/doc/development/tutorials/helloworld.rst
@@ -0,0 +1,189 @@
+Developing a "Hello world" extension
+====================================
+
+The objective of this tutorial is to create a very basic extension that adds a
+new directive. This directive will output a paragraph containing "hello world".
+
+Only basic information is provided in this tutorial. For more information, refer
+to the :doc:`other tutorials <index>` that go into more details.
+
+.. warning::
+
+ For this extension, you will need some basic understanding of docutils_
+ and Python.
+
+
+Overview
+--------
+
+We want the extension to add the following to Sphinx:
+
+* A ``helloworld`` directive, that will simply output the text "hello world".
+
+
+Prerequisites
+-------------
+
+We will not be distributing this plugin via `PyPI`_ and will instead include it
+as part of an existing project. This means you will need to use an existing
+project or create a new one using :program:`sphinx-quickstart`.
+
+We assume you are using separate source (:file:`source`) and build
+(:file:`build`) folders. Your extension file could be in any folder of your
+project. In our case, let's do the following:
+
+#. Create an :file:`_ext` folder in :file:`source`
+#. Create a new Python file in the :file:`_ext` folder called
+ :file:`helloworld.py`
+
+Here is an example of the folder structure you might obtain:
+
+.. code-block:: text
+
+ └── source
+    ├── _ext
+ │   └── helloworld.py
+    ├── _static
+    ├── conf.py
+    ├── somefolder
+    ├── index.rst
+    ├── somefile.rst
+    └── someotherfile.rst
+
+
+Writing the extension
+---------------------
+
+Open :file:`helloworld.py` and paste the following code in it:
+
+.. literalinclude:: examples/helloworld.py
+ :language: python
+ :linenos:
+
+Some essential things are happening in this example, and you will see them for
+all directives.
+
+.. rubric:: The directive class
+
+Our new directive is declared in the ``HelloWorld`` class.
+
+.. literalinclude:: examples/helloworld.py
+ :language: python
+ :linenos:
+ :lines: 5-9
+
+This class extends the docutils_' ``Directive`` class. All extensions that
+create directives should extend this class.
+
+.. seealso::
+
+ `The docutils documentation on creating directives <docutils directives_>`_
+
+This class contains a ``run`` method. This method is a requirement and it is
+part of every directive. It contains the main logic of the directive and it
+returns a list of docutils nodes to be processed by Sphinx. These nodes are
+docutils' way of representing the content of a document. There are many types of
+nodes available: text, paragraph, reference, table, etc.
+
+.. seealso::
+
+ `The docutils documentation on nodes <docutils nodes_>`_
+
+The ``nodes.paragraph`` class creates a new paragraph node. A paragraph
+node typically contains some text that we can set during instantiation using
+the ``text`` parameter.
+
+.. rubric:: The ``setup`` function
+
+.. currentmodule:: sphinx.application
+
+This function is a requirement. We use it to plug our new directive into
+Sphinx.
+
+.. literalinclude:: examples/helloworld.py
+ :language: python
+ :linenos:
+ :lines: 12-
+
+The simplest thing you can do is to call the :meth:`~Sphinx.add_directive` method,
+which is what we've done here. For this particular call, the first argument is
+the name of the directive itself as used in a reST file. In this case, we would
+use ``helloworld``. For example:
+
+.. code-block:: rst
+
+ Some intro text here...
+
+ .. helloworld::
+
+ Some more text here...
+
+We also return the :ref:`extension metadata <ext-metadata>` that indicates the
+version of our extension, along with the fact that it is safe to use the
+extension for both parallel reading and writing.
+
+
+Using the extension
+-------------------
+
+The extension has to be declared in your :file:`conf.py` file to make Sphinx
+aware of it. There are two steps necessary here:
+
+#. Add the :file:`_ext` directory to the `Python path`_ using
+ ``sys.path.append``. This should be placed at the top of the file.
+
+#. Update or create the :confval:`extensions` list and add the extension file
+ name to the list
+
+For example:
+
+.. code-block:: python
+
+ import os
+ import sys
+
+ sys.path.append(os.path.abspath("./_ext"))
+
+ extensions = ['helloworld']
+
+.. tip::
+
+ We're not distributing this extension as a `Python package`_, we need to
+ modify the `Python path`_ so Sphinx can find our extension. This is why we
+ need the call to ``sys.path.append``.
+
+You can now use the extension in a file. For example:
+
+.. code-block:: rst
+
+ Some intro text here...
+
+ .. helloworld::
+
+ Some more text here...
+
+The sample above would generate:
+
+.. code-block:: text
+
+ Some intro text here...
+
+ Hello World!
+
+ Some more text here...
+
+
+Further reading
+---------------
+
+This is the very basic principle of an extension that creates a new directive.
+
+For a more advanced example, refer to :doc:`todo`.
+
+
+.. _docutils: https://docutils.sourceforge.io/
+.. _docutils directives: https://docutils.sourceforge.io/docs/howto/rst-directives.html
+.. _docutils nodes: https://docutils.sourceforge.io/docs/ref/doctree.html
+.. _PyPI: https://pypi.org/
+.. _Python package: https://packaging.python.org/
+.. _Python path: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH
diff --git a/doc/development/tutorials/index.rst b/doc/development/tutorials/index.rst
new file mode 100644
index 0000000..a7eee48
--- /dev/null
+++ b/doc/development/tutorials/index.rst
@@ -0,0 +1,17 @@
+.. _extension-tutorials-index:
+
+Extension tutorials
+===================
+
+Refer to the following tutorials to get started with extension development.
+
+
+.. toctree::
+ :caption: Directive tutorials
+ :maxdepth: 1
+
+ helloworld
+ todo
+ recipe
+ autodoc_ext
+
diff --git a/doc/development/tutorials/recipe.rst b/doc/development/tutorials/recipe.rst
new file mode 100644
index 0000000..1ed428a
--- /dev/null
+++ b/doc/development/tutorials/recipe.rst
@@ -0,0 +1,227 @@
+Developing a "recipe" extension
+===============================
+
+The objective of this tutorial is to illustrate roles, directives and domains.
+Once complete, we will be able to use this extension to describe a recipe and
+reference that recipe from elsewhere in our documentation.
+
+.. note::
+
+ This tutorial is based on a guide first published on `opensource.com`_ and
+ is provided here with the original author's permission.
+
+ .. _opensource.com: https://opensource.com/article/18/11/building-custom-workflows-sphinx
+
+
+Overview
+--------
+
+We want the extension to add the following to Sphinx:
+
+* A ``recipe`` :term:`directive`, containing some content describing the recipe
+ steps, along with a ``:contains:`` option highlighting the main ingredients
+ of the recipe.
+
+* A ``ref`` :term:`role`, which provides a cross-reference to the recipe
+ itself.
+
+* A ``recipe`` :term:`domain`, which allows us to tie together the above role
+ and domain, along with things like indices.
+
+For that, we will need to add the following elements to Sphinx:
+
+* A new directive called ``recipe``
+
+* New indexes to allow us to reference ingredient and recipes
+
+* A new domain called ``recipe``, which will contain the ``recipe`` directive
+ and ``ref`` role
+
+
+Prerequisites
+-------------
+
+We need the same setup as in :doc:`the previous extensions <todo>`. This time,
+we will be putting out extension in a file called :file:`recipe.py`.
+
+Here is an example of the folder structure you might obtain:
+
+.. code-block:: text
+
+ └── source
+    ├── _ext
+ │   └── recipe.py
+    ├── conf.py
+    └── index.rst
+
+
+Writing the extension
+---------------------
+
+Open :file:`recipe.py` and paste the following code in it, all of which we will
+explain in detail shortly:
+
+.. literalinclude:: examples/recipe.py
+ :language: python
+ :linenos:
+
+Let's look at each piece of this extension step-by-step to explain what's going
+on.
+
+.. rubric:: The directive class
+
+The first thing to examine is the ``RecipeDirective`` directive:
+
+.. literalinclude:: examples/recipe.py
+ :language: python
+ :linenos:
+ :pyobject: RecipeDirective
+
+Unlike :doc:`helloworld` and :doc:`todo`, this directive doesn't derive from
+:class:`docutils.parsers.rst.Directive` and doesn't define a ``run`` method.
+Instead, it derives from :class:`sphinx.directives.ObjectDescription` and
+defines ``handle_signature`` and ``add_target_and_index`` methods. This is
+because ``ObjectDescription`` is a special-purpose directive that's intended
+for describing things like classes, functions, or, in our case, recipes. More
+specifically, ``handle_signature`` implements parsing the signature of the
+directive and passes on the object's name and type to its superclass, while
+``add_target_and_index`` adds a target (to link to) and an entry to the index
+for this node.
+
+We also see that this directive defines ``has_content``, ``required_arguments``
+and ``option_spec``. Unlike the ``TodoDirective`` directive added in the
+:doc:`previous tutorial <todo>`, this directive takes a single argument, the
+recipe name, and an option, ``contains``, in addition to the nested
+reStructuredText in the body.
+
+.. rubric:: The index classes
+
+.. currentmodule:: sphinx.domains
+
+.. todo:: Add brief overview of indices
+
+.. literalinclude:: examples/recipe.py
+ :language: python
+ :linenos:
+ :pyobject: IngredientIndex
+
+.. literalinclude:: examples/recipe.py
+ :language: python
+ :linenos:
+ :pyobject: RecipeIndex
+
+Both ``IngredientIndex`` and ``RecipeIndex`` are derived from :class:`Index`.
+They implement custom logic to generate a tuple of values that define the
+index. Note that ``RecipeIndex`` is a simple index that has only one entry.
+Extending it to cover more object types is not yet part of the code.
+
+Both indices use the method :meth:`Index.generate` to do their work. This
+method combines the information from our domain, sorts it, and returns it in a
+list structure that will be accepted by Sphinx. This might look complicated but
+all it really is is a list of tuples like ``('tomato', 'TomatoSoup', 'test',
+'rec-TomatoSoup',...)``. Refer to the :doc:`domain API guide
+</extdev/domainapi>` for more information on this API.
+
+These index pages can be referenced with the :rst:role:`ref` role by combining
+the domain name and the index ``name`` value. For example, ``RecipeIndex`` can be
+referenced with ``:ref:`recipe-recipe``` and ``IngredientIndex`` can be referenced
+with ``:ref:`recipe-ingredient```.
+
+.. rubric:: The domain
+
+A Sphinx domain is a specialized container that ties together roles,
+directives, and indices, among other things. Let's look at the domain we're
+creating here.
+
+.. literalinclude:: examples/recipe.py
+ :language: python
+ :linenos:
+ :pyobject: RecipeDomain
+
+There are some interesting things to note about this ``recipe`` domain and domains
+in general. Firstly, we actually register our directives, roles and indices
+here, via the ``directives``, ``roles`` and ``indices`` attributes, rather than
+via calls later on in ``setup``. We can also note that we aren't actually
+defining a custom role and are instead reusing the
+:class:`sphinx.roles.XRefRole` role and defining the
+:class:`sphinx.domains.Domain.resolve_xref` method. This method takes two
+arguments, ``typ`` and ``target``, which refer to the cross-reference type and
+its target name. We'll use ``target`` to resolve our destination from our
+domain's ``recipes`` because we currently have only one type of node.
+
+Moving on, we can see that we've defined ``initial_data``. The values defined in
+``initial_data`` will be copied to ``env.domaindata[domain_name]`` as the
+initial data of the domain, and domain instances can access it via
+``self.data``. We see that we have defined two items in ``initial_data``:
+``recipes`` and ``recipe_ingredients``. Each contains a list of all objects
+defined (i.e. all recipes) and a hash that maps a canonical ingredient name to
+the list of objects. The way we name objects is common across our extension and
+is defined in the ``get_full_qualified_name`` method. For each object created,
+the canonical name is ``recipe.<recipename>``, where ``<recipename>`` is the
+name the documentation writer gives the object (a recipe). This enables the
+extension to use different object types that share the same name. Having a
+canonical name and central place for our objects is a huge advantage. Both our
+indices and our cross-referencing code use this feature.
+
+.. rubric:: The ``setup`` function
+
+.. currentmodule:: sphinx.application
+
+:doc:`As always <todo>`, the ``setup`` function is a requirement and is used to
+hook the various parts of our extension into Sphinx. Let's look at the
+``setup`` function for this extension.
+
+.. literalinclude:: examples/recipe.py
+ :language: python
+ :linenos:
+ :pyobject: setup
+
+This looks a little different to what we're used to seeing. There are no calls
+to :meth:`~Sphinx.add_directive` or even :meth:`~Sphinx.add_role`. Instead, we
+have a single call to :meth:`~Sphinx.add_domain` followed by some
+initialization of the :ref:`standard domain <domains-std>`. This is because we
+had already registered our directives, roles and indexes as part of the
+directive itself.
+
+
+Using the extension
+-------------------
+
+You can now use the extension throughout your project. For example:
+
+.. code-block:: rst
+ :caption: index.rst
+
+ Joe's Recipes
+ =============
+
+ Below are a collection of my favourite recipes. I highly recommend the
+ :recipe:ref:`TomatoSoup` recipe in particular!
+
+ .. toctree::
+
+ tomato-soup
+
+.. code-block:: rst
+ :caption: tomato-soup.rst
+
+ The recipe contains `tomato` and `cilantro`.
+
+ .. recipe:recipe:: TomatoSoup
+ :contains: tomato, cilantro, salt, pepper
+
+ This recipe is a tasty tomato soup, combine all ingredients
+ and cook.
+
+The important things to note are the use of the ``:recipe:ref:`` role to
+cross-reference the recipe actually defined elsewhere (using the
+``:recipe:recipe:`` directive).
+
+
+Further reading
+---------------
+
+For more information, refer to the `docutils`_ documentation and
+:doc:`/extdev/index`.
+
+.. _docutils: https://docutils.sourceforge.io/docs/
diff --git a/doc/development/tutorials/todo.rst b/doc/development/tutorials/todo.rst
new file mode 100644
index 0000000..f23d8ad
--- /dev/null
+++ b/doc/development/tutorials/todo.rst
@@ -0,0 +1,367 @@
+Developing a "TODO" extension
+=============================
+
+The objective of this tutorial is to create a more comprehensive extension than
+that created in :doc:`helloworld`. Whereas that guide just covered writing a
+custom :term:`directive`, this guide adds multiple directives, along with custom
+nodes, additional config values and custom event handlers. To this end, we will
+cover a ``todo`` extension that adds capabilities to include todo entries in the
+documentation, and to collect these in a central place. This is similar the
+``sphinxext.todo`` extension distributed with Sphinx.
+
+
+Overview
+--------
+
+.. note::
+ To understand the design of this extension, refer to
+ :ref:`important-objects` and :ref:`build-phases`.
+
+We want the extension to add the following to Sphinx:
+
+* A ``todo`` directive, containing some content that is marked with "TODO" and
+ only shown in the output if a new config value is set. Todo entries should not
+ be in the output by default.
+
+* A ``todolist`` directive that creates a list of all todo entries throughout
+ the documentation.
+
+For that, we will need to add the following elements to Sphinx:
+
+* New directives, called ``todo`` and ``todolist``.
+
+* New document tree nodes to represent these directives, conventionally also
+ called ``todo`` and ``todolist``. We wouldn't need new nodes if the new
+ directives only produced some content representable by existing nodes.
+
+* A new config value ``todo_include_todos`` (config value names should start
+ with the extension name, in order to stay unique) that controls whether todo
+ entries make it into the output.
+
+* New event handlers: one for the :event:`doctree-resolved` event, to
+ replace the todo and todolist nodes, one for :event:`env-merge-info`
+ to merge intermediate results from parallel builds, and one for
+ :event:`env-purge-doc` (the reason for that will be covered later).
+
+
+Prerequisites
+-------------
+
+As with :doc:`helloworld`, we will not be distributing this plugin via PyPI so
+once again we need a Sphinx project to call this from. You can use an existing
+project or create a new one using :program:`sphinx-quickstart`.
+
+We assume you are using separate source (:file:`source`) and build
+(:file:`build`) folders. Your extension file could be in any folder of your
+project. In our case, let's do the following:
+
+#. Create an :file:`_ext` folder in :file:`source`
+#. Create a new Python file in the :file:`_ext` folder called :file:`todo.py`
+
+Here is an example of the folder structure you might obtain:
+
+.. code-block:: text
+
+ └── source
+    ├── _ext
+ │   └── todo.py
+    ├── _static
+    ├── conf.py
+    ├── somefolder
+    ├── index.rst
+    ├── somefile.rst
+    └── someotherfile.rst
+
+
+Writing the extension
+---------------------
+
+Open :file:`todo.py` and paste the following code in it, all of which we will
+explain in detail shortly:
+
+.. literalinclude:: examples/todo.py
+ :language: python
+ :linenos:
+
+This is far more extensive extension than the one detailed in :doc:`helloworld`,
+however, we will will look at each piece step-by-step to explain what's
+happening.
+
+.. rubric:: The node classes
+
+Let's start with the node classes:
+
+.. literalinclude:: examples/todo.py
+ :language: python
+ :linenos:
+ :lines: 8-21
+
+Node classes usually don't have to do anything except inherit from the standard
+docutils classes defined in :mod:`docutils.nodes`. ``todo`` inherits from
+``Admonition`` because it should be handled like a note or warning, ``todolist``
+is just a "general" node.
+
+.. note::
+
+ Many extensions will not have to create their own node classes and work fine
+ with the nodes already provided by `docutils
+ <https://docutils.sourceforge.io/docs/ref/doctree.html>`__ and :ref:`Sphinx
+ <nodes>`.
+
+.. attention::
+
+ It is important to know that while you can extend Sphinx without
+ leaving your ``conf.py``, if you declare an inherited node right
+ there, you'll hit an unobvious :py:class:`~pickle.PickleError`. So if
+ something goes wrong, please make sure that you put inherited nodes
+ into a separate Python module.
+
+ For more details, see:
+
+ - https://github.com/sphinx-doc/sphinx/issues/6751
+ - https://github.com/sphinx-doc/sphinx/issues/1493
+ - https://github.com/sphinx-doc/sphinx/issues/1424
+
+.. rubric:: The directive classes
+
+A directive class is a class deriving usually from
+:class:`docutils.parsers.rst.Directive`. The directive interface is also
+covered in detail in the `docutils documentation`_; the important thing is that
+the class should have attributes that configure the allowed markup, and a
+``run`` method that returns a list of nodes.
+
+Looking first at the ``TodolistDirective`` directive:
+
+.. literalinclude:: examples/todo.py
+ :language: python
+ :linenos:
+ :lines: 24-27
+
+It's very simple, creating and returning an instance of our ``todolist`` node
+class. The ``TodolistDirective`` directive itself has neither content nor
+arguments that need to be handled. That brings us to the ``TodoDirective``
+directive:
+
+.. literalinclude:: examples/todo.py
+ :language: python
+ :linenos:
+ :lines: 30-53
+
+Several important things are covered here. First, as you can see, we're now
+subclassing the :class:`~sphinx.util.docutils.SphinxDirective` helper class
+instead of the usual :class:`~docutils.parsers.rst.Directive` class. This
+gives us access to the :ref:`build environment instance <important-objects>`
+using the ``self.env`` property. Without this, we'd have to use the rather
+convoluted ``self.state.document.settings.env``. Then, to act as a link target
+(from ``TodolistDirective``), the ``TodoDirective`` directive needs to return a
+target node in addition to the ``todo`` node. The target ID (in HTML, this will
+be the anchor name) is generated by using ``env.new_serialno`` which returns a
+new unique integer on each call and therefore leads to unique target names. The
+target node is instantiated without any text (the first two arguments).
+
+On creating admonition node, the content body of the directive are parsed using
+``self.state.nested_parse``. The first argument gives the content body, and
+the second one gives content offset. The third argument gives the parent node
+of parsed result, in our case the ``todo`` node. Following this, the ``todo``
+node is added to the environment. This is needed to be able to create a list of
+all todo entries throughout the documentation, in the place where the author
+puts a ``todolist`` directive. For this case, the environment attribute
+``todo_all_todos`` is used (again, the name should be unique, so it is prefixed
+by the extension name). It does not exist when a new environment is created, so
+the directive must check and create it if necessary. Various information about
+the todo entry's location are stored along with a copy of the node.
+
+In the last line, the nodes that should be put into the doctree are returned:
+the target node and the admonition node.
+
+The node structure that the directive returns looks like this::
+
+ +--------------------+
+ | target node |
+ +--------------------+
+ +--------------------+
+ | todo node |
+ +--------------------+
+ \__+--------------------+
+ | admonition title |
+ +--------------------+
+ | paragraph |
+ +--------------------+
+ | ... |
+ +--------------------+
+
+.. rubric:: The event handlers
+
+Event handlers are one of Sphinx's most powerful features, providing a way to
+do hook into any part of the documentation process. There are many events
+provided by Sphinx itself, as detailed in :ref:`the API guide <events>`, and
+we're going to use a subset of them here.
+
+Let's look at the event handlers used in the above example. First, the one for
+the :event:`env-purge-doc` event:
+
+.. literalinclude:: examples/todo.py
+ :language: python
+ :linenos:
+ :lines: 56-61
+
+Since we store information from source files in the environment, which is
+persistent, it may become out of date when the source file changes. Therefore,
+before each source file is read, the environment's records of it are cleared,
+and the :event:`env-purge-doc` event gives extensions a chance to do the same.
+Here we clear out all todos whose docname matches the given one from the
+``todo_all_todos`` list. If there are todos left in the document, they will be
+added again during parsing.
+
+The next handler, for the :event:`env-merge-info` event, is used
+during parallel builds. As during parallel builds all threads have
+their own ``env``, there's multiple ``todo_all_todos`` lists that need
+to be merged:
+
+.. literalinclude:: examples/todo.py
+ :language: python
+ :linenos:
+ :lines: 64-68
+
+
+The other handler belongs to the :event:`doctree-resolved` event:
+
+.. literalinclude:: examples/todo.py
+ :language: python
+ :linenos:
+ :lines: 71-113
+
+The :event:`doctree-resolved` event is emitted at the end of :ref:`phase 3
+(resolving) <build-phases>` and allows custom resolving to be done. The handler
+we have written for this event is a bit more involved. If the
+``todo_include_todos`` config value (which we'll describe shortly) is false,
+all ``todo`` and ``todolist`` nodes are removed from the documents. If not,
+``todo`` nodes just stay where and how they are. ``todolist`` nodes are
+replaced by a list of todo entries, complete with backlinks to the location
+where they come from. The list items are composed of the nodes from the
+``todo`` entry and docutils nodes created on the fly: a paragraph for each
+entry, containing text that gives the location, and a link (reference node
+containing an italic node) with the backreference. The reference URI is built
+by :meth:`sphinx.builders.Builder.get_relative_uri` which creates a suitable
+URI depending on the used builder, and appending the todo node's (the target's)
+ID as the anchor name.
+
+.. rubric:: The ``setup`` function
+
+.. currentmodule:: sphinx.application
+
+As noted :doc:`previously <helloworld>`, the ``setup`` function is a requirement
+and is used to plug directives into Sphinx. However, we also use it to hook up
+the other parts of our extension. Let's look at our ``setup`` function:
+
+.. literalinclude:: examples/todo.py
+ :language: python
+ :linenos:
+ :lines: 116-
+
+The calls in this function refer to the classes and functions we added earlier.
+What the individual calls do is the following:
+
+* :meth:`~Sphinx.add_config_value` lets Sphinx know that it should recognize the
+ new *config value* ``todo_include_todos``, whose default value should be
+ ``False`` (this also tells Sphinx that it is a boolean value).
+
+ If the third argument was ``'html'``, HTML documents would be full rebuild if the
+ config value changed its value. This is needed for config values that
+ influence reading (build :ref:`phase 1 (reading) <build-phases>`).
+
+* :meth:`~Sphinx.add_node` adds a new *node class* to the build system. It also
+ can specify visitor functions for each supported output format. These visitor
+ functions are needed when the new nodes stay until :ref:`phase 4 (writing)
+ <build-phases>`. Since the ``todolist`` node is always replaced in
+ :ref:`phase 3 (resolving) <build-phases>`, it doesn't need any.
+
+* :meth:`~Sphinx.add_directive` adds a new *directive*, given by name and class.
+
+* Finally, :meth:`~Sphinx.connect` adds an *event handler* to the event whose
+ name is given by the first argument. The event handler function is called
+ with several arguments which are documented with the event.
+
+With this, our extension is complete.
+
+
+Using the extension
+-------------------
+
+As before, we need to enable the extension by declaring it in our
+:file:`conf.py` file. There are two steps necessary here:
+
+#. Add the :file:`_ext` directory to the `Python path`_ using
+ ``sys.path.append``. This should be placed at the top of the file.
+
+#. Update or create the :confval:`extensions` list and add the extension file
+ name to the list
+
+In addition, we may wish to set the ``todo_include_todos`` config value. As
+noted above, this defaults to ``False`` but we can set it explicitly.
+
+For example:
+
+.. code-block:: python
+
+ import os
+ import sys
+
+ sys.path.append(os.path.abspath("./_ext"))
+
+ extensions = ['todo']
+
+ todo_include_todos = False
+
+You can now use the extension throughout your project. For example:
+
+.. code-block:: rst
+ :caption: index.rst
+
+ Hello, world
+ ============
+
+ .. toctree::
+ somefile.rst
+ someotherfile.rst
+
+ Hello world. Below is the list of TODOs.
+
+ .. todolist::
+
+.. code-block:: rst
+ :caption: somefile.rst
+
+ foo
+ ===
+
+ Some intro text here...
+
+ .. todo:: Fix this
+
+.. code-block:: rst
+ :caption: someotherfile.rst
+
+ bar
+ ===
+
+ Some more text here...
+
+ .. todo:: Fix that
+
+Because we have configured ``todo_include_todos`` to ``False``, we won't
+actually see anything rendered for the ``todo`` and ``todolist`` directives.
+However, if we toggle this to true, we will see the output described
+previously.
+
+
+Further reading
+---------------
+
+For more information, refer to the `docutils`_ documentation and
+:doc:`/extdev/index`.
+
+
+.. _docutils: https://docutils.sourceforge.io/docs/
+.. _Python path: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH
+.. _docutils documentation: https://docutils.sourceforge.io/docs/ref/rst/directives.html
diff --git a/doc/examples.rst b/doc/examples.rst
new file mode 100644
index 0000000..c28364a
--- /dev/null
+++ b/doc/examples.rst
@@ -0,0 +1,5 @@
+:tocdepth: 2
+
+.. _examples:
+
+.. include:: ../EXAMPLES
diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst
new file mode 100644
index 0000000..270000b
--- /dev/null
+++ b/doc/extdev/appapi.rst
@@ -0,0 +1,473 @@
+.. highlight:: rest
+
+Application API
+===============
+
+.. module:: sphinx.application
+ :synopsis: Application class and extensibility interface.
+
+
+Each Sphinx extension is a Python module with at least a :func:`setup`
+function. This function is called at initialization time with one argument,
+the application object representing the Sphinx process.
+
+.. class:: Sphinx
+
+ This application object has the public API described in the following.
+
+Extension setup
+---------------
+
+These methods are usually called in an extension's ``setup()`` function.
+
+Examples of using the Sphinx extension API can be seen in the :mod:`sphinx.ext`
+package.
+
+.. currentmodule:: sphinx.application
+
+.. automethod:: Sphinx.setup_extension
+
+.. automethod:: Sphinx.require_sphinx
+
+.. automethod:: Sphinx.connect
+
+.. automethod:: Sphinx.disconnect
+
+.. automethod:: Sphinx.add_builder
+
+.. automethod:: Sphinx.add_config_value
+
+.. automethod:: Sphinx.add_event
+
+.. automethod:: Sphinx.set_translator
+
+.. automethod:: Sphinx.add_node
+
+.. automethod:: Sphinx.add_enumerable_node
+
+.. automethod:: Sphinx.add_directive
+
+.. automethod:: Sphinx.add_role
+
+.. automethod:: Sphinx.add_generic_role
+
+.. automethod:: Sphinx.add_domain
+
+.. automethod:: Sphinx.add_directive_to_domain
+
+.. automethod:: Sphinx.add_role_to_domain
+
+.. automethod:: Sphinx.add_index_to_domain
+
+.. automethod:: Sphinx.add_object_type
+
+.. automethod:: Sphinx.add_crossref_type
+
+.. automethod:: Sphinx.add_transform
+
+.. automethod:: Sphinx.add_post_transform
+
+.. automethod:: Sphinx.add_js_file
+
+.. automethod:: Sphinx.add_css_file
+
+.. automethod:: Sphinx.add_latex_package
+
+.. automethod:: Sphinx.add_lexer
+
+.. automethod:: Sphinx.add_autodocumenter
+
+.. automethod:: Sphinx.add_autodoc_attrgetter
+
+.. automethod:: Sphinx.add_search_language
+
+.. automethod:: Sphinx.add_source_suffix
+
+.. automethod:: Sphinx.add_source_parser
+
+.. automethod:: Sphinx.add_env_collector
+
+.. automethod:: Sphinx.add_html_theme
+
+.. automethod:: Sphinx.add_html_math_renderer
+
+.. automethod:: Sphinx.add_message_catalog
+
+.. automethod:: Sphinx.is_parallel_allowed
+
+.. exception:: ExtensionError
+
+ All these methods raise this exception if something went wrong with the
+ extension API.
+
+
+Emitting events
+---------------
+
+.. class:: Sphinx
+ :no-index:
+
+ .. automethod:: emit
+
+ .. automethod:: emit_firstresult
+
+
+Sphinx runtime information
+--------------------------
+
+The application object also provides runtime information as attributes.
+
+.. attribute:: Sphinx.project
+
+ Target project. See :class:`.Project`.
+
+.. attribute:: Sphinx.srcdir
+
+ Source directory.
+
+.. attribute:: Sphinx.confdir
+
+ Directory containing ``conf.py``.
+
+.. attribute:: Sphinx.doctreedir
+
+ Directory for storing pickled doctrees.
+
+.. attribute:: Sphinx.outdir
+
+ Directory for storing built document.
+
+
+.. _events:
+
+Sphinx core events
+------------------
+
+These events are known to the core. The arguments shown are given to the
+registered event handlers. Use :meth:`.Sphinx.connect` in an extension's
+``setup`` function (note that ``conf.py`` can also have a ``setup`` function) to
+connect handlers to the events. Example:
+
+.. code-block:: python
+
+ def source_read_handler(app, docname, source):
+ print('do something here...')
+
+ def setup(app):
+ app.connect('source-read', source_read_handler)
+
+
+Below is an overview of each event that happens during a build. In the list
+below, we include the event name, its callback parameters, and the input and output
+type for that event:
+
+.. code-block:: none
+
+ 1. event.config-inited(app,config)
+ 2. event.builder-inited(app)
+ 3. event.env-get-outdated(app, env, added, changed, removed)
+ 4. event.env-before-read-docs(app, env, docnames)
+
+ for docname in docnames:
+ 5. event.env-purge-doc(app, env, docname)
+
+ if doc changed and not removed:
+ 6. source-read(app, docname, source)
+ 7. run source parsers: text -> docutils.document
+ - parsers can be added with the app.add_source_parser() API
+ 8. apply transforms based on priority: docutils.document -> docutils.document
+ - event.doctree-read(app, doctree) is called in the middle of transforms,
+ transforms come before/after this event depending on their priority.
+
+ 9. event.env-merge-info(app, env, docnames, other)
+ - if running in parallel mode, this event will be emitted for each process
+
+ 10. event.env-updated(app, env)
+ 11. event.env-get-updated(app, env)
+ 12. event.env-check-consistency(app, env)
+
+ # The updated-docs list can be builder dependent, but generally includes all new/changed documents,
+ # plus any output from `env-get-updated`, and then all "parent" documents in the ToC tree
+ # For builders that output a single page, they are first joined into a single doctree before post-transforms
+ # or the doctree-resolved event is emitted
+ for docname in updated-docs:
+ 13. apply post-transforms (by priority): docutils.document -> docutils.document
+ 14. event.doctree-resolved(app, doctree, docname)
+ - In the event that any reference nodes fail to resolve, the following may emit:
+ - event.missing-reference(env, node, contnode)
+ - event.warn-missing-reference(domain, node)
+
+ 15. Generate output files
+ 16. event.build-finished(app, exception)
+
+Here is a more detailed list of these events.
+
+.. event:: builder-inited (app)
+
+ Emitted when the builder object has been created. It is available as
+ ``app.builder``.
+
+.. event:: config-inited (app, config)
+
+ Emitted when the config object has been initialized.
+
+ .. versionadded:: 1.8
+
+.. event:: env-get-outdated (app, env, added, changed, removed)
+
+ Emitted when the environment determines which source files have changed and
+ should be re-read. *added*, *changed* and *removed* are sets of docnames
+ that the environment has determined. You can return a list of docnames to
+ re-read in addition to these.
+
+ .. versionadded:: 1.1
+
+.. event:: env-purge-doc (app, env, docname)
+
+ Emitted when all traces of a source file should be cleaned from the
+ environment, that is, if the source file is removed or before it is freshly
+ read. This is for extensions that keep their own caches in attributes of the
+ environment.
+
+ For example, there is a cache of all modules on the environment. When a
+ source file has been changed, the cache's entries for the file are cleared,
+ since the module declarations could have been removed from the file.
+
+ .. versionadded:: 0.5
+
+.. event:: env-before-read-docs (app, env, docnames)
+
+ Emitted after the environment has determined the list of all added and
+ changed files and just before it reads them. It allows extension authors to
+ reorder the list of docnames (*inplace*) before processing, or add more
+ docnames that Sphinx did not consider changed (but never add any docnames
+ that are not in ``env.found_docs``).
+
+ You can also remove document names; do this with caution since it will make
+ Sphinx treat changed files as unchanged.
+
+ .. versionadded:: 1.3
+
+.. event:: source-read (app, docname, source)
+
+ Emitted when a source file has been read. The *source* argument is a list
+ whose single element is the contents of the source file. You can process the
+ contents and replace this item to implement source-level transformations.
+
+ For example, if you want to use ``$`` signs to delimit inline math, like in
+ LaTeX, you can use a regular expression to replace ``$...$`` by
+ ``:math:`...```.
+
+ .. versionadded:: 0.5
+
+.. event:: include-read (app, relative_path, parent_docname, content)
+
+ Emitted when a file has been read with the :dudir:`include` directive.
+ The *relative_path* argument is a :py:class:`~pathlib.Path` object representing
+ the relative path of the included file from the :term:`source directory`.
+ The *parent_docname* argument is the name of the document that
+ contains the :dudir:`include` directive.
+ The *source* argument is a list whose single element is
+ the contents of the included file.
+ You can process the contents and replace this item
+ to transform the included content,
+ as with the :event:`source-read` event.
+
+ .. versionadded:: 7.2.5
+
+ .. seealso:: The :dudir:`include` directive and the :event:`source-read` event.
+
+.. event:: object-description-transform (app, domain, objtype, contentnode)
+
+ Emitted when an object description directive has run. The *domain* and
+ *objtype* arguments are strings indicating object description of the object.
+ And *contentnode* is a content for the object. It can be modified in-place.
+
+ .. versionadded:: 2.4
+
+.. event:: doctree-read (app, doctree)
+
+ Emitted when a doctree has been parsed and read by the environment, and is
+ about to be pickled. The *doctree* can be modified in-place.
+
+.. event:: missing-reference (app, env, node, contnode)
+
+ Emitted when a cross-reference to an object cannot be resolved.
+ If the event handler can resolve the reference, it should return a
+ new docutils node to be inserted in the document tree in place of the node
+ *node*. Usually this node is a :class:`~nodes.reference` node containing
+ *contnode* as a child.
+ If the handler can not resolve the cross-reference,
+ it can either return ``None`` to let other handlers try,
+ or raise :class:`~sphinx.errors.NoUri` to prevent other handlers in
+ trying and suppress a warning about this cross-reference being unresolved.
+
+ :param env: The build environment (``app.builder.env``).
+ :param node: The :class:`~sphinx.addnodes.pending_xref` node to be resolved.
+ Its ``reftype``, ``reftarget``, ``modname`` and ``classname`` attributes
+ determine the type and target of the reference.
+ :param contnode: The node that carries the text and formatting inside the
+ future reference and should be a child of the returned reference node.
+
+ .. versionadded:: 0.5
+
+.. event:: warn-missing-reference (app, domain, node)
+
+ Emitted when a cross-reference to an object cannot be resolved even after
+ :event:`missing-reference`. If the event handler can emit warnings for
+ the missing reference, it should return ``True``. The configuration variables
+ :confval:`nitpick_ignore` and :confval:`nitpick_ignore_regex` prevent the
+ event from being emitted for the corresponding nodes.
+
+ .. versionadded:: 3.4
+
+.. event:: doctree-resolved (app, doctree, docname)
+
+ Emitted when a doctree has been "resolved" by the environment, that is, all
+ references have been resolved and TOCs have been inserted. The *doctree* can
+ be modified in place.
+
+ Here is the place to replace custom nodes that don't have visitor methods in
+ the writers, so that they don't cause errors when the writers encounter them.
+
+.. event:: env-merge-info (app, env, docnames, other)
+
+ This event is only emitted when parallel reading of documents is enabled. It
+ is emitted once for every subprocess that has read some documents.
+
+ You must handle this event in an extension that stores data in the
+ environment in a custom location. Otherwise the environment in the main
+ process will not be aware of the information stored in the subprocess.
+
+ *other* is the environment object from the subprocess, *env* is the
+ environment from the main process. *docnames* is a set of document names
+ that have been read in the subprocess.
+
+ .. versionadded:: 1.3
+
+.. event:: env-updated (app, env)
+
+ Emitted after reading all documents, when the environment and all
+ doctrees are now up-to-date.
+
+ You can return an iterable of docnames from the handler. These documents
+ will then be considered updated, and will be (re-)written during the writing
+ phase.
+
+ .. versionadded:: 0.5
+
+ .. versionchanged:: 1.3
+ The handlers' return value is now used.
+
+.. event:: env-check-consistency (app, env)
+
+ Emitted when Consistency checks phase. You can check consistency of
+ metadata for whole of documents.
+
+ .. versionadded:: 1.6
+
+ As a **experimental** event
+
+.. event:: html-collect-pages (app)
+
+ Emitted when the HTML builder is starting to write non-document pages. You
+ can add pages to write by returning an iterable from this event consisting of
+ ``(pagename, context, templatename)``.
+
+ .. versionadded:: 1.0
+
+.. event:: html-page-context (app, pagename, templatename, context, doctree)
+
+ Emitted when the HTML builder has created a context dictionary to render a
+ template with -- this can be used to add custom elements to the context.
+
+ The *pagename* argument is the canonical name of the page being rendered,
+ that is, without ``.html`` suffix and using slashes as path separators. The
+ *templatename* is the name of the template to render, this will be
+ ``'page.html'`` for all pages from reST documents.
+
+ The *context* argument is a dictionary of values that are given to the
+ template engine to render the page and can be modified to include custom
+ values. Keys must be strings.
+
+ The *doctree* argument will be a doctree when the page is created from a reST
+ documents; it will be ``None`` when the page is created from an HTML template
+ alone.
+
+ You can return a string from the handler, it will then replace
+ ``'page.html'`` as the HTML template for this page.
+
+ .. note:: You can install JS/CSS files for the specific page via
+ :meth:`Sphinx.add_js_file` and :meth:`Sphinx.add_css_file` since
+ v3.5.0.
+
+ .. versionadded:: 0.4
+
+ .. versionchanged:: 1.3
+ The return value can now specify a template name.
+
+.. event:: linkcheck-process-uri (app, uri)
+
+ Emitted when the linkcheck builder collects hyperlinks from document. *uri*
+ is a collected URI. The event handlers can modify the URI by returning a
+ string.
+
+ .. versionadded:: 4.1
+
+.. event:: build-finished (app, exception)
+
+ Emitted when a build has finished, before Sphinx exits, usually used for
+ cleanup. This event is emitted even when the build process raised an
+ exception, given as the *exception* argument. The exception is reraised in
+ the application after the event handlers have run. If the build process
+ raised no exception, *exception* will be ``None``. This allows to customize
+ cleanup actions depending on the exception status.
+
+ .. versionadded:: 0.5
+
+
+Checking the Sphinx version
+---------------------------
+
+.. currentmodule:: sphinx
+
+Use this to adapt your extension to API changes in Sphinx.
+
+.. autodata:: version_info
+
+
+The Config object
+-----------------
+
+.. currentmodule:: sphinx.config
+
+.. autoclass:: Config
+
+
+.. _template-bridge:
+
+The template bridge
+-------------------
+
+.. currentmodule:: sphinx.application
+
+.. autoclass:: TemplateBridge
+ :members:
+
+
+.. _exceptions:
+
+Exceptions
+----------
+
+.. module:: sphinx.errors
+
+.. autoexception:: SphinxError
+
+.. autoexception:: ConfigError
+
+.. autoexception:: ExtensionError
+
+.. autoexception:: ThemeError
+
+.. autoexception:: VersionRequirementError
diff --git a/doc/extdev/builderapi.rst b/doc/extdev/builderapi.rst
new file mode 100644
index 0000000..5c5a525
--- /dev/null
+++ b/doc/extdev/builderapi.rst
@@ -0,0 +1,46 @@
+.. _writing-builders:
+
+Builder API
+===========
+
+.. todo:: Expand this.
+
+.. currentmodule:: sphinx.builders
+
+.. class:: Builder
+
+ This is the base class for all builders.
+
+ These attributes should be set on builder classes:
+
+ .. autoattribute:: name
+ .. autoattribute:: format
+ .. autoattribute:: epilog
+ .. autoattribute:: allow_parallel
+ .. autoattribute:: supported_image_types
+ .. autoattribute:: supported_remote_images
+ .. autoattribute:: supported_data_uri_images
+ .. autoattribute:: default_translator_class
+
+ These methods are predefined and will be called from the application:
+
+ .. automethod:: get_relative_uri
+ .. automethod:: build_all
+ .. automethod:: build_specific
+ .. automethod:: build_update
+ .. automethod:: build
+
+ These methods can be overridden in concrete builder classes:
+
+ .. automethod:: init
+ .. automethod:: get_outdated_docs
+ .. automethod:: get_target_uri
+ .. automethod:: prepare_writing
+ .. automethod:: write_doc
+ .. automethod:: finish
+
+ **Attributes**
+
+ .. attribute:: events
+
+ An :class:`.EventManager` object.
diff --git a/doc/extdev/collectorapi.rst b/doc/extdev/collectorapi.rst
new file mode 100644
index 0000000..cb4c30b
--- /dev/null
+++ b/doc/extdev/collectorapi.rst
@@ -0,0 +1,9 @@
+.. _collector-api:
+
+Environment Collector API
+-------------------------
+
+.. module:: sphinx.environment.collectors
+
+.. autoclass:: EnvironmentCollector
+ :members:
diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst
new file mode 100644
index 0000000..f90389c
--- /dev/null
+++ b/doc/extdev/deprecated.rst
@@ -0,0 +1,1911 @@
+.. _dev-deprecated-apis:
+
+Deprecated APIs
+===============
+
+On developing Sphinx, we are always careful to the compatibility of our APIs.
+But, sometimes, the change of interface are needed for some reasons. In such
+cases, we've marked them as deprecated. And they are kept during the two
+major versions (for more details, please see :ref:`deprecation-policy`).
+
+The following is a list of deprecated interfaces.
+
+.. tabularcolumns:: >{\raggedright}\Y{.4}>{\centering}\Y{.1}>{\sphinxcolorblend{!95!red}\centering\noindent\bfseries\color{red}}\Y{.12}>{\raggedright\arraybackslash}\Y{.38}
+
+.. list-table:: deprecated APIs
+ :header-rows: 1
+ :class: deprecated
+ :widths: 40, 10, 10, 40
+
+ * - Target
+ - Deprecated
+ - Removed
+ - Alternatives
+
+ * - ``sphinx.ext.autodoc.preserve_defaults.get_function_def()``
+ - 7.2
+ - 9.0
+ - N/A (replacement is private)
+
+ * - ``sphinx.builders.html.StandaloneHTMLBuilder.css_files``
+ - 7.2
+ - 9.0
+ - N/A
+
+ * - ``sphinx.builders.html.StandaloneHTMLBuilder.script_files``
+ - 7.2
+ - 9.0
+ - N/A
+
+ * - ``sphinx.builders.html.Stylesheet``
+ - 7.2
+ - 9.0
+ - ``sphinx.application.Sphinx.add_css_file()``
+
+ * - ``sphinx.builders.html.JavaScript``
+ - 7.2
+ - 9.0
+ - ``sphinx.application.Sphinx.add_js_file()``
+
+ * - ``sphinx.util.split_into``
+ - 7.2
+ - 9.0
+ - N/A
+
+ * - ``sphinx.util.split_index_msg``
+ - 7.2
+ - 9.0
+ - ``sphinx.util.index_entries.split_index_msg``
+
+ * - ``sphinx.testing.path``
+ - 7.2
+ - 9.0
+ - ``os.path`` or ``pathlib``
+
+ * - ``sphinx.util.md5``
+ - 7.2
+ - 9.0
+ - ``hashlib.md5``
+
+ * - ``sphinx.util.sha1``
+ - 7.2
+ - 9.0
+ - ``hashlib.sha1``
+
+ * - ``sphinx.util.osutil.cd``
+ - 6.2
+ - 8.0
+ - ``contextlib.chdir``
+
+ * - ``sphinx.util.save_traceback``
+ - 6.1
+ - 8.0
+ - ``sphinx.util.exceptions.save_traceback``
+
+ * - ``sphinx.util.format_exception_cut_frames``
+ - 6.1
+ - 8.0
+ - ``sphinx.util.exceptions.format_exception_cut_frames``
+
+ * - ``sphinx.util.epoch_to_rfc1123``
+ - 6.1
+ - 8.0
+ - ``sphinx.util.http_date.epoch_to_rfc1123``
+
+ * - ``sphinx.util.rfc1123_to_epoch``
+ - 6.1
+ - 8.0
+ - ``sphinx.util.http_date.rfc1123_to_epoch``
+
+ * - ``sphinx.util.status_iterator``
+ - 6.1
+ - 8.0
+ - ``sphinx.util.display.status_iterator``
+
+ * - ``sphinx.util.display_chunk``
+ - 6.1
+ - 8.0
+ - ``sphinx.util.display.display_chunk``
+
+ * - ``sphinx.util.SkipProgressMessage``
+ - 6.1
+ - 8.0
+ - ``sphinx.util.display.SkipProgressMessage``
+
+ * - ``sphinx.util.progress_message``
+ - 6.1
+ - 8.0
+ - ``sphinx.util.display.progress_message``
+
+ * - ``sphinx.util.typing.stringify``
+ - 6.1
+ - 8.0
+ - ``sphinx.util.typing.stringify_annotation``
+
+ * - HTML 4 support
+ - 5.2
+ - 7.0
+ - N/A
+
+ * - ``sphinx.util.path_stabilize``
+ - 5.1
+ - 7.0
+ - ``sphinx.util.osutil.path_stabilize``
+
+ * - ``sphinx.util.get_matching_files``
+ - 5.1
+ - 7.0
+ - ``sphinx.util.matching.get_matching_files``
+
+ * - ``sphinx.ext.napoleon.iterators``
+ - 5.1
+ - 7.0
+ - ``pockets.iterators``
+
+ * - ``sphinx.util.stemmer``
+ - 5.1
+ - 7.0
+ - ``snowballstemmer``
+
+ * - ``sphinx.util.jsdump``
+ - 5.0
+ - 7.0
+ - The standard library ``json`` module.
+
+ * - The Setuptools integration (``setup.py build_sphinx``)
+ - 5.0
+ - 7.0
+ - N/A
+
+ * - The ``locale`` argument of ``sphinx.util.i18n:babel_format_date()``
+ - 5.0
+ - 7.0
+ - N/A
+
+ * - The ``language`` argument of ``sphinx.util.i18n:format_date()``
+ - 5.0
+ - 7.0
+ - N/A
+
+ * - ``sphinx.builders.html.html5_ready``
+ - 5.0
+ - 7.0
+ - N/A
+
+ * - ``sphinx.io.read_doc()``
+ - 5.0
+ - 7.0
+ - ``sphinx.builders.Builder.read_doc()``
+
+ * - ``sphinx.util.docutils.__version_info__``
+ - 5.0
+ - 7.0
+ - ``docutils.__version_info__``
+
+ * - ``sphinx.util.docutils.is_html5_writer_available()``
+ - 5.0
+ - 7.0
+ - N/A
+
+ * - ``sphinx.writers.latex.LaTeXWriter.docclasses``
+ - 5.0
+ - 7.0
+ - N/A
+
+ * - ``sphinx.ext.napoleon.docstring.GoogleDocstring._qualify_name()``
+ - 4.5
+ - 6.0
+ - N/A
+
+ * - ``sphinx.ext.autodoc.AttributeDocumenter._datadescriptor``
+ - 4.3
+ - 6.0
+ - N/A
+
+ * - ``sphinx.writers.html.HTMLTranslator._fieldlist_row_index``
+ - 4.3
+ - 6.0
+ - ``sphinx.writers.html.HTMLTranslator._fieldlist_row_indices``
+
+ * - ``sphinx.writers.html.HTMLTranslator._table_row_index``
+ - 4.3
+ - 6.0
+ - ``sphinx.writers.html.HTMLTranslator._table_row_indices``
+
+ * - ``sphinx.writers.html5.HTML5Translator._fieldlist_row_index``
+ - 4.3
+ - 6.0
+ - ``sphinx.writers.html5.HTML5Translator._fieldlist_row_indices``
+
+ * - ``sphinx.writers.html5.HTML5Translator._table_row_index``
+ - 4.3
+ - 6.0
+ - ``sphinx.writers.html5.HTML5Translator._table_row_indices``
+
+ * - The optional argument ``app`` for ``sphinx.environment.BuildEnvironment``
+ - 4.1
+ - 6.0
+ - The required argument
+
+ * - ``sphinx.application.Sphinx.html_theme``
+ - 4.1
+ - 6.0
+ - ``sphinx.registry.SphinxComponentRegistry.html_themes``
+
+ * - ``sphinx.ext.autosummary._app``
+ - 4.1
+ - 6.0
+ - N/A
+
+ * - ``sphinx.util.docstrings.extract_metadata()``
+ - 4.1
+ - 6.0
+ - ``sphinx.util.docstrings.separate_metadata()``
+
+ * - ``favicon`` variable in HTML templates
+ - 4.0
+ - 6.0
+ - ``favicon_url``
+
+ * - ``logo`` variable in HTML templates
+ - 4.0
+ - 6.0
+ - ``logo_url``
+
+ * - ``sphinx.directives.patches.ListTable``
+ - 4.0
+ - 6.0
+ - ``docutils.parsers.rst.directives.tables.ListSVTable``
+
+ * - ``sphinx.directives.patches.RSTTable``
+ - 4.0
+ - 6.0
+ - ``docutils.parsers.rst.directives.tables.RSTTable``
+
+ * - ``sphinx.ext.autodoc.directive.DocumenterBridge.filename_set``
+ - 4.0
+ - 6.0
+ - ``sphinx.ext.autodoc.directive.DocumenterBridge.record_dependencies``
+
+ * - ``sphinx.ext.autodoc.directive.DocumenterBridge.warn()``
+ - 4.0
+ - 6.0
+ - :ref:`logging-api`
+
+ * - ``sphinx.registry.SphinxComponentRegistry.get_source_input()``
+ - 4.0
+ - 6.0
+ - N/A
+
+ * - ``sphinx.registry.SphinxComponentRegistry.source_inputs``
+ - 4.0
+ - 6.0
+ - N/A
+
+ * - ``sphinx.transforms.FigureAligner``
+ - 4.0
+ - 6.0
+ - N/A
+
+ * - ``sphinx.util.pycompat.convert_with_2to3()``
+ - 4.0
+ - 6.0
+ - N/A
+
+ * - ``sphinx.util.pycompat.execfile_()``
+ - 4.0
+ - 6.0
+ - N/A
+
+ * - ``sphinx.util.smartypants``
+ - 4.0
+ - 6.0
+ - ``docutils.utils.smartquotes``
+
+ * - ``sphinx.util.typing.DirectiveOption``
+ - 4.0
+ - 6.0
+ - N/A
+
+ * - pending_xref node for viewcode extension
+ - 3.5
+ - 5.0
+ - ``sphinx.ext.viewcode.viewcode_anchor``
+
+ * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.anchors_ignore``
+ - 3.5
+ - 5.0
+ - N/A
+
+ * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.auth``
+ - 3.5
+ - 5.0
+ - N/A
+
+ * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.broken``
+ - 3.5
+ - 5.0
+ - N/A
+
+ * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.good``
+ - 3.5
+ - 5.0
+ - N/A
+
+ * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.redirected``
+ - 3.5
+ - 5.0
+ - N/A
+
+ * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.rqueue``
+ - 3.5
+ - 5.0
+ - N/A
+
+ * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.to_ignore``
+ - 3.5
+ - 5.0
+ - N/A
+
+ * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.workers``
+ - 3.5
+ - 5.0
+ - N/A
+
+ * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.wqueue``
+ - 3.5
+ - 5.0
+ - N/A
+
+ * - ``sphinx.builders.linkcheck.node_line_or_0()``
+ - 3.5
+ - 5.0
+ - ``sphinx.util.nodes.get_node_line()``
+
+ * - ``sphinx.ext.autodoc.AttributeDocumenter.isinstanceattribute()``
+ - 3.5
+ - 5.0
+ - N/A
+
+ * - ``sphinx.ext.autodoc.importer.get_module_members()``
+ - 3.5
+ - 5.0
+ - ``sphinx.ext.autodoc.ModuleDocumenter.get_module_members()``
+
+ * - ``sphinx.ext.autosummary.generate._simple_info()``
+ - 3.5
+ - 5.0
+ - :ref:`logging-api`
+
+ * - ``sphinx.ext.autosummary.generate._simple_warn()``
+ - 3.5
+ - 5.0
+ - :ref:`logging-api`
+
+ * - ``sphinx.writers.html.HTMLTranslator.permalink_text``
+ - 3.5
+ - 5.0
+ - :confval:`html_permalinks_icon`
+
+ * - ``sphinx.writers.html5.HTML5Translator.permalink_text``
+ - 3.5
+ - 5.0
+ - :confval:`html_permalinks_icon`
+
+ * - The ``follow_wrapped`` argument of ``sphinx.util.inspect.signature()``
+ - 3.4
+ - 5.0
+ - N/A
+
+ * - The ``no_docstring`` argument of
+ ``sphinx.ext.autodoc.Documenter.add_content()``
+ - 3.4
+ - 5.0
+ - ``sphinx.ext.autodoc.Documenter.get_doc()``
+
+ * - ``sphinx.ext.autodoc.Documenter.get_object_members()``
+ - 3.4
+ - 6.0
+ - ``sphinx.ext.autodoc.ClassDocumenter.get_object_members()``
+
+ * - ``sphinx.ext.autodoc.DataDeclarationDocumenter``
+ - 3.4
+ - 5.0
+ - ``sphinx.ext.autodoc.DataDocumenter``
+
+ * - ``sphinx.ext.autodoc.GenericAliasDocumenter``
+ - 3.4
+ - 5.0
+ - ``sphinx.ext.autodoc.DataDocumenter``
+
+ * - ``sphinx.ext.autodoc.InstanceAttributeDocumenter``
+ - 3.4
+ - 5.0
+ - ``sphinx.ext.autodoc.AttributeDocumenter``
+
+ * - ``sphinx.ext.autodoc.SlotsAttributeDocumenter``
+ - 3.4
+ - 5.0
+ - ``sphinx.ext.autodoc.AttributeDocumenter``
+
+ * - ``sphinx.ext.autodoc.TypeVarDocumenter``
+ - 3.4
+ - 5.0
+ - ``sphinx.ext.autodoc.DataDocumenter``
+
+ * - ``sphinx.ext.autodoc.directive.DocumenterBridge.reporter``
+ - 3.5
+ - 5.0
+ - ``sphinx.util.logging``
+
+ * - ``sphinx.ext.autodoc.importer._getannotations()``
+ - 3.4
+ - 4.0
+ - ``sphinx.util.inspect.getannotations()``
+
+ * - ``sphinx.ext.autodoc.importer._getmro()``
+ - 3.4
+ - 4.0
+ - ``sphinx.util.inspect.getmro()``
+
+ * - ``sphinx.pycode.ModuleAnalyzer.parse()``
+ - 3.4
+ - 5.0
+ - ``sphinx.pycode.ModuleAnalyzer.analyze()``
+
+ * - ``sphinx.util.osutil.movefile()``
+ - 3.4
+ - 5.0
+ - ``os.replace()``
+
+ * - ``sphinx.util.requests.is_ssl_error()``
+ - 3.4
+ - 5.0
+ - N/A
+
+ * - ``sphinx.builders.latex.LaTeXBuilder.usepackages``
+ - 3.3
+ - 5.0
+ - N/A
+
+ * - ``sphinx.builders.latex.LaTeXBuilder.usepackages_afger_hyperref``
+ - 3.3
+ - 5.0
+ - N/A
+
+ * - ``sphinx.ext.autodoc.SingledispatchFunctionDocumenter``
+ - 3.3
+ - 5.0
+ - ``sphinx.ext.autodoc.FunctionDocumenter``
+
+ * - ``sphinx.ext.autodoc.SingledispatchMethodDocumenter``
+ - 3.3
+ - 5.0
+ - ``sphinx.ext.autodoc.MethodDocumenter``
+
+ * - ``sphinx.ext.autodoc.members_set_option()``
+ - 3.2
+ - 5.0
+ - N/A
+
+ * - ``sphinx.ext.autodoc.merge_special_members_option()``
+ - 3.2
+ - 5.0
+ - ``sphinx.ext.autodoc.merge_members_option()``
+
+ * - ``sphinx.writers.texinfo.TexinfoWriter.desc``
+ - 3.2
+ - 5.0
+ - ``sphinx.writers.texinfo.TexinfoWriter.descs``
+
+ * - The first argument for
+ ``sphinx.ext.autosummary.generate.AutosummaryRenderer`` has been changed
+ to Sphinx object
+ - 3.1
+ - 5.0
+ - N/A
+
+ * - ``sphinx.ext.autosummary.generate.AutosummaryRenderer`` takes an object
+ type as an argument
+ - 3.1
+ - 5.0
+ - N/A
+
+ * - The ``ignore`` argument of ``sphinx.ext.autodoc.Documenter.get_doc()``
+ - 3.1
+ - 5.0
+ - N/A
+
+ * - The ``template_dir`` argument of
+ ``sphinx.ext.autosummary.generate.AutosummaryRenderer``
+ - 3.1
+ - 5.0
+ - N/A
+
+ * - The ``module`` argument of
+ ``sphinx.ext.autosummary.generate.find_autosummary_in_docstring()``
+ - 3.0
+ - 5.0
+ - N/A
+
+ * - The ``builder`` argument of
+ ``sphinx.ext.autosummary.generate.generate_autosummary_docs()``
+ - 3.1
+ - 5.0
+ - N/A
+
+ * - The ``template_dir`` argument of
+ ``sphinx.ext.autosummary.generate.generate_autosummary_docs()``
+ - 3.1
+ - 5.0
+ - N/A
+
+ * - ``sphinx.ext.autosummary.generate.AutosummaryRenderer.exists()``
+ - 3.1
+ - 5.0
+ - N/A
+
+ * - The ``ignore`` argument of ``sphinx.util.docstring.prepare_docstring()``
+ - 3.1
+ - 5.0
+ - N/A
+
+ * - ``sphinx.util.rpartition()``
+ - 3.1
+ - 5.0
+ - ``str.rpartition()``
+
+ * - ``desc_signature['first']``
+ -
+ - 3.0
+ - N/A
+
+ * - ``sphinx.directives.DescDirective``
+ - 3.0
+ - 5.0
+ - ``sphinx.directives.ObjectDescription``
+
+ * - ``sphinx.domains.std.StandardDomain.add_object()``
+ - 3.0
+ - 5.0
+ - ``sphinx.domains.std.StandardDomain.note_object()``
+
+ * - ``sphinx.domains.python.PyDecoratorMixin``
+ - 3.0
+ - 5.0
+ - N/A
+
+ * - ``sphinx.ext.autodoc.get_documenters()``
+ - 3.0
+ - 5.0
+ - ``sphinx.registry.documenters``
+
+ * - ``sphinx.ext.autosummary.process_autosummary_toc()``
+ - 3.0
+ - 5.0
+ - N/A
+
+ * - ``sphinx.parsers.Parser.app``
+ - 3.0
+ - 5.0
+ - N/A
+
+ * - ``sphinx.testing.path.Path.text()``
+ - 3.0
+ - 5.0
+ - ``sphinx.testing.path.Path.read_text()``
+
+ * - ``sphinx.testing.path.Path.bytes()``
+ - 3.0
+ - 5.0
+ - ``sphinx.testing.path.Path.read_bytes()``
+
+ * - ``sphinx.util.inspect.getargspec()``
+ - 3.0
+ - 5.0
+ - ``inspect.getargspec()``
+
+ * - ``sphinx.writers.latex.LaTeXWriter.format_docclass()``
+ - 3.0
+ - 5.0
+ - LaTeX Themes
+
+ * - ``decode`` argument of ``sphinx.pycode.ModuleAnalyzer()``
+ - 2.4
+ - 4.0
+ - N/A
+
+ * - ``sphinx.directives.other.Index``
+ - 2.4
+ - 4.0
+ - ``sphinx.domains.index.IndexDirective``
+
+ * - ``sphinx.environment.temp_data['gloss_entries']``
+ - 2.4
+ - 4.0
+ - ``documents.nameids``
+
+ * - ``sphinx.environment.BuildEnvironment.indexentries``
+ - 2.4
+ - 4.0
+ - ``sphinx.domains.index.IndexDomain``
+
+ * - ``sphinx.environment.collectors.indexentries.IndexEntriesCollector``
+ - 2.4
+ - 4.0
+ - ``sphinx.domains.index.IndexDomain``
+
+ * - ``sphinx.io.FiletypeNotFoundError``
+ - 2.4
+ - 4.0
+ - ``sphinx.errors.FiletypeNotFoundError``
+
+ * - ``sphinx.ext.apidoc.INITPY``
+ - 2.4
+ - 4.0
+ - N/A
+
+ * - ``sphinx.ext.apidoc.shall_skip()``
+ - 2.4
+ - 4.0
+ - ``sphinx.ext.apidoc.is_skipped_package``
+
+ * - ``sphinx.io.get_filetype()``
+ - 2.4
+ - 4.0
+ - ``sphinx.util.get_filetype()``
+
+ * - ``sphinx.pycode.ModuleAnalyzer.encoding``
+ - 2.4
+ - 4.0
+ - N/A
+
+ * - ``sphinx.roles.Index``
+ - 2.4
+ - 4.0
+ - ``sphinx.domains.index.IndexRole``
+
+ * - ``sphinx.util.detect_encoding()``
+ - 2.4
+ - 4.0
+ - ``tokenize.detect_encoding()``
+
+ * - ``sphinx.util.get_module_source()``
+ - 2.4
+ - 4.0
+ - N/A
+
+ * - ``sphinx.util.inspect.Signature``
+ - 2.4
+ - 4.0
+ - ``sphinx.util.inspect.signature`` and
+ ``sphinx.util.inspect.stringify_signature()``
+
+ * - ``sphinx.util.inspect.safe_getmembers()``
+ - 2.4
+ - 4.0
+ - ``inspect.getmembers()``
+
+ * - ``sphinx.writers.latex.LaTeXTranslator.settings.author``
+ - 2.4
+ - 4.0
+ - N/A
+
+ * - ``sphinx.writers.latex.LaTeXTranslator.settings.contentsname``
+ - 2.4
+ - 4.0
+ - ``document['contentsname']``
+
+ * - ``sphinx.writers.latex.LaTeXTranslator.settings.docclass``
+ - 2.4
+ - 4.0
+ - ``document['docclass']``
+
+ * - ``sphinx.writers.latex.LaTeXTranslator.settings.docname``
+ - 2.4
+ - 4.0
+ - N/A
+
+ * - ``sphinx.writers.latex.LaTeXTranslator.settings.title``
+ - 2.4
+ - 4.0
+ - N/A
+
+ * - ``sphinx.writers.latex.ADDITIONAL_SETTINGS``
+ - 2.4
+ - 4.0
+ - ``sphinx.builders.latex.constants.ADDITIONAL_SETTINGS``
+
+ * - ``sphinx.writers.latex.DEFAULT_SETTINGS``
+ - 2.4
+ - 4.0
+ - ``sphinx.builders.latex.constants.DEFAULT_SETTINGS``
+
+ * - ``sphinx.writers.latex.LUALATEX_DEFAULT_FONTPKG``
+ - 2.4
+ - 4.0
+ - ``sphinx.builders.latex.constants.LUALATEX_DEFAULT_FONTPKG``
+
+ * - ``sphinx.writers.latex.PDFLATEX_DEFAULT_FONTPKG``
+ - 2.4
+ - 4.0
+ - ``sphinx.builders.latex.constants.PDFLATEX_DEFAULT_FONTPKG``
+
+ * - ``sphinx.writers.latex.XELATEX_DEFAULT_FONTPKG``
+ - 2.4
+ - 4.0
+ - ``sphinx.builders.latex.constants.XELATEX_DEFAULT_FONTPKG``
+
+ * - ``sphinx.writers.latex.XELATEX_GREEK_DEFAULT_FONTPKG``
+ - 2.4
+ - 4.0
+ - ``sphinx.builders.latex.constants.XELATEX_GREEK_DEFAULT_FONTPKG``
+
+ * - ``sphinx.builders.gettext.POHEADER``
+ - 2.3
+ - 4.0
+ - ``sphinx/templates/gettext/message.pot_t`` (template file)
+
+ * - ``sphinx.io.SphinxStandaloneReader.app``
+ - 2.3
+ - 4.0
+ - ``sphinx.io.SphinxStandaloneReader.setup()``
+
+ * - ``sphinx.io.SphinxStandaloneReader.env``
+ - 2.3
+ - 4.0
+ - ``sphinx.io.SphinxStandaloneReader.setup()``
+
+ * - ``sphinx.util.texescape.tex_escape_map``
+ - 2.3
+ - 4.0
+ - ``sphinx.util.texescape.escape()``
+
+ * - ``sphinx.util.texescape.tex_hl_escape_map_new``
+ - 2.3
+ - 4.0
+ - ``sphinx.util.texescape.hlescape()``
+
+ * - ``sphinx.writers.latex.LaTeXTranslator.no_contractions``
+ - 2.3
+ - 4.0
+ - N/A
+
+ * - ``sphinx.domains.math.MathDomain.add_equation()``
+ - 2.2
+ - 4.0
+ - ``sphinx.domains.math.MathDomain.note_equation()``
+
+ * - ``sphinx.domains.math.MathDomain.get_next_equation_number()``
+ - 2.2
+ - 4.0
+ - ``sphinx.domains.math.MathDomain.note_equation()``
+
+ * - The ``info`` and ``warn`` arguments of
+ ``sphinx.ext.autosummary.generate.generate_autosummary_docs()``
+ - 2.2
+ - 4.0
+ - ``logging.info()`` and ``logging.warning()``
+
+ * - ``sphinx.ext.autosummary.generate._simple_info()``
+ - 2.2
+ - 4.0
+ - ``logging.info()``
+
+ * - ``sphinx.ext.autosummary.generate._simple_warn()``
+ - 2.2
+ - 4.0
+ - ``logging.warning()``
+
+ * - ``sphinx.ext.todo.merge_info()``
+ - 2.2
+ - 4.0
+ - ``sphinx.ext.todo.TodoDomain``
+
+ * - ``sphinx.ext.todo.process_todo_nodes()``
+ - 2.2
+ - 4.0
+ - ``sphinx.ext.todo.TodoDomain``
+
+ * - ``sphinx.ext.todo.process_todos()``
+ - 2.2
+ - 4.0
+ - ``sphinx.ext.todo.TodoDomain``
+
+ * - ``sphinx.ext.todo.purge_todos()``
+ - 2.2
+ - 4.0
+ - ``sphinx.ext.todo.TodoDomain``
+
+ * - ``sphinx.builders.latex.LaTeXBuilder.apply_transforms()``
+ - 2.1
+ - 4.0
+ - N/A
+
+ * - ``sphinx.builders._epub_base.EpubBuilder.esc()``
+ - 2.1
+ - 4.0
+ - ``html.escape()``
+
+ * - ``sphinx.directives.Acks``
+ - 2.1
+ - 4.0
+ - ``sphinx.directives.other.Acks``
+
+ * - ``sphinx.directives.Author``
+ - 2.1
+ - 4.0
+ - ``sphinx.directives.other.Author``
+
+ * - ``sphinx.directives.Centered``
+ - 2.1
+ - 4.0
+ - ``sphinx.directives.other.Centered``
+
+ * - ``sphinx.directives.Class``
+ - 2.1
+ - 4.0
+ - ``sphinx.directives.other.Class``
+
+ * - ``sphinx.directives.CodeBlock``
+ - 2.1
+ - 4.0
+ - ``sphinx.directives.code.CodeBlock``
+
+ * - ``sphinx.directives.Figure``
+ - 2.1
+ - 4.0
+ - ``sphinx.directives.patches.Figure``
+
+ * - ``sphinx.directives.HList``
+ - 2.1
+ - 4.0
+ - ``sphinx.directives.other.HList``
+
+ * - ``sphinx.directives.Highlight``
+ - 2.1
+ - 4.0
+ - ``sphinx.directives.code.Highlight``
+
+ * - ``sphinx.directives.Include``
+ - 2.1
+ - 4.0
+ - ``sphinx.directives.other.Include``
+
+ * - ``sphinx.directives.Index``
+ - 2.1
+ - 4.0
+ - ``sphinx.directives.other.Index``
+
+ * - ``sphinx.directives.LiteralInclude``
+ - 2.1
+ - 4.0
+ - ``sphinx.directives.code.LiteralInclude``
+
+ * - ``sphinx.directives.Meta``
+ - 2.1
+ - 4.0
+ - ``sphinx.directives.patches.Meta``
+
+ * - ``sphinx.directives.Only``
+ - 2.1
+ - 4.0
+ - ``sphinx.directives.other.Only``
+
+ * - ``sphinx.directives.SeeAlso``
+ - 2.1
+ - 4.0
+ - ``sphinx.directives.other.SeeAlso``
+
+ * - ``sphinx.directives.TabularColumns``
+ - 2.1
+ - 4.0
+ - ``sphinx.directives.other.TabularColumns``
+
+ * - ``sphinx.directives.TocTree``
+ - 2.1
+ - 4.0
+ - ``sphinx.directives.other.TocTree``
+
+ * - ``sphinx.directives.VersionChange``
+ - 2.1
+ - 4.0
+ - ``sphinx.directives.other.VersionChange``
+
+ * - ``sphinx.domains.python.PyClassmember``
+ - 2.1
+ - 4.0
+ - ``sphinx.domains.python.PyAttribute``,
+ ``sphinx.domains.python.PyMethod``,
+ ``sphinx.domains.python.PyClassMethod``,
+ ``sphinx.domains.python.PyObject`` and
+ ``sphinx.domains.python.PyStaticMethod``
+
+ * - ``sphinx.domains.python.PyModulelevel``
+ - 2.1
+ - 4.0
+ - ``sphinx.domains.python.PyFunction``,
+ ``sphinx.domains.python.PyObject`` and
+ ``sphinx.domains.python.PyVariable``
+
+ * - ``sphinx.domains.std.StandardDomain._resolve_citation_xref()``
+ - 2.1
+ - 4.0
+ - ``sphinx.domains.citation.CitationDomain.resolve_xref()``
+
+ * - ``sphinx.domains.std.StandardDomain.note_citations()``
+ - 2.1
+ - 4.0
+ - ``sphinx.domains.citation.CitationDomain.note_citation()``
+
+ * - ``sphinx.domains.std.StandardDomain.note_citation_refs()``
+ - 2.1
+ - 4.0
+ - ``sphinx.domains.citation.CitationDomain.note_citation_reference()``
+
+ * - ``sphinx.domains.std.StandardDomain.note_labels()``
+ - 2.1
+ - 4.0
+ - ``sphinx.domains.std.StandardDomain.process_doc()``
+
+ * - ``sphinx.domains.js.JSObject.display_prefix``
+ -
+ - 4.3
+ - ``sphinx.domains.js.JSObject.get_display_prefix()``
+
+ * - ``sphinx.environment.NoUri``
+ - 2.1
+ - 3.0
+ - ``sphinx.errors.NoUri``
+
+ * - ``sphinx.ext.apidoc.format_directive()``
+ - 2.1
+ - 4.0
+ - N/A
+
+ * - ``sphinx.ext.apidoc.format_heading()``
+ - 2.1
+ - 4.0
+ - N/A
+
+ * - ``sphinx.ext.apidoc.makename()``
+ - 2.1
+ - 4.0
+ - ``sphinx.ext.apidoc.module_join()``
+
+ * - ``sphinx.ext.autodoc.importer.MockFinder``
+ - 2.1
+ - 4.0
+ - ``sphinx.ext.autodoc.mock.MockFinder``
+
+ * - ``sphinx.ext.autodoc.importer.MockLoader``
+ - 2.1
+ - 4.0
+ - ``sphinx.ext.autodoc.mock.MockLoader``
+
+ * - ``sphinx.ext.autodoc.importer.mock()``
+ - 2.1
+ - 4.0
+ - ``sphinx.ext.autodoc.mock.mock()``
+
+ * - ``sphinx.ext.autosummary.autolink_role()``
+ - 2.1
+ - 4.0
+ - ``sphinx.ext.autosummary.AutoLink``
+
+ * - ``sphinx.ext.imgmath.DOC_BODY``
+ - 2.1
+ - 4.0
+ - N/A
+
+ * - ``sphinx.ext.imgmath.DOC_BODY_PREVIEW``
+ - 2.1
+ - 4.0
+ - N/A
+
+ * - ``sphinx.ext.imgmath.DOC_HEAD``
+ - 2.1
+ - 4.0
+ - N/A
+
+ * - ``sphinx.transforms.CitationReferences``
+ - 2.1
+ - 4.0
+ - ``sphinx.domains.citation.CitationReferenceTransform``
+
+ * - ``sphinx.transforms.SmartQuotesSkipper``
+ - 2.1
+ - 4.0
+ - ``sphinx.domains.citation.CitationDefinitionTransform``
+
+ * - ``sphinx.util.docfields.DocFieldTransformer.preprocess_fieldtypes()``
+ - 2.1
+ - 4.0
+ - ``sphinx.directives.ObjectDescription.get_field_type_map()``
+
+ * - ``sphinx.util.node.find_source_node()``
+ - 2.1
+ - 4.0
+ - ``sphinx.util.node.get_node_source()``
+
+ * - ``sphinx.util.i18n.find_catalog()``
+ - 2.1
+ - 4.0
+ - ``sphinx.util.i18n.docname_to_domain()``
+
+ * - ``sphinx.util.i18n.find_catalog_files()``
+ - 2.1
+ - 4.0
+ - ``sphinx.util.i18n.CatalogRepository``
+
+ * - ``sphinx.util.i18n.find_catalog_source_files()``
+ - 2.1
+ - 4.0
+ - ``sphinx.util.i18n.CatalogRepository``
+
+ * - ``encoding`` argument of ``autodoc.Documenter.get_doc()``,
+ ``autodoc.DocstringSignatureMixin.get_doc()``,
+ ``autodoc.DocstringSignatureMixin._find_signature()``, and
+ ``autodoc.ClassDocumenter.get_doc()``
+ - 2.0
+ - 4.0
+ - N/A
+
+ * - arguments of ``EpubBuilder.build_mimetype()``,
+ ``EpubBuilder.build_container()``, ``EpubBuilder.build_content()``,
+ ``EpubBuilder.build_toc()`` and ``EpubBuilder.build_epub()``
+ - 2.0
+ - 4.0
+ - N/A
+
+ * - arguments of ``Epub3Builder.build_navigation_doc()``
+ - 2.0
+ - 4.0
+ - N/A
+
+ * - ``nodetype`` argument of
+ ``sphinx.search.WordCollector.is_meta_keywords()``
+ - 2.0
+ - 4.0
+ - N/A
+
+ * - ``suffix`` argument of ``BuildEnvironment.doc2path()``
+ - 2.0
+ - 4.0
+ - N/A
+
+ * - string style ``base`` argument of ``BuildEnvironment.doc2path()``
+ - 2.0
+ - 4.0
+ - ``os.path.join()``
+
+ * - ``sphinx.addnodes.abbreviation``
+ - 2.0
+ - 4.0
+ - ``docutils.nodes.abbreviation``
+
+ * - ``sphinx.builders.applehelp``
+ - 2.0
+ - 4.0
+ - ``sphinxcontrib.applehelp``
+
+ * - ``sphinx.builders.devhelp``
+ - 2.0
+ - 4.0
+ - ``sphinxcontrib.devhelp``
+
+ * - ``sphinx.builders.epub3.Epub3Builder.validate_config_value()``
+ - 2.0
+ - 4.0
+ - ``sphinx.builders.epub3.validate_config_values()``
+
+ * - ``sphinx.builders.html.JSONHTMLBuilder``
+ - 2.0
+ - 4.0
+ - ``sphinx.builders.serializinghtml.JSONHTMLBuilder``
+
+ * - ``sphinx.builders.html.PickleHTMLBuilder``
+ - 2.0
+ - 4.0
+ - ``sphinx.builders.serializinghtml.PickleHTMLBuilder``
+
+ * - ``sphinx.builders.html.SerializingHTMLBuilder``
+ - 2.0
+ - 4.0
+ - ``sphinx.builders.serializinghtml.SerializingHTMLBuilder``
+
+ * - ``sphinx.builders.html.SingleFileHTMLBuilder``
+ - 2.0
+ - 4.0
+ - ``sphinx.builders.singlehtml.SingleFileHTMLBuilder``
+
+ * - ``sphinx.builders.html.WebHTMLBuilder``
+ - 2.0
+ - 4.0
+ - ``sphinx.builders.serializinghtml.PickleHTMLBuilder``
+
+ * - ``sphinx.builders.htmlhelp``
+ - 2.0
+ - 4.0
+ - ``sphinxcontrib.htmlhelp``
+
+ * - ``sphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()``
+ - 2.0
+ - 4.0
+ - ``open()``
+
+ * - ``sphinx.builders.qthelp``
+ - 2.0
+ - 4.0
+ - ``sphinxcontrib.qthelp``
+
+ * - ``sphinx.cmd.quickstart.term_decode()``
+ - 2.0
+ - 4.0
+ - N/A
+
+ * - ``sphinx.cmd.quickstart.TERM_ENCODING``
+ - 2.0
+ - 4.0
+ - ``sys.stdin.encoding``
+
+ * - ``sphinx.config.check_unicode()``
+ - 2.0
+ - 4.0
+ - N/A
+
+ * - ``sphinx.config.string_classes``
+ - 2.0
+ - 4.0
+ - ``[str]``
+
+ * - ``sphinx.domains.cpp.DefinitionError.description``
+ - 2.0
+ - 4.0
+ - ``str(exc)``
+
+ * - ``sphinx.domains.cpp.NoOldIdError.description``
+ - 2.0
+ - 4.0
+ - ``str(exc)``
+
+ * - ``sphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded``
+ - 2.0
+ - 4.0
+ - ``str(exc)``
+
+ * - ``sphinx.ext.autosummary.Autosummary.warn()``
+ - 2.0
+ - 4.0
+ - N/A
+
+ * - ``sphinx.ext.autosummary.Autosummary.genopt``
+ - 2.0
+ - 4.0
+ - N/A
+
+ * - ``sphinx.ext.autosummary.Autosummary.warnings``
+ - 2.0
+ - 4.0
+ - N/A
+
+ * - ``sphinx.ext.autosummary.Autosummary.result``
+ - 2.0
+ - 4.0
+ - N/A
+
+ * - ``sphinx.ext.doctest.doctest_encode()``
+ - 2.0
+ - 4.0
+ - N/A
+
+ * - ``sphinx.ext.jsmath``
+ - 2.0
+ - 4.0
+ - ``sphinxcontrib.jsmath``
+
+ * - ``sphinx.roles.abbr_role()``
+ - 2.0
+ - 4.0
+ - ``sphinx.roles.Abbreviation``
+
+ * - ``sphinx.roles.emph_literal_role()``
+ - 2.0
+ - 4.0
+ - ``sphinx.roles.EmphasizedLiteral``
+
+ * - ``sphinx.roles.menusel_role()``
+ - 2.0
+ - 4.0
+ - ``sphinx.roles.GUILabel`` or ``sphinx.roles.MenuSelection``
+
+ * - ``sphinx.roles.index_role()``
+ - 2.0
+ - 4.0
+ - ``sphinx.roles.Index``
+
+ * - ``sphinx.roles.indexmarkup_role()``
+ - 2.0
+ - 4.0
+ - ``sphinx.roles.PEP`` or ``sphinx.roles.RFC``
+
+ * - ``sphinx.testing.util.remove_unicode_literal()``
+ - 2.0
+ - 4.0
+ - N/A
+
+ * - ``sphinx.util.attrdict``
+ - 2.0
+ - 4.0
+ - N/A
+
+ * - ``sphinx.util.force_decode()``
+ - 2.0
+ - 5.0
+ - N/A
+
+ * - ``sphinx.util.get_matching_docs()``
+ - 2.0
+ - 4.0
+ - ``sphinx.util.get_matching_files()``
+
+ * - ``sphinx.util.inspect.Parameter``
+ - 2.0
+ - 3.0
+ - N/A
+
+ * - ``sphinx.util.jsonimpl``
+ - 2.0
+ - 4.0
+ - ``sphinxcontrib.serializinghtml.jsonimpl``
+
+ * - ``sphinx.util.osutil.EEXIST``
+ - 2.0
+ - 4.0
+ - ``errno.EEXIST`` or ``FileExistsError``
+
+ * - ``sphinx.util.osutil.EINVAL``
+ - 2.0
+ - 4.0
+ - ``errno.EINVAL``
+
+ * - ``sphinx.util.osutil.ENOENT``
+ - 2.0
+ - 4.0
+ - ``errno.ENOENT`` or ``FileNotFoundError``
+
+ * - ``sphinx.util.osutil.EPIPE``
+ - 2.0
+ - 4.0
+ - ``errno.ENOENT`` or ``BrokenPipeError``
+
+ * - ``sphinx.util.osutil.walk()``
+ - 2.0
+ - 4.0
+ - ``os.walk()``
+
+ * - ``sphinx.util.pycompat.NoneType``
+ - 2.0
+ - 4.0
+ - ``sphinx.util.typing.NoneType``
+
+ * - ``sphinx.util.pycompat.TextIOWrapper``
+ - 2.0
+ - 4.0
+ - ``io.TextIOWrapper``
+
+ * - ``sphinx.util.pycompat.UnicodeMixin``
+ - 2.0
+ - 4.0
+ - N/A
+
+ * - ``sphinx.util.pycompat.htmlescape()``
+ - 2.0
+ - 4.0
+ - ``html.escape()``
+
+ * - ``sphinx.util.pycompat.indent()``
+ - 2.0
+ - 4.0
+ - ``textwrap.indent()``
+
+ * - ``sphinx.util.pycompat.sys_encoding``
+ - 2.0
+ - 4.0
+ - ``sys.getdefaultencoding()``
+
+ * - ``sphinx.util.pycompat.terminal_safe()``
+ - 2.0
+ - 4.0
+ - ``sphinx.util.console.terminal_safe()``
+
+ * - ``sphinx.util.pycompat.u``
+ - 2.0
+ - 4.0
+ - N/A
+
+ * - ``sphinx.util.PeekableIterator``
+ - 2.0
+ - 4.0
+ - N/A
+
+ * - Omitting the ``filename`` argument in an overriddent
+ ``IndexBuilder.feed()`` method.
+ - 2.0
+ - 4.0
+ - ``IndexBuilder.feed(docname, filename, title, doctree)``
+
+ * - ``sphinx.writers.latex.ExtBabel``
+ - 2.0
+ - 4.0
+ - ``sphinx.builders.latex.util.ExtBabel``
+
+ * - ``sphinx.writers.latex.LaTeXTranslator.babel_defmacro()``
+ - 2.0
+ - 4.0
+ - N/A
+
+ * - ``sphinx.application.Sphinx._setting_up_extension``
+ - 2.0
+ - 3.0
+ - N/A
+
+ * - The ``importer`` argument of ``sphinx.ext.autodoc.importer._MockModule``
+ - 2.0
+ - 3.0
+ - N/A
+
+ * - ``sphinx.ext.autodoc.importer._MockImporter``
+ - 2.0
+ - 3.0
+ - N/A
+
+ * - ``sphinx.io.SphinxBaseFileInput``
+ - 2.0
+ - 3.0
+ - N/A
+
+ * - ``sphinx.io.SphinxFileInput.supported``
+ - 2.0
+ - 3.0
+ - N/A
+
+ * - ``sphinx.io.SphinxRSTFileInput``
+ - 2.0
+ - 3.0
+ - N/A
+
+ * - ``sphinx.registry.SphinxComponentRegistry.add_source_input()``
+ - 2.0
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.latex.LaTeXTranslator._make_visit_admonition()``
+ - 2.0
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.latex.LaTeXTranslator.collect_footnotes()``
+ - 2.0
+ - 4.0
+ - N/A
+
+ * - ``sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()``
+ - 2.0
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.text.TextTranslator._make_depart_admonition()``
+ - 2.0
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.latex.LaTeXTranslator.generate_numfig_format()``
+ - 2.0
+ - 4.0
+ - N/A
+
+ * - :rst:dir:`!highlightlang`
+ - 1.8
+ - 4.0
+ - :rst:dir:`highlight`
+
+ * - :meth:`!add_stylesheet`
+ - 1.8
+ - 6.0
+ - :meth:`~sphinx.application.Sphinx.add_css_file()`
+
+ * - :meth:`!add_javascript()`
+ - 1.8
+ - 4.0
+ - :meth:`~sphinx.application.Sphinx.add_js_file()`
+
+ * - :confval:`autodoc_default_flags`
+ - 1.8
+ - 4.0
+ - :confval:`autodoc_default_options`
+
+ * - ``content`` arguments of ``sphinx.util.image.guess_mimetype()``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``gettext_compact`` arguments of
+ ``sphinx.util.i18n.find_catalog_source_files()``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.io.SphinxI18nReader.set_lineno_for_reporter()``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.io.SphinxI18nReader.line``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.directives.other.VersionChanges``
+ - 1.8
+ - 3.0
+ - ``sphinx.domains.changeset.VersionChanges``
+
+ * - ``sphinx.highlighting.PygmentsBridge.unhighlight()``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``trim_doctest_flags`` arguments of
+ ``sphinx.highlighting.PygmentsBridge``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.ext.mathbase``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.ext.mathbase.MathDomain``
+ - 1.8
+ - 3.0
+ - ``sphinx.domains.math.MathDomain``
+
+ * - ``sphinx.ext.mathbase.MathDirective``
+ - 1.8
+ - 3.0
+ - ``sphinx.directives.patches.MathDirective``
+
+ * - ``sphinx.ext.mathbase.math_role()``
+ - 1.8
+ - 3.0
+ - ``docutils.parsers.rst.roles.math_role()``
+
+ * - ``sphinx.ext.mathbase.setup_math()``
+ - 1.8
+ - 3.0
+ - :meth:`~sphinx.application.Sphinx.add_html_math_renderer()`
+
+ * - ``sphinx.ext.mathbase.is_in_section_title()``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.ext.mathbase.get_node_equation_number()``
+ - 1.8
+ - 3.0
+ - ``sphinx.util.math.get_node_equation_number()``
+
+ * - ``sphinx.ext.mathbase.wrap_displaymath()``
+ - 1.8
+ - 3.0
+ - ``sphinx.util.math.wrap_displaymath()``
+
+ * - ``sphinx.ext.mathbase.math`` (node)
+ - 1.8
+ - 3.0
+ - ``docutils.nodes.math``
+
+ * - ``sphinx.ext.mathbase.displaymath`` (node)
+ - 1.8
+ - 3.0
+ - ``docutils.nodes.math_block``
+
+ * - ``sphinx.ext.mathbase.eqref`` (node)
+ - 1.8
+ - 3.0
+ - ``sphinx.builders.latex.nodes.math_reference``
+
+ * - :confval:`!viewcode_import` (config value)
+ - 1.8
+ - 3.0
+ - :confval:`viewcode_follow_imported_members`
+
+ * - ``sphinx.writers.latex.Table.caption_footnotetexts``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.latex.Table.header_footnotetexts``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.latex.LaTeXTranslator.footnotestack``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.latex.LaTeXTranslator.in_container_literal_block``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.latex.LaTeXTranslator.next_section_ids``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.latex.LaTeXTranslator.restrict_footnote()``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote()``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids()``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids()``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.latex.LaTeXTranslator.bibitems``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.latex.LaTeXTranslator.hlsettingstack``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.latex.ExtBabel.get_shorthandoff()``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.html.HTMLTranslator.highlightlang()``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.html.HTMLTranslator.highlightlang_base()``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.html.HTMLTranslator.highlightlangopts()``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.html.HTMLTranslator.highlightlinenothreshold()``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.html5.HTMLTranslator.highlightlang()``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.html5.HTMLTranslator.highlightlang_base()``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.html5.HTMLTranslator.highlightlangopts()``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold()``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``sphinx.writers.latex.LaTeXTranslator.check_latex_elements()``
+ - 1.8
+ - 3.0
+ - Nothing
+
+ * - ``sphinx.application.CONFIG_FILENAME``
+ - 1.8
+ - 3.0
+ - ``sphinx.config.CONFIG_FILENAME``
+
+ * - ``Config.check_unicode()``
+ - 1.8
+ - 3.0
+ - ``sphinx.config.check_unicode()``
+
+ * - ``Config.check_types()``
+ - 1.8
+ - 3.0
+ - ``sphinx.config.check_confval_types()``
+
+ * - ``dirname``, ``filename`` and ``tags`` arguments of
+ ``Config.__init__()``
+ - 1.8
+ - 3.0
+ - ``Config.read()``
+
+ * - The value of :confval:`html_search_options`
+ - 1.8
+ - 3.0
+ - see :confval:`html_search_options`
+
+ * - ``sphinx.versioning.prepare()``
+ - 1.8
+ - 3.0
+ - ``sphinx.versioning.UIDTransform``
+
+ * - ``Sphinx.override_domain()``
+ - 1.8
+ - 3.0
+ - :meth:`~sphinx.application.Sphinx.add_domain()`
+
+ * - ``Sphinx.import_object()``
+ - 1.8
+ - 3.0
+ - ``sphinx.util.import_object()``
+
+ * - ``suffix`` argument of
+ :meth:`~sphinx.application.Sphinx.add_source_parser()`
+ - 1.8
+ - 3.0
+ - :meth:`~sphinx.application.Sphinx.add_source_suffix()`
+
+
+ * - ``BuildEnvironment.load()``
+ - 1.8
+ - 3.0
+ - ``pickle.load()``
+
+ * - ``BuildEnvironment.loads()``
+ - 1.8
+ - 3.0
+ - ``pickle.loads()``
+
+ * - ``BuildEnvironment.frompickle()``
+ - 1.8
+ - 3.0
+ - ``pickle.load()``
+
+ * - ``BuildEnvironment.dump()``
+ - 1.8
+ - 3.0
+ - ``pickle.dump()``
+
+ * - ``BuildEnvironment.dumps()``
+ - 1.8
+ - 3.0
+ - ``pickle.dumps()``
+
+ * - ``BuildEnvironment.topickle()``
+ - 1.8
+ - 3.0
+ - ``pickle.dump()``
+
+ * - ``BuildEnvironment._nitpick_ignore``
+ - 1.8
+ - 3.0
+ - :confval:`nitpick_ignore`
+
+ * - ``BuildEnvironment.versionchanges``
+ - 1.8
+ - 3.0
+ - N/A
+
+ * - ``BuildEnvironment.update()``
+ - 1.8
+ - 3.0
+ - ``Builder.read()``
+
+ * - ``BuildEnvironment.read_doc()``
+ - 1.8
+ - 3.0
+ - ``Builder.read_doc()``
+
+ * - ``BuildEnvironment._read_serial()``
+ - 1.8
+ - 3.0
+ - ``Builder.read()``
+
+ * - ``BuildEnvironment._read_parallel()``
+ - 1.8
+ - 3.0
+ - ``Builder.read()``
+
+ * - ``BuildEnvironment.write_doctree()``
+ - 1.8
+ - 3.0
+ - ``Builder.write_doctree()``
+
+ * - ``BuildEnvironment.note_versionchange()``
+ - 1.8
+ - 3.0
+ - ``ChangesDomain.note_changeset()``
+
+ * - ``warn()`` (template helper function)
+ - 1.8
+ - 3.0
+ - ``warning()``
+
+ * - :confval:`source_parsers`
+ - 1.8
+ - 3.0
+ - :meth:`~sphinx.application.Sphinx.add_source_parser()`
+
+ * - ``sphinx.util.docutils.directive_helper()``
+ - 1.8
+ - 3.0
+ - ``Directive`` class of docutils
+
+ * - ``sphinx.cmdline``
+ - 1.8
+ - 3.0
+ - ``sphinx.cmd.build``
+
+ * - ``sphinx.make_mode``
+ - 1.8
+ - 3.0
+ - ``sphinx.cmd.make_mode``
+
+ * - ``sphinx.locale.l_()``
+ - 1.8
+ - 3.0
+ - :func:`sphinx.locale._()`
+
+ * - ``sphinx.locale.lazy_gettext()``
+ - 1.8
+ - 3.0
+ - :func:`sphinx.locale._()`
+
+ * - ``sphinx.locale.mygettext()``
+ - 1.8
+ - 3.0
+ - :func:`sphinx.locale._()`
+
+ * - ``sphinx.util.copy_static_entry()``
+ - 1.5
+ - 3.0
+ - ``sphinx.util.fileutil.copy_asset()``
+
+ * - ``sphinx.build_main()``
+ - 1.7
+ - 2.0
+ - ``sphinx.cmd.build.build_main()``
+
+ * - ``sphinx.ext.intersphinx.debug()``
+ - 1.7
+ - 2.0
+ - ``sphinx.ext.intersphinx.inspect_main()``
+
+ * - ``sphinx.ext.autodoc.format_annotation()``
+ - 1.7
+ - 2.0
+ - ``sphinx.util.inspect.Signature``
+
+ * - ``sphinx.ext.autodoc.formatargspec()``
+ - 1.7
+ - 2.0
+ - ``sphinx.util.inspect.Signature``
+
+ * - ``sphinx.ext.autodoc.AutodocReporter``
+ - 1.7
+ - 2.0
+ - ``sphinx.util.docutils.switch_source_input()``
+
+ * - ``sphinx.ext.autodoc.add_documenter()``
+ - 1.7
+ - 2.0
+ - :meth:`~sphinx.application.Sphinx.add_autodocumenter()`
+
+ * - ``sphinx.ext.autodoc.AutoDirective._register``
+ - 1.7
+ - 2.0
+ - :meth:`~sphinx.application.Sphinx.add_autodocumenter()`
+
+ * - ``AutoDirective._special_attrgetters``
+ - 1.7
+ - 2.0
+ - :meth:`~sphinx.application.Sphinx.add_autodoc_attrgetter()`
+
+ * - ``Sphinx.warn()``, ``Sphinx.info()``
+ - 1.6
+ - 2.0
+ - :ref:`logging-api`
+
+ * - ``BuildEnvironment.set_warnfunc()``
+ - 1.6
+ - 2.0
+ - :ref:`logging-api`
+
+ * - ``BuildEnvironment.note_toctree()``
+ - 1.6
+ - 2.0
+ - ``Toctree.note()`` (in ``sphinx.environment.adapters.toctree``)
+
+ * - ``BuildEnvironment.get_toc_for()``
+ - 1.6
+ - 2.0
+ - ``Toctree.get_toc_for()`` (in ``sphinx.environment.adapters.toctree``)
+
+ * - ``BuildEnvironment.get_toctree_for()``
+ - 1.6
+ - 2.0
+ - ``Toctree.get_toctree_for()`` (in ``sphinx.environment.adapters.toctree``)
+
+ * - ``BuildEnvironment.create_index()``
+ - 1.6
+ - 2.0
+ - ``IndexEntries.create_index()`` (in ``sphinx.environment.adapters.indexentries``)
+
+ * - ``sphinx.websupport``
+ - 1.6
+ - 2.0
+ - `sphinxcontrib-websupport`_
+
+ .. _sphinxcontrib-websupport: https://pypi.org/project/sphinxcontrib-websupport/
+
+ * - ``StandaloneHTMLBuilder.css_files``
+ - 1.6
+ - 2.0
+ - :meth:`!add_stylesheet`
+
+ * - ``document.settings.gettext_compact``
+ - 1.8
+ - 1.8
+ - :confval:`gettext_compact`
+
+ * - ``Sphinx.status_iterator()``
+ - 1.6
+ - 1.7
+ - ``sphinx.util.status_iterator()``
+
+ * - ``Sphinx.old_status_iterator()``
+ - 1.6
+ - 1.7
+ - ``sphinx.util.old_status_iterator()``
+
+ * - ``Sphinx._directive_helper()``
+ - 1.6
+ - 1.7
+ - ``sphinx.util.docutils.directive_helper()``
+
+ * - ``sphinx.util.compat.Directive``
+ - 1.6
+ - 1.7
+ - ``docutils.parsers.rst.Directive``
+
+ * - ``sphinx.util.compat.docutils_version``
+ - 1.6
+ - 1.7
+ - ``sphinx.util.docutils.__version_info__``
+
+.. note:: On deprecating on public APIs (internal functions and classes),
+ we also follow the policy as much as possible.
diff --git a/doc/extdev/domainapi.rst b/doc/extdev/domainapi.rst
new file mode 100644
index 0000000..d70b5db
--- /dev/null
+++ b/doc/extdev/domainapi.rst
@@ -0,0 +1,32 @@
+.. _domain-api:
+
+Domain API
+==========
+
+.. module:: sphinx.domains
+
+.. autoclass:: Domain
+ :members:
+
+.. autoclass:: ObjType
+
+.. autoclass:: Index
+ :members:
+
+.. module:: sphinx.directives
+
+.. autoclass:: ObjectDescription
+ :members:
+ :private-members: _toc_entry_name, _object_hierarchy_parts
+
+Python Domain
+-------------
+
+.. module:: sphinx.domains.python
+
+.. autoclass:: PythonDomain
+
+ .. autoattribute:: objects
+ .. autoattribute:: modules
+ .. automethod:: note_object
+ .. automethod:: note_module
diff --git a/doc/extdev/envapi.rst b/doc/extdev/envapi.rst
new file mode 100644
index 0000000..d7ec239
--- /dev/null
+++ b/doc/extdev/envapi.rst
@@ -0,0 +1,58 @@
+Build environment API
+=====================
+
+.. module:: sphinx.environment
+
+.. class:: BuildEnvironment
+
+ **Attributes**
+
+ .. attribute:: app
+
+ Reference to the :class:`.Sphinx` (application) object.
+
+ .. attribute:: config
+
+ Reference to the :class:`.Config` object.
+
+ .. attribute:: project
+
+ Target project. See :class:`.Project`.
+
+ .. attribute:: srcdir
+
+ Source directory.
+
+ .. attribute:: doctreedir
+
+ Directory for storing pickled doctrees.
+
+ .. attribute:: events
+
+ An :class:`.EventManager` object.
+
+ .. attribute:: found_docs
+
+ A set of all existing docnames.
+
+ .. attribute:: metadata
+
+ Dictionary mapping docnames to "metadata" (see :ref:`metadata`).
+
+ .. attribute:: titles
+
+ Dictionary mapping docnames to the docutils node for their main title.
+
+ .. autoattribute:: docname
+
+ **Utility methods**
+
+ .. automethod:: doc2path
+
+ .. automethod:: relfn2path
+
+ .. automethod:: note_dependency
+
+ .. automethod:: new_serialno
+
+ .. automethod:: note_reread
diff --git a/doc/extdev/i18n.rst b/doc/extdev/i18n.rst
new file mode 100644
index 0000000..6b32b8b
--- /dev/null
+++ b/doc/extdev/i18n.rst
@@ -0,0 +1,97 @@
+.. _i18n-api:
+
+i18n API
+========
+
+.. currentmodule:: sphinx.locale
+
+.. autofunction:: init
+
+.. autofunction:: init_console
+
+.. autofunction:: get_translation
+
+.. autofunction:: _
+
+.. autofunction:: __
+
+
+.. _ext-i18n:
+
+Extension internationalization (`i18n`) and localization (`l10n`) using i18n API
+--------------------------------------------------------------------------------
+
+.. versionadded:: 1.8
+
+An extension may naturally come with message translations. This is briefly
+summarized in :func:`sphinx.locale.get_translation` help.
+
+In practice, you have to:
+
+#. Choose a name for your message catalog, which must be unique. Usually
+ the name of your extension is used for the name of message catalog.
+
+#. Mark in your extension sources all messages as translatable, via
+ :func:`sphinx.locale.get_translation` function, usually renamed ``_()``,
+ e.g.:
+
+ .. code-block:: python
+ :caption: src/__init__.py
+
+ from sphinx.locale import get_translation
+
+ MESSAGE_CATALOG_NAME = 'myextension'
+ _ = get_translation(MESSAGE_CATALOG_NAME)
+
+ translated_text = _('Hello Sphinx!')
+
+#. Set up your extension to be aware of its dedicated translations:
+
+ .. code-block:: python
+ :caption: src/__init__.py
+
+ def setup(app):
+ package_dir = path.abspath(path.dirname(__file__))
+ locale_dir = os.path.join(package_dir, 'locales')
+ app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
+
+#. Generate message catalog template ``*.pot`` file, usually in ``locale/``
+ source directory, for example via `Babel`_:
+
+ .. code-block:: console
+
+ $ pybabel extract --output=src/locale/myextension.pot src/
+
+#. Create message catalogs (``*.po``) for each language which your extension
+ will provide localization, for example via `Babel`_:
+
+ .. code-block:: console
+
+ $ pybabel init --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale --locale=fr_FR
+
+#. Translate message catalogs for each language manually
+
+#. Compile message catalogs into ``*.mo`` files, for example via `Babel`_:
+
+ .. code-block:: console
+
+ $ pybabel compile --directory=src/locale --domain=myextension
+
+#. Ensure that message catalog files are distributed when your package will
+ be installed, by adding equivalent line in your extension ``MANIFEST.in``:
+
+ .. code-block:: ini
+ :caption: MANIFEST.in
+
+ recursive-include src *.pot *.po *.mo
+
+
+When the messages on your extension has been changed, you need to also update
+message catalog template and message catalogs, for example via `Babel`_:
+
+.. code-block:: console
+
+ $ pybabel extract --output=src/locale/myextension.pot src/
+ $ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale
+
+.. _Babel: https://babel.pocoo.org/
diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst
new file mode 100644
index 0000000..8332315
--- /dev/null
+++ b/doc/extdev/index.rst
@@ -0,0 +1,218 @@
+.. _dev-extensions:
+
+Sphinx Extensions API
+=====================
+
+Since many projects will need special features in their documentation, Sphinx
+is designed to be extensible on several levels.
+
+Here are a few things you can do in an extension:
+
+* Add new :term:`builder`\s to support new output formats or actions on the
+ parsed documents.
+* Register custom reStructuredText roles and directives, extending the markup
+ using the :doc:`markupapi`.
+* Add custom code to so-called "hook points" at strategic places throughout the
+ build process, allowing you to register a hook and run specialized code.
+ For example, see the :ref:`events`.
+
+An extension is simply a Python module with a ``setup()`` function. A user
+activates the extension by placing the extension's module name
+(or a sub-module) in their :confval:`extensions` configuration value.
+
+When :program:`sphinx-build` is executed, Sphinx will attempt to import each
+module that is listed, and execute ``yourmodule.setup(app)``. This
+function is used to prepare the extension (e.g., by executing Python code),
+linking resources that Sphinx uses in the build process (like CSS or HTML
+files), and notifying Sphinx of everything the extension offers (such
+as directive or role definitions). The ``app`` argument is an instance of
+:class:`.Sphinx` and gives you control over most aspects of the Sphinx build.
+
+.. note::
+
+ The configuration file itself can be treated as an extension if it
+ contains a ``setup()`` function. All other extensions to load must be
+ listed in the :confval:`extensions` configuration value.
+
+The rest of this page describes some high-level aspects of developing
+extensions and various parts of Sphinx's behavior that you can control.
+For some examples of how extensions can be built and used to control different
+parts of Sphinx, see the :ref:`extension-tutorials-index`.
+
+.. _important-objects:
+
+Important objects
+-----------------
+
+There are several key objects whose API you will use while writing an
+extension. These are:
+
+**Application**
+ The application object (usually called ``app``) is an instance of
+ :class:`.Sphinx`. It controls most high-level functionality, such as the
+ setup of extensions, event dispatching and producing output (logging).
+
+ If you have the environment object, the application is available as
+ ``env.app``.
+
+**Environment**
+ The build environment object (usually called ``env``) is an instance of
+ :class:`.BuildEnvironment`. It is responsible for parsing the source
+ documents, stores all metadata about the document collection and is
+ serialized to disk after each build.
+
+ Its API provides methods to do with access to metadata, resolving references,
+ etc. It can also be used by extensions to cache information that should
+ persist for incremental rebuilds.
+
+ If you have the application or builder object, the environment is available
+ as ``app.env`` or ``builder.env``.
+
+**Builder**
+ The builder object (usually called ``builder``) is an instance of a specific
+ subclass of :class:`.Builder`. Each builder class knows how to convert the
+ parsed documents into an output format, or otherwise process them (e.g. check
+ external links).
+
+ If you have the application object, the builder is available as
+ ``app.builder``.
+
+**Config**
+ The config object (usually called ``config``) provides the values of
+ configuration values set in :file:`conf.py` as attributes. It is an instance
+ of :class:`.Config`.
+
+ The config is available as ``app.config`` or ``env.config``.
+
+To see an example of use of these objects, refer to
+:doc:`../development/tutorials/index`.
+
+.. _build-phases:
+
+Build Phases
+------------
+
+One thing that is vital in order to understand extension mechanisms is the way
+in which a Sphinx project is built: this works in several phases.
+
+**Phase 0: Initialization**
+
+In this phase, almost nothing of interest to us happens. The source
+directory is searched for source files, and extensions are initialized.
+Should a stored build environment exist, it is loaded, otherwise a new one is
+created.
+
+**Phase 1: Reading**
+
+In Phase 1, all source files (and on subsequent builds, those that are new or
+changed) are read and parsed. This is the phase where directives and roles
+are encountered by docutils, and the corresponding code is executed. The
+output of this phase is a *doctree* for each source file; that is a tree of
+docutils nodes. For document elements that aren't fully known until all
+existing files are read, temporary nodes are created.
+
+There are nodes provided by docutils, which are documented `in the docutils
+documentation <https://docutils.sourceforge.io/docs/ref/doctree.html>`__.
+Additional nodes are provided by Sphinx and :ref:`documented here <nodes>`.
+
+During reading, the build environment is updated with all meta- and cross
+reference data of the read documents, such as labels, the names of headings,
+described Python objects and index entries. This will later be used to
+replace the temporary nodes.
+
+The parsed doctrees are stored on the disk, because it is not possible to
+hold all of them in memory.
+
+**Phase 2: Consistency checks**
+
+Some checking is done to ensure no surprises in the built documents.
+
+**Phase 3: Resolving**
+
+Now that the metadata and cross-reference data of all existing documents is
+known, all temporary nodes are replaced by nodes that can be converted into
+output using components called transforms. For example, links are created
+for object references that exist, and simple literal nodes are created for
+those that don't.
+
+**Phase 4: Writing**
+
+This phase converts the resolved doctrees to the desired output format, such
+as HTML or LaTeX. This happens via a so-called docutils writer that visits
+the individual nodes of each doctree and produces some output in the process.
+
+.. note::
+
+ Some builders deviate from this general build plan, for example, the builder
+ that checks external links does not need anything more than the parsed
+ doctrees and therefore does not have phases 2--4.
+
+To see an example of application, refer to :doc:`../development/tutorials/todo`.
+
+.. _ext-metadata:
+
+Extension metadata
+------------------
+
+.. versionadded:: 1.3
+
+The ``setup()`` function can return a dictionary. This is treated by Sphinx
+as metadata of the extension. Metadata keys currently recognized are:
+
+* ``'version'``: a string that identifies the extension version. It is used for
+ extension version requirement checking (see :confval:`needs_extensions`) and
+ informational purposes. If not given, ``"unknown version"`` is substituted.
+* ``'env_version'``: an integer that identifies the version of env data
+ structure if the extension stores any data to environment. It is used to
+ detect the data structure has been changed from last build. The extensions
+ have to increment the version when data structure has changed. If not given,
+ Sphinx considers the extension does not stores any data to environment.
+* ``'parallel_read_safe'``: a boolean that specifies if parallel reading of
+ source files can be used when the extension is loaded. It defaults to
+ ``False``, i.e. you have to explicitly specify your extension to be
+ parallel-read-safe after checking that it is.
+
+ .. note:: The *parallel-read-safe* extension must satisfy the following
+ conditions:
+
+ * The core logic of the extension is parallelly executable during
+ the reading phase.
+ * It has event handlers for :event:`env-merge-info` and
+ :event:`env-purge-doc` events if it stores data to the build
+ environment object (env) during the reading phase.
+
+* ``'parallel_write_safe'``: a boolean that specifies if parallel writing of
+ output files can be used when the extension is loaded. Since extensions
+ usually don't negatively influence the process, this defaults to ``True``.
+
+ .. note:: The *parallel-write-safe* extension must satisfy the following
+ conditions:
+
+ * The core logic of the extension is parallelly executable during
+ the writing phase.
+
+
+APIs used for writing extensions
+--------------------------------
+
+These sections provide a more complete description of the tools at your
+disposal when developing Sphinx extensions. Some are core to Sphinx
+(such as the :doc:`appapi`) while others trigger specific behavior
+(such as the :doc:`i18n`)
+
+.. toctree::
+ :maxdepth: 2
+
+ appapi
+ projectapi
+ envapi
+ builderapi
+ collectorapi
+ markupapi
+ domainapi
+ parserapi
+ nodes
+ logging
+ i18n
+ utils
+ deprecated
diff --git a/doc/extdev/logging.rst b/doc/extdev/logging.rst
new file mode 100644
index 0000000..e6c4dc6
--- /dev/null
+++ b/doc/extdev/logging.rst
@@ -0,0 +1,66 @@
+.. _logging-api:
+
+Logging API
+===========
+
+.. currentmodule:: sphinx.util.logging
+
+.. autofunction:: getLogger(name)
+
+.. autoclass:: SphinxLoggerAdapter(logging.LoggerAdapter)
+
+ .. method:: SphinxLoggerAdapter.error(msg, *args, **kwargs)
+ .. method:: SphinxLoggerAdapter.critical(msg, *args, **kwargs)
+ .. method:: SphinxLoggerAdapter.warning(msg, *args, **kwargs)
+
+ Logs a message on this logger with the specified level.
+ Basically, the arguments are as with python's logging module.
+
+ In addition, Sphinx logger supports following keyword arguments:
+
+ **type**, ***subtype***
+ Categories of warning logs. It is used to suppress
+ warnings by :confval:`suppress_warnings` setting.
+
+ **location**
+ Where the warning happened. It is used to include
+ the path and line number in each log. It allows docname,
+ tuple of docname and line number and nodes::
+
+ logger = sphinx.util.logging.getLogger(__name__)
+ logger.warning('Warning happened!', location='index')
+ logger.warning('Warning happened!', location=('chapter1/index', 10))
+ logger.warning('Warning happened!', location=some_node)
+
+ **color**
+ The color of logs. By default, error level logs are colored as
+ ``"darkred"``, critical level ones is not colored, and warning level
+ ones are colored as ``"red"``.
+
+ .. method:: SphinxLoggerAdapter.log(level, msg, *args, **kwargs)
+ .. method:: SphinxLoggerAdapter.info(msg, *args, **kwargs)
+ .. method:: SphinxLoggerAdapter.verbose(msg, *args, **kwargs)
+ .. method:: SphinxLoggerAdapter.debug(msg, *args, **kwargs)
+
+ Logs a message to this logger with the specified level.
+ Basically, the arguments are as with python's logging module.
+
+ In addition, Sphinx logger supports following keyword arguments:
+
+ **nonl**
+ If true, the logger does not fold lines at the end of the log message.
+ The default is ``False``.
+
+ **location**
+ Where the message emitted. For more detail, see
+ :meth:`SphinxLoggerAdapter.warning`.
+
+ **color**
+ The color of logs. By default, info and verbose level logs are not
+ colored, and debug level ones are colored as ``"darkgray"``.
+
+.. autofunction:: pending_logging()
+
+.. autofunction:: pending_warnings()
+
+.. autofunction:: prefixed_warnings()
diff --git a/doc/extdev/markupapi.rst b/doc/extdev/markupapi.rst
new file mode 100644
index 0000000..072760c
--- /dev/null
+++ b/doc/extdev/markupapi.rst
@@ -0,0 +1,152 @@
+Docutils markup API
+===================
+
+This section describes the API for adding ReST markup elements (roles and
+directives).
+
+Roles
+-----
+
+
+Directives
+----------
+
+Directives are handled by classes derived from
+``docutils.parsers.rst.Directive``. They have to be registered by an extension
+using :meth:`.Sphinx.add_directive` or :meth:`.Sphinx.add_directive_to_domain`.
+
+.. module:: docutils.parsers.rst
+
+.. class:: Directive
+
+ The markup syntax of the new directive is determined by the follow five class
+ attributes:
+
+ .. autoattribute:: required_arguments
+ .. autoattribute:: optional_arguments
+ .. autoattribute:: final_argument_whitespace
+ .. autoattribute:: option_spec
+
+ Option validator functions take a single parameter, the option argument
+ (or ``None`` if not given), and should validate it or convert it to the
+ proper form. They raise :exc:`ValueError` or :exc:`TypeError` to indicate
+ failure.
+
+ There are several predefined and possibly useful validators in the
+ :mod:`docutils.parsers.rst.directives` module.
+
+ .. autoattribute:: has_content
+
+ New directives must implement the :meth:`run` method:
+
+ .. method:: run()
+
+ This method must process the directive arguments, options and content, and
+ return a list of Docutils/Sphinx nodes that will be inserted into the
+ document tree at the point where the directive was encountered.
+
+ Instance attributes that are always set on the directive are:
+
+ .. attribute:: name
+
+ The directive name (useful when registering the same directive class under
+ multiple names).
+
+ .. attribute:: arguments
+
+ The arguments given to the directive, as a list.
+
+ .. attribute:: options
+
+ The options given to the directive, as a dictionary mapping option names
+ to validated/converted values.
+
+ .. attribute:: content
+
+ The directive content, if given, as a :class:`!ViewList`.
+
+ .. attribute:: lineno
+
+ The absolute line number on which the directive appeared. This is not
+ always a useful value; use :attr:`srcline` instead.
+
+ .. attribute:: content_offset
+
+ Internal offset of the directive content. Used when calling
+ ``nested_parse`` (see below).
+
+ .. attribute:: block_text
+
+ The string containing the entire directive.
+
+ .. attribute:: state
+ state_machine
+
+ The state and state machine which controls the parsing. Used for
+ ``nested_parse``.
+
+
+ViewLists
+^^^^^^^^^
+
+Docutils represents document source lines in a class
+``docutils.statemachine.ViewList``. This is a list with extended functionality
+-- for one, slicing creates views of the original list, and also the list
+contains information about the source line numbers.
+
+The :attr:`Directive.content` attribute is a ViewList. If you generate content
+to be parsed as ReST, you have to create a ViewList yourself. Important for
+content generation are the following points:
+
+* The constructor takes a list of strings (lines) and a source (document) name.
+
+* The ``.append()`` method takes a line and a source name as well.
+
+
+Parsing directive content as ReST
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Many directives will contain more markup that must be parsed. To do this, use
+one of the following APIs from the :meth:`Directive.run` method:
+
+* ``self.state.nested_parse``
+* :func:`sphinx.util.nodes.nested_parse_with_titles` -- this allows titles in
+ the parsed content.
+
+Both APIs parse the content into a given node. They are used like this::
+
+ node = docutils.nodes.paragraph()
+ # either
+ nested_parse_with_titles(self.state, self.result, node)
+ # or
+ self.state.nested_parse(self.result, 0, node)
+
+.. note::
+
+ ``sphinx.util.docutils.switch_source_input()`` allows to change a target file
+ during nested_parse. It is useful to mixed contents. For example, ``sphinx.
+ ext.autodoc`` uses it to parse docstrings::
+
+ from sphinx.util.docutils import switch_source_input
+
+ # Switch source_input between parsing content.
+ # Inside this context, all parsing errors and warnings are reported as
+ # happened in new source_input (in this case, ``self.result``).
+ with switch_source_input(self.state, self.result):
+ node = docutils.nodes.paragraph()
+ self.state.nested_parse(self.result, 0, node)
+
+ .. deprecated:: 1.7
+
+ Until Sphinx 1.6, ``sphinx.ext.autodoc.AutodocReporter`` was used for this
+ purpose. It is replaced by ``switch_source_input()``.
+
+If you don't need the wrapping node, you can use any concrete node type and
+return ``node.children`` from the Directive.
+
+
+.. seealso::
+
+ `Creating directives`_ HOWTO of the Docutils documentation
+
+.. _Creating directives: https://docutils.sourceforge.io/docs/howto/rst-directives.html
diff --git a/doc/extdev/nodes.rst b/doc/extdev/nodes.rst
new file mode 100644
index 0000000..7603763
--- /dev/null
+++ b/doc/extdev/nodes.rst
@@ -0,0 +1,103 @@
+.. _nodes:
+
+Doctree node classes added by Sphinx
+====================================
+
+.. module:: sphinx.addnodes
+
+Nodes for domain-specific object descriptions
+---------------------------------------------
+
+Top-level nodes
+...............
+
+These nodes form the top-most levels of object descriptions.
+
+.. autoclass:: desc
+.. autoclass:: desc_signature
+.. autoclass:: desc_signature_line
+.. autoclass:: desc_content
+.. autoclass:: desc_inline
+
+Nodes for high-level structure in signatures
+............................................
+
+These nodes occur in in non-multiline :py:class:`desc_signature` nodes
+and in :py:class:`desc_signature_line` nodes.
+
+.. autoclass:: desc_name
+.. autoclass:: desc_addname
+
+.. autoclass:: desc_type
+.. autoclass:: desc_returns
+.. autoclass:: desc_parameterlist
+.. autoclass:: desc_parameter
+.. autoclass:: desc_optional
+.. autoclass:: desc_annotation
+
+Nodes for signature text elements
+.................................
+
+These nodes inherit :py:class:`desc_sig_element` and are generally translated
+to ``docutils.nodes.inline`` by :py:class:`!SigElementFallbackTransform`.
+
+Extensions may create additional ``desc_sig_*``-like nodes but in order for
+:py:class:`!SigElementFallbackTransform` to translate them to inline nodes
+automatically, they must be added to :py:data:`SIG_ELEMENTS` via the class
+keyword argument `_sig_element=True` of :py:class:`desc_sig_element`, e.g.:
+
+ .. code-block:: python
+
+ class desc_custom_sig_node(desc_sig_element, _sig_element=True): ...
+
+For backwards compatibility, it is still possible to add the nodes directly
+using ``SIG_ELEMENTS.add(desc_custom_sig_node)``.
+
+.. autodata:: SIG_ELEMENTS
+ :no-value:
+
+.. autoclass:: desc_sig_element
+
+.. autoclass:: desc_sig_space
+.. autoclass:: desc_sig_name
+.. autoclass:: desc_sig_operator
+.. autoclass:: desc_sig_punctuation
+.. autoclass:: desc_sig_keyword
+.. autoclass:: desc_sig_keyword_type
+.. autoclass:: desc_sig_literal_number
+.. autoclass:: desc_sig_literal_string
+.. autoclass:: desc_sig_literal_char
+
+New admonition-like constructs
+------------------------------
+
+.. autoclass:: versionmodified
+.. autoclass:: seealso
+
+Other paragraph-level nodes
+-------------------------------
+
+.. autoclass:: compact_paragraph
+
+New inline nodes
+----------------
+
+.. autoclass:: index
+.. autoclass:: pending_xref
+.. autoclass:: pending_xref_condition
+.. autoclass:: literal_emphasis
+.. autoclass:: download_reference
+
+Special nodes
+-------------
+
+.. autoclass:: only
+.. autoclass:: highlightlang
+
+You should not need to generate the nodes below in extensions.
+
+.. autoclass:: glossary
+.. autoclass:: toctree
+.. autoclass:: start_of_file
+.. autoclass:: productionlist
+.. autoclass:: production
diff --git a/doc/extdev/parserapi.rst b/doc/extdev/parserapi.rst
new file mode 100644
index 0000000..c5db2ac
--- /dev/null
+++ b/doc/extdev/parserapi.rst
@@ -0,0 +1,38 @@
+.. _parser-api:
+
+Parser API
+==========
+
+`The docutils documentation describes`__ parsers as follows:
+
+ The Parser analyzes the input document and creates a node tree
+ representation.
+
+__ https://docutils.sourceforge.io/docs/dev/hacking.html#parsing-the-document
+
+In Sphinx, the parser modules works as same as docutils. The parsers are
+registered to Sphinx by extensions using Application APIs;
+:meth:`.Sphinx.add_source_suffix()` and :meth:`.Sphinx.add_source_parser()`.
+
+The *source suffix* is a mapping from file suffix to file type. For example,
+``.rst`` file is mapped to ``'restructuredtext'`` type. Sphinx uses the
+file type to looking for parsers from registered list. On searching,
+Sphinx refers to the ``Parser.supported`` attribute and picks up a parser
+which contains the file type in the attribute.
+
+The users can override the source suffix mappings using
+:confval:`source_suffix` like following::
+
+ # a mapping from file suffix to file types
+ source_suffix = {
+ '.rst': 'restructuredtext',
+ '.md': 'markdown',
+ }
+
+You should indicate file types your parser supports. This will allow users
+to configure their settings appropriately.
+
+.. module:: sphinx.parsers
+
+.. autoclass:: Parser
+ :members:
diff --git a/doc/extdev/projectapi.rst b/doc/extdev/projectapi.rst
new file mode 100644
index 0000000..238aeb4
--- /dev/null
+++ b/doc/extdev/projectapi.rst
@@ -0,0 +1,9 @@
+.. _project-api:
+
+Project API
+===========
+
+.. currentmodule:: sphinx.project
+
+.. autoclass:: Project
+ :members:
diff --git a/doc/extdev/utils.rst b/doc/extdev/utils.rst
new file mode 100644
index 0000000..e842f30
--- /dev/null
+++ b/doc/extdev/utils.rst
@@ -0,0 +1,37 @@
+Utilities
+=========
+
+Sphinx provides utility classes and functions to develop extensions.
+
+Base classes for components
+---------------------------
+
+These base classes are useful to allow your extensions to obtain Sphinx
+components (e.g. :class:`.Config`, :class:`.BuildEnvironment` and so on) easily.
+
+.. note:: The subclasses of them might not work with bare docutils because they
+ are strongly coupled with Sphinx.
+
+.. autoclass:: sphinx.transforms.SphinxTransform
+ :members:
+
+.. autoclass:: sphinx.transforms.post_transforms.SphinxPostTransform
+ :members:
+
+.. autoclass:: sphinx.util.docutils.SphinxDirective
+ :members:
+
+.. autoclass:: sphinx.util.docutils.SphinxRole
+ :members:
+
+.. autoclass:: sphinx.util.docutils.ReferenceRole
+ :members:
+
+.. autoclass:: sphinx.transforms.post_transforms.images.ImageConverter
+ :members:
+
+Utility components
+------------------
+
+.. autoclass:: sphinx.events.EventManager
+ :members:
diff --git a/doc/faq.rst b/doc/faq.rst
new file mode 100644
index 0000000..85ccb24
--- /dev/null
+++ b/doc/faq.rst
@@ -0,0 +1,354 @@
+.. _faq:
+
+Sphinx FAQ
+==========
+
+This is a list of Frequently Asked Questions about Sphinx. Feel free to
+suggest new entries!
+
+How do I...
+-----------
+
+... create PDF files without LaTeX?
+ `rinohtype`_ provides a PDF builder that can be used as a drop-in
+ replacement for the LaTeX builder.
+
+ .. _rinohtype: https://github.com/brechtm/rinohtype
+
+... get section numbers?
+ They are automatic in LaTeX output; for HTML, give a ``:numbered:`` option to
+ the :rst:dir:`toctree` directive where you want to start numbering.
+
+... customize the look of the built HTML files?
+ Use themes, see :doc:`/usage/theming`.
+
+... add global substitutions or includes?
+ Add them in the :confval:`rst_prolog` or :confval:`rst_epilog` config value.
+
+... display the whole TOC tree in the sidebar?
+ Use the :data:`toctree` callable in a custom layout template, probably in the
+ ``sidebartoc`` block.
+
+... write my own extension?
+ See the :doc:`/development/tutorials/index`.
+
+... convert from my existing docs using MoinMoin markup?
+ The easiest way is to convert to xhtml, then convert `xhtml to reST`_.
+ You'll still need to mark up classes and such, but the headings and code
+ examples come through cleanly.
+
+For many more extensions and other contributed stuff, see the sphinx-contrib_
+repository.
+
+.. _sphinx-contrib: https://github.com/sphinx-contrib/
+
+.. _usingwith:
+
+Using Sphinx with...
+--------------------
+
+Read the Docs
+ `Read the Docs <https://readthedocs.org>`_ is a documentation hosting
+ service based around Sphinx. They will host sphinx documentation, along
+ with supporting a number of other features including version support, PDF
+ generation, and more. The `Getting Started`_ guide is a good place to start.
+
+Epydoc
+ There's a third-party extension providing an `api role`_ which refers to
+ Epydoc's API docs for a given identifier.
+
+Doxygen
+ Michael Jones is developing a reST/Sphinx bridge to doxygen called `breathe
+ <https://github.com/michaeljones/breathe/tree/master>`_.
+
+SCons
+ Glenn Hutchings has written a SCons build script to build Sphinx
+ documentation; it is hosted here:
+ https://bitbucket-archive.softwareheritage.org/projects/zo/zondo/sphinx-scons.html
+
+PyPI
+ Jannis Leidel wrote a `setuptools command
+ <https://pypi.org/project/Sphinx-PyPI-upload/>`_ that automatically
+ uploads Sphinx documentation to the PyPI package documentation area at
+ https://pythonhosted.org/.
+
+GitHub Pages
+ Please add :py:mod:`sphinx.ext.githubpages` to your project. It allows you
+ to publish your document in GitHub Pages. It generates helper files for
+ GitHub Pages on building HTML document automatically.
+
+MediaWiki
+ See `sphinx-wiki`_, a project by Kevin Dunn.
+
+ .. _sphinx-wiki: https://bitbucket-archive.softwareheritage.org/projects/ke/kevindunn/sphinx-wiki.html
+
+Google Analytics
+ You can use a custom ``layout.html`` template, like this:
+
+ .. code-block:: html+jinja
+
+ {% extends "!layout.html" %}
+
+ {%- block extrahead %}
+ {{ super() }}
+ <script>
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'XXX account number XXX']);
+ _gaq.push(['_trackPageview']);
+ </script>
+ {% endblock %}
+
+ {% block footer %}
+ {{ super() }}
+ <div class="footer">This page uses <a href="https://analytics.google.com/">
+ Google Analytics</a> to collect statistics. You can disable it by blocking
+ the JavaScript coming from www.google-analytics.com.
+ <script>
+ (function() {
+ var ga = document.createElement('script');
+ ga.src = ('https:' == document.location.protocol ?
+ 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ ga.setAttribute('async', 'true');
+ document.documentElement.firstChild.appendChild(ga);
+ })();
+ </script>
+ </div>
+ {% endblock %}
+
+
+Google Search
+ To replace Sphinx's built-in search function with Google Search, proceed as
+ follows:
+
+ 1. Go to https://cse.google.com/cse/all to create the Google Search code
+ snippet.
+
+ 2. Copy the code snippet and paste it into ``_templates/searchbox.html`` in
+ your Sphinx project:
+
+ .. code-block:: html+jinja
+
+ <div>
+ <h3>{{ _('Quick search') }}</h3>
+ <script>
+ (function() {
+ var cx = '......';
+ var gcse = document.createElement('script');
+ gcse.async = true;
+ gcse.src = 'https://cse.google.com/cse.js?cx=' + cx;
+ var s = document.getElementsByTagName('script')[0];
+ s.parentNode.insertBefore(gcse, s);
+ })();
+ </script>
+ <gcse:search></gcse:search>
+ </div>
+
+ 3. Add ``searchbox.html`` to the :confval:`html_sidebars` configuration value.
+
+.. _Getting Started: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html
+.. _api role: https://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py
+.. _xhtml to reST: https://docutils.sourceforge.io/sandbox/xhtml2rest/xhtml2rest.py
+
+
+Sphinx vs. Docutils
+-------------------
+
+tl;dr: *docutils* converts reStructuredText to multiple output formats. Sphinx
+builds upon docutils to allow construction of cross-referenced and indexed
+bodies of documentation.
+
+`docutils`__ is a text processing system for converting plain text
+documentation into other, richer formats. As noted in the `docutils
+documentation`__, docutils uses *readers* to read a document, *parsers* for
+parsing plain text formats into an internal tree representation made up of
+different types of *nodes*, and *writers* to output this tree in various
+document formats. docutils provides parsers for one plain text format -
+`reStructuredText`__ - though other, *out-of-tree* parsers have been
+implemented including Sphinx's :doc:`Markdown parser </usage/markdown>`. On the
+other hand, it provides writers for many different formats including HTML,
+LaTeX, man pages, Open Document Format and XML.
+
+docutils exposes all of its functionality through a variety of `front-end
+tools`__, such as ``rst2html``, ``rst2odt`` and ``rst2xml``. Crucially though,
+all of these tools, and docutils itself, are concerned with individual
+documents. They don't support concepts such as cross-referencing, indexing of
+documents, or the construction of a document hierarchy (typically manifesting
+in a table of contents).
+
+Sphinx builds upon docutils by harnessing docutils' readers and parsers and
+providing its own :doc:`/usage/builders/index`. As a result, Sphinx wraps some
+of the *writers* provided by docutils. This allows Sphinx to provide many
+features that would simply not be possible with docutils, such as those
+outlined above.
+
+__ https://docutils.sourceforge.io/
+__ https://docutils.sourceforge.io/docs/dev/hacking.html
+__ https://docutils.sourceforge.io/rst.html
+__ https://docutils.sourceforge.io/docs/user/tools.html
+
+
+.. _epub-faq:
+
+Epub info
+---------
+
+The following list gives some hints for the creation of epub files:
+
+* Split the text into several files. The longer the individual HTML files are,
+ the longer it takes the ebook reader to render them. In extreme cases, the
+ rendering can take up to one minute.
+
+* Try to minimize the markup. This also pays in rendering time.
+
+* For some readers you can use embedded or external fonts using the CSS
+ ``@font-face`` directive. This is *extremely* useful for code listings which
+ are often cut at the right margin. The default Courier font (or variant) is
+ quite wide and you can only display up to 60 characters on a line. If you
+ replace it with a narrower font, you can get more characters on a line. You
+ may even use `FontForge <https://fontforge.github.io/>`_ and create
+ narrow variants of some free font. In my case I get up to 70 characters on a
+ line.
+
+ You may have to experiment a little until you get reasonable results.
+
+* Test the created epubs. You can use several alternatives. The ones I am aware
+ of are Epubcheck_, Calibre_, FBreader_ (although it does not render the CSS),
+ and Bookworm_. For Bookworm, you can download the source from
+ https://code.google.com/archive/p/threepress and run your own local server.
+
+* Large floating divs are not displayed properly.
+ If they cover more than one page, the div is only shown on the first page.
+ In that case you can copy the :file:`epub.css` from the
+ ``sphinx/themes/epub/static/`` directory to your local ``_static/``
+ directory and remove the float settings.
+
+* Files that are inserted outside of the ``toctree`` directive must be manually
+ included. This sometimes applies to appendixes, e.g. the glossary or
+ the indices. You can add them with the :confval:`epub_post_files` option.
+
+* The handling of the epub cover page differs from the reStructuredText
+ procedure which automatically resolves image paths and puts the images
+ into the ``_images`` directory. For the epub cover page put the image in the
+ :confval:`html_static_path` directory and reference it with its full path in
+ the :confval:`epub_cover` config option.
+
+* kindlegen_ command can convert from epub3 resulting file to ``.mobi`` file
+ for Kindle. You can get ``yourdoc.mobi`` under ``_build/epub`` after the
+ following command:
+
+ .. code-block:: bash
+
+ $ make epub
+ $ kindlegen _build/epub/yourdoc.epub
+
+ The kindlegen command doesn't accept documents that have section
+ titles surrounding ``toctree`` directive:
+
+ .. code-block:: rst
+
+ Section Title
+ =============
+
+ .. toctree::
+
+ subdocument
+
+ Section After Toc Tree
+ ======================
+
+ kindlegen assumes all documents order in line, but the resulting document
+ has complicated order for kindlegen::
+
+ ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
+
+ If you get the following error, fix your document structure:
+
+ .. code-block:: none
+
+ Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
+ Error(prcgen):E24001: The table of content could not be built.
+
+.. _Epubcheck: https://github.com/IDPF/epubcheck
+.. _Calibre: https://calibre-ebook.com/
+.. _FBreader: https://fbreader.org/
+.. _Bookworm: https://www.oreilly.com/bookworm/index.html
+.. _kindlegen: https://www.amazon.com/gp/feature.html?docId=1000765211
+
+.. _texinfo-faq:
+
+Texinfo info
+------------
+
+There are two main programs for reading Info files, ``info`` and GNU Emacs. The
+``info`` program has less features but is available in most Unix environments
+and can be quickly accessed from the terminal. Emacs provides better font and
+color display and supports extensive customization (of course).
+
+.. _texinfo-links:
+
+Displaying Links
+~~~~~~~~~~~~~~~~
+
+One noticeable problem you may encounter with the generated Info files is how
+references are displayed. If you read the source of an Info file, a reference
+to this section would look like::
+
+ * note Displaying Links: target-id
+
+In the stand-alone reader, ``info``, references are displayed just as they
+appear in the source. Emacs, on the other-hand, will by default replace
+``*note:`` with ``see`` and hide the ``target-id``. For example:
+
+ :ref:`texinfo-links`
+
+One can disable generation of the inline references in a document
+with :confval:`texinfo_cross_references`. That makes
+an info file more readable with stand-alone reader (``info``).
+
+The exact behavior of how Emacs displays references is dependent on the variable
+``Info-hide-note-references``. If set to the value of ``hide``, Emacs will hide
+both the ``*note:`` part and the ``target-id``. This is generally the best way
+to view Sphinx-based documents since they often make frequent use of links and
+do not take this limitation into account. However, changing this variable
+affects how all Info documents are displayed and most do take this behavior
+into account.
+
+If you want Emacs to display Info files produced by Sphinx using the value
+``hide`` for ``Info-hide-note-references`` and the default value for all other
+Info files, try adding the following Emacs Lisp code to your start-up file,
+``~/.emacs.d/init.el``.
+
+.. code-block:: elisp
+
+ (defadvice info-insert-file-contents (after
+ sphinx-info-insert-file-contents
+ activate)
+ "Hack to make `Info-hide-note-references' buffer-local and
+ automatically set to `hide' iff it can be determined that this file
+ was created from a Texinfo file generated by Docutils or Sphinx."
+ (set (make-local-variable 'Info-hide-note-references)
+ (default-value 'Info-hide-note-references))
+ (save-excursion
+ (save-restriction
+ (widen) (goto-char (point-min))
+ (when (re-search-forward
+ "^Generated by \\(Sphinx\\|Docutils\\)"
+ (save-excursion (search-forward "\x1f" nil t)) t)
+ (set (make-local-variable 'Info-hide-note-references)
+ 'hide)))))
+
+
+Notes
+~~~~~
+
+The following notes may be helpful if you want to create Texinfo files:
+
+- Each section corresponds to a different ``node`` in the Info file.
+
+- Colons (``:``) cannot be properly escaped in menu entries and xrefs.
+ They will be replaced with semicolons (``;``).
+
+- Links to external Info files can be created using the somewhat official URI
+ scheme ``info``. For example::
+
+ info:Texinfo#makeinfo_options
diff --git a/doc/glossary.rst b/doc/glossary.rst
new file mode 100644
index 0000000..e58ce6b
--- /dev/null
+++ b/doc/glossary.rst
@@ -0,0 +1,103 @@
+.. _glossary:
+
+Glossary
+========
+
+.. glossary::
+
+ builder
+ A class (inheriting from :class:`~sphinx.builders.Builder`) that takes
+ parsed documents and performs an action on them. Normally, builders
+ translate the documents to an output format, but it is also possible to
+ use builders that e.g. check for broken links in the documentation, or
+ build coverage information.
+
+ See :doc:`/usage/builders/index` for an overview over Sphinx's built-in
+ builders.
+
+ configuration directory
+ The directory containing :file:`conf.py`. By default, this is the same as
+ the :term:`source directory`, but can be set differently with the **-c**
+ command-line option.
+
+ directive
+ A reStructuredText markup element that allows marking a block of content
+ with special meaning. Directives are supplied not only by docutils, but
+ Sphinx and custom extensions can add their own. The basic directive
+ syntax looks like this:
+
+ .. sourcecode:: rst
+
+ .. directivename:: argument ...
+ :option: value
+
+ Content of the directive.
+
+ See :ref:`rst-directives` for more information.
+
+ document name
+ Since reST source files can have different extensions (some people like
+ ``.txt``, some like ``.rst`` -- the extension can be configured with
+ :confval:`source_suffix`) and different OSes have different path
+ separators, Sphinx abstracts them: :dfn:`document names` are always
+ relative to the :term:`source directory`, the extension is stripped, and
+ path separators are converted to slashes. All values, parameters and such
+ referring to "documents" expect such document names.
+
+ Examples for document names are ``index``, ``library/zipfile``, or
+ ``reference/datamodel/types``. Note that there is no leading or trailing
+ slash.
+
+ domain
+ 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``.
+
+ 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.
+
+ For more information, refer to :doc:`/usage/restructuredtext/domains`.
+
+ 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.
+
+ extension
+ A custom :term:`role`, :term:`directive` or other aspect of Sphinx that
+ allows users to modify any aspect of the build process within Sphinx.
+
+ For more information, refer to :doc:`/usage/extensions/index`.
+
+ master document
+ The document that contains the root :rst:dir:`toctree` directive.
+
+ root document
+ Same as :term:`master document`.
+
+ object
+ The basic building block of Sphinx documentation. Every "object
+ directive" (e.g. :rst:dir:`py:function` or :rst:dir:`object`) creates such
+ a block; and most objects can be cross-referenced to.
+
+ RemoveInSphinxXXXWarning
+ The feature which is warned will be removed in Sphinx-XXX version.
+ It usually caused from Sphinx extensions which is using deprecated.
+ See also :ref:`when-deprecation-warnings-are-displayed`.
+
+ role
+ A reStructuredText markup element that allows marking a piece of text.
+ Like directives, roles are extensible. The basic syntax looks like this:
+ ``:rolename:`content```. See :ref:`rst-inline-markup` for details.
+
+ source directory
+ The directory which, including its subdirectories, contains all source
+ files for one Sphinx project.
+
+ reStructuredText
+ An easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and
+ parser system.
diff --git a/doc/index.rst b/doc/index.rst
new file mode 100644
index 0000000..e9aea1c
--- /dev/null
+++ b/doc/index.rst
@@ -0,0 +1,117 @@
+=======
+Welcome
+=======
+
+.. epigraph:: Sphinx makes it easy to create intelligent and beautiful documentation.
+
+Here are some of Sphinx's major features:
+
+* **Output formats:** HTML (including Windows HTML Help), LaTeX (for printable
+ PDF versions), ePub, Texinfo, manual pages, plain text
+* **Extensive cross-references:** semantic markup and automatic links for
+ functions, classes, citations, glossary terms and similar pieces of
+ information
+* **Hierarchical structure:** easy definition of a document tree, with automatic
+ links to siblings, parents and children
+* **Automatic indices:** general index as well as a language-specific module
+ indices
+* **Code handling:** automatic highlighting using the Pygments_ highlighter
+* **Extensions:** automatic testing of code snippets, inclusion of docstrings
+ from Python modules (API docs) via :ref:`built-in extensions
+ <builtin-extensions>`, and much more functionality via :ref:`third-party
+ extensions <third-party-extensions>`.
+* **Themes:** modify the look and feel of outputs via :doc:`creating themes
+ <development/theming>`, and re-use many :ref:`third-party themes
+ <third-party-themes>`.
+* **Contributed extensions:** dozens of extensions :ref:`contributed by users
+ <third-party-extensions>`; most of them installable from PyPI.
+
+.. _reStructuredText: https://docutils.sourceforge.io/rst.html
+.. _Docutils: https://docutils.sourceforge.io/
+.. _Pygments: https://pygments.org/
+
+Sphinx uses the reStructuredText_ markup language by default, and can read
+:ref:`MyST markdown <markdown>` via third-party extensions. Both of these
+are powerful and straightforward to use, and have functionality
+for complex documentation and publishing workflows. They both build upon
+Docutils_ to parse and write documents.
+
+See below for how to navigate Sphinx's documentation.
+
+.. seealso::
+
+ The `Sphinx documentation Table of Contents <contents.html>`_ has
+ a full list of this site's pages.
+
+.. _get-started:
+
+Get started
+===========
+
+These sections cover the basics of getting started with Sphinx, including
+creating and building your own documentation from scratch.
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Get started
+
+ usage/quickstart
+ usage/installation
+ tutorial/index
+
+.. _user-guides:
+
+User Guides
+===========
+
+These sections cover various topics in using and extending Sphinx for various
+use-cases. They are a comprehensive guide to using Sphinx in many contexts and
+assume more knowledge of Sphinx. If you are new to Sphinx, we recommend
+starting with :ref:`get-started`.
+
+.. toctree::
+ :maxdepth: 2
+ :caption: User Guides
+
+ usage/index
+ development/index
+ latex
+ extdev/index
+
+Community guide
+===============
+
+Sphinx is community supported and welcomes contributions from anybody.
+The sections below should help you get started joining the Sphinx community
+as well as contributing.
+
+See the :doc:`Sphinx contributors' guide <internals/contributing>` if you would
+like to contribute to the project.
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Community
+
+ support
+ internals/index
+ faq
+ authors
+
+Reference guide
+===============
+
+Reference documentation is more complete and programmatic in nature, it is a
+collection of information that can be quickly referenced. If you would like
+usecase-driven documentation, see :ref:`get-started` or :ref:`user-guides`.
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Reference
+
+ man/index
+ usage/configuration
+ usage/extensions/index
+ usage/restructuredtext/index
+ glossary
+ changes
+ examples
diff --git a/doc/internals/code-of-conduct.rst b/doc/internals/code-of-conduct.rst
new file mode 100644
index 0000000..8e31ef0
--- /dev/null
+++ b/doc/internals/code-of-conduct.rst
@@ -0,0 +1,5 @@
+:tocdepth: 2
+
+.. _code_of_conduct:
+
+.. include:: ../../CODE_OF_CONDUCT
diff --git a/doc/internals/contributing.rst b/doc/internals/contributing.rst
new file mode 100644
index 0000000..195f6a5
--- /dev/null
+++ b/doc/internals/contributing.rst
@@ -0,0 +1,332 @@
+======================
+Contributing to Sphinx
+======================
+
+There are many ways you can contribute to Sphinx, be it filing bug reports or
+feature requests, writing new documentation or submitting patches for new or
+fixed behavior. This guide serves to illustrate how you can get started with
+this.
+
+Get help
+--------
+
+The Sphinx community maintains a number of mailing lists and IRC channels.
+
+Stack Overflow with tag `python-sphinx`_
+ Questions and answers about use and development.
+
+sphinx-users <sphinx-users@googlegroups.com>
+ Mailing list for user support.
+
+sphinx-dev <sphinx-dev@googlegroups.com>
+ Mailing list for development related discussions.
+
+#sphinx-doc on irc.libera.chat
+ IRC channel for development questions and user support.
+
+.. _python-sphinx: https://stackoverflow.com/questions/tagged/python-sphinx
+
+Bug Reports and Feature Requests
+--------------------------------
+
+If you have encountered a problem with Sphinx or have an idea for a new
+feature, please submit it to the `issue tracker`_ on GitHub or discuss it
+on the `sphinx-dev`_ mailing list.
+
+For bug reports, please include the output produced during the build process
+and also the log file Sphinx creates after it encounters an unhandled
+exception. The location of this file should be shown towards the end of the
+error message.
+
+Including or providing a link to the source files involved may help us fix the
+issue. If possible, try to create a minimal project that produces the error
+and post that instead.
+
+.. _`issue tracker`: https://github.com/sphinx-doc/sphinx/issues
+.. _`sphinx-dev`: mailto:sphinx-dev@googlegroups.com
+
+
+Contribute code
+---------------
+
+The Sphinx source code is managed using Git and is hosted on `GitHub`__. The
+recommended way for new contributors to submit code to Sphinx is to fork this
+repository and submit a pull request after committing changes to their fork.
+The pull request will then need to be approved by one of the core developers
+before it is merged into the main repository.
+
+.. __: https://github.com/sphinx-doc/sphinx
+
+.. _contribute-get-started:
+
+Getting started
+~~~~~~~~~~~~~~~
+
+Before starting on a patch, we recommend checking for open issues or open a
+fresh issue to start a discussion around a feature idea or a bug. If you feel
+uncomfortable or uncertain about an issue or your changes, feel free to email
+the *sphinx-dev* mailing list.
+
+These are the basic steps needed to start developing on Sphinx.
+
+#. Create an account on GitHub.
+
+#. Fork the main Sphinx repository (`sphinx-doc/sphinx
+ <https://github.com/sphinx-doc/sphinx>`_) using the GitHub interface.
+
+#. Clone the forked repository to your machine. ::
+
+ git clone https://github.com/USERNAME/sphinx
+ cd sphinx
+
+#. Checkout the appropriate branch.
+
+ Sphinx adopts Semantic Versioning 2.0.0 (refs: https://semver.org/ ).
+
+ For changes that preserves backwards-compatibility of API and features,
+ they should be included in the next MINOR release, use the ``A.x`` branch.
+ ::
+
+ git checkout A.x
+
+ For incompatible or other substantial changes that should wait until the
+ next MAJOR release, use the ``master`` branch.
+
+ For urgent release, a new PATCH branch must be branched from the newest
+ release tag (see :doc:`release-process` for detail).
+
+#. Setup a virtual environment.
+
+ This is not necessary for unit testing, thanks to ``tox``, but it is
+ necessary if you wish to run ``sphinx-build`` locally or run unit tests
+ without the help of ``tox``::
+
+ virtualenv ~/.venv
+ . ~/.venv/bin/activate
+ pip install -e .
+
+#. Create a new working branch. Choose any name you like. ::
+
+ git checkout -b feature-xyz
+
+#. Hack, hack, hack.
+
+ Write your code along with tests that shows that the bug was fixed or that
+ the feature works as expected.
+
+#. Add a bullet point to :file:`CHANGES` if the fix or feature is not trivial
+ (small doc updates, typo fixes), then commit::
+
+ git commit -m '#42: Add useful new feature that does this.'
+
+ GitHub recognizes certain phrases that can be used to automatically
+ update the issue tracker. For example::
+
+ git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
+
+ would close issue #42.
+
+#. Push changes in the branch to your forked repository on GitHub::
+
+ git push origin feature-xyz
+
+#. Submit a pull request from your branch to the respective branch (``master``
+ or ``A.x``).
+
+#. Wait for a core developer to review your changes.
+
+Coding style
+~~~~~~~~~~~~
+
+Please follow these guidelines when writing code for Sphinx:
+
+* Try to use the same code style as used in the rest of the project.
+
+* For non-trivial changes, please update the :file:`CHANGES` file. If your
+ changes alter existing behavior, please document this.
+
+* New features should be documented. Include examples and use cases where
+ appropriate. If possible, include a sample that is displayed in the
+ generated output.
+
+* When adding a new configuration variable, be sure to document it and update
+ :file:`sphinx/cmd/quickstart.py` if it's important enough.
+
+* Add appropriate unit tests.
+
+Style and type checks can be run as follows::
+
+ ruff .
+ mypy sphinx/
+
+Unit tests
+~~~~~~~~~~
+
+Sphinx is tested using `pytest`__ for Python code and `Karma`__ for JavaScript.
+
+.. __: https://docs.pytest.org/en/latest/
+.. __: https://karma-runner.github.io
+
+To run Python unit tests, we recommend using ``tox``, which provides a number
+of targets and allows testing against multiple different Python environments:
+
+* To list all possible targets::
+
+ tox -av
+
+* To run unit tests for a specific Python version, such as Python 3.10::
+
+ tox -e py310
+
+* To run unit tests for a specific Python version and turn on deprecation
+ warnings so they're shown in the test output::
+
+ PYTHONWARNINGS=error tox -e py310
+
+* Arguments to ``pytest`` can be passed via ``tox``, e.g., in order to run a
+ particular test::
+
+ tox -e py310 tests/test_module.py::test_new_feature
+
+You can also test by installing dependencies in your local environment::
+
+ pip install .[test]
+
+To run JavaScript tests, use ``npm``::
+
+ npm install
+ npm run test
+
+New unit tests should be included in the ``tests`` directory where
+necessary:
+
+* For bug fixes, first add a test that fails without your changes and passes
+ after they are applied.
+
+* Tests that need a ``sphinx-build`` run should be integrated in one of the
+ existing test modules if possible. New tests that to ``@with_app`` and
+ then ``build_all`` for a few assertions are not good since *the test suite
+ should not take more than a minute to run*.
+
+.. versionadded:: 1.8
+
+ Sphinx also runs JavaScript tests.
+
+.. versionadded:: 1.6
+
+ ``sphinx.testing`` is added as a experimental.
+
+.. versionchanged:: 1.5.2
+
+ Sphinx was switched from nose to pytest.
+
+.. todo:: The below belongs in the developer guide
+
+Utility functions and pytest fixtures for testing are provided in
+``sphinx.testing``. If you are a developer of Sphinx extensions, you can write
+unit tests by using pytest. At this time, ``sphinx.testing`` will help your
+test implementation.
+
+How to use pytest fixtures that are provided by ``sphinx.testing``? You can
+require ``'sphinx.testing.fixtures'`` in your test modules or ``conftest.py``
+files like this::
+
+ pytest_plugins = 'sphinx.testing.fixtures'
+
+If you want to know more detailed usage, please refer to ``tests/conftest.py``
+and other ``test_*.py`` files under the ``tests`` directory.
+
+
+Contribute documentation
+------------------------
+
+Contributing to documentation involves modifying the source files found in the
+``doc/`` folder. To get started, you should first follow :ref:`contribute-get-started`,
+and then take the steps below to work with the documentation.
+
+The following sections describe how to get started with contributing
+documentation, as well as key aspects of a few different tools that we use.
+
+.. todo:: Add a more extensive documentation contribution guide.
+
+Build the documentation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To build the documentation, run the following command::
+
+ sphinx-build -M html ./doc ./build/sphinx -W --keep-going
+
+This will parse the Sphinx documentation's source files and generate HTML for
+you to preview in ``build/sphinx/html``.
+
+You can also build a **live version of the documentation** that you can preview
+in the browser. It will detect changes and reload the page any time you make
+edits. To do so, run the following command::
+
+ sphinx-autobuild ./doc ./build/sphinx/
+
+Translations
+~~~~~~~~~~~~
+
+The parts of messages in Sphinx that go into builds are translated into several
+locales. The translations are kept as gettext ``.po`` files translated from the
+master template :file:`sphinx/locale/sphinx.pot`.
+
+Sphinx uses `Babel <https://babel.pocoo.org/en/latest/>`_ to extract messages
+and maintain the catalog files. The ``utils`` directory contains a helper
+script, ``babel_runner.py``.
+
+* Use ``python babel_runner.py extract`` to update the ``.pot`` template.
+* Use ``python babel_runner.py update`` to update all existing language
+ catalogs in ``sphinx/locale/*/LC_MESSAGES`` with the current messages in the
+ template file.
+* Use ``python babel_runner.py compile`` to compile the ``.po`` files to binary
+ ``.mo`` files and ``.js`` files.
+
+When an updated ``.po`` file is submitted, run
+``python babel_runner.py compile`` to commit both the source and the compiled
+catalogs.
+
+When a new locale is submitted, add a new directory with the ISO 639-1 language
+identifier and put ``sphinx.po`` in there. Don't forget to update the possible
+values for :confval:`language` in ``doc/usage/configuration.rst``.
+
+The Sphinx core messages can also be translated on `Transifex
+<https://www.transifex.com/sphinx-doc/sphinx-1/>`_. There ``tx`` client tool,
+which is provided by the ``transifex_client`` Python package, can be used to
+pull translations in ``.po`` format from Transifex. To do this, go to
+``sphinx/locale`` and then run ``tx pull -f -l LANG`` where ``LANG`` is an
+existing language identifier. It is good practice to run
+``python babel_runner.py update`` afterwards to make sure the ``.po`` file has the
+canonical Babel formatting.
+
+
+Debugging tips
+--------------
+
+* Delete the build cache before building documents if you make changes in the
+ code by running the command ``make clean`` or using the
+ :option:`sphinx-build -E` option.
+
+* Use the :option:`sphinx-build -P` option to run ``pdb`` on exceptions.
+
+* Use ``node.pformat()`` and ``node.asdom().toxml()`` to generate a printable
+ representation of the document structure.
+
+* Set the configuration variable :confval:`keep_warnings` to ``True`` so
+ warnings will be displayed in the generated output.
+
+* Set the configuration variable :confval:`nitpicky` to ``True`` so that Sphinx
+ will complain about references without a known target.
+
+* Set the debugging options in the `Docutils configuration file
+ <https://docutils.sourceforge.io/docs/user/config.html>`_.
+
+* JavaScript stemming algorithms in ``sphinx/search/non-minified-js/*.js``
+ are generated using `snowball <https://github.com/snowballstem/snowball>`_
+ by cloning the repository, executing ``make dist_libstemmer_js`` and then
+ unpacking the tarball which is generated in ``dist`` directory.
+
+ Minified files in ``sphinx/search/minified-js/*.js`` are generated from
+ non-minified ones using ``uglifyjs`` (installed via npm), with ``-m``
+ option to enable mangling.
diff --git a/doc/internals/index.rst b/doc/internals/index.rst
new file mode 100644
index 0000000..187082e
--- /dev/null
+++ b/doc/internals/index.rst
@@ -0,0 +1,15 @@
+====================
+Contribute to Sphinx
+====================
+
+This guide contains information about the Sphinx open source project itself.
+This is where you can find information about how Sphinx is managed and learn
+how to contribute to the project.
+
+.. toctree::
+ :maxdepth: 2
+
+ contributing
+ release-process
+ organization
+ code-of-conduct
diff --git a/doc/internals/organization.rst b/doc/internals/organization.rst
new file mode 100644
index 0000000..9dec923
--- /dev/null
+++ b/doc/internals/organization.rst
@@ -0,0 +1,56 @@
+==================================
+Organization of the Sphinx project
+==================================
+
+The guide explains how the Sphinx project is organized.
+
+Core developers
+---------------
+
+The core developers of Sphinx have write access to the main repository. They
+can commit changes, accept/reject pull requests, and manage items on the issue
+tracker.
+
+Guidelines
+~~~~~~~~~~
+
+The following are some general guidelines for core developers:
+
+* Questionable or extensive changes should be submitted as a pull request
+ instead of being committed directly to the main repository. The pull
+ request should be reviewed by another core developer before it is merged.
+
+* Trivial changes can be committed directly but be sure to keep the repository
+ in a good working state and that all tests pass before pushing your changes.
+
+* When committing code written by someone else, please attribute the original
+ author in the commit message and any relevant :file:`CHANGES` entry.
+
+Membership
+~~~~~~~~~~
+
+Core membership is predicated on continued active contribution to the project.
+In general, prospective cores should demonstrate:
+
+- a good understanding of one of more components of Sphinx
+
+- a history of helpful, constructive contributions
+
+- a willingness to invest time improving Sphinx
+
+Refer to :doc:`contributing` for more information on how you can get started.
+
+Other contributors
+------------------
+
+You do not need to be a core developer or have write access to be involved in
+the development of Sphinx. You can submit patches or create pull requests
+from forked repositories and have a core developer add the changes for you.
+
+Similarly, contributions are not limited to code patches. We also welcome help
+triaging bugs, input on design decisions, reviews of existing patches and
+documentation improvements. More information can be found in
+:doc:`contributing`.
+
+A list of people that have contributed to Sphinx can be found in
+:doc:`../authors`.
diff --git a/doc/internals/release-process.rst b/doc/internals/release-process.rst
new file mode 100644
index 0000000..50648cd
--- /dev/null
+++ b/doc/internals/release-process.rst
@@ -0,0 +1,125 @@
+========================
+Sphinx's release process
+========================
+
+Versioning
+----------
+
+Sphinx adheres to :pep:`440` versions, with a ``major.minor.micro`` scheme for
+the *release segment* (e.g. 1.2.3).
+The major, minor, and micro version parts should be altered as follows:
+
+* The major version part should be incremented for incompatible behavior change and
+ public API updates.
+
+* The minor version part should be incremented for most releases of Sphinx, where
+ backwards-compatibility of API and features are preserves.
+
+* The micro version part should only be incremented for urgent bugfix-only releases.
+
+When the major version part is incremented, the minor and micro version parts
+must be set to ``0``.
+When the minor version part is incremented, the micro version part must be set
+to ``0``.
+
+New major versions should come with a beta-testing period before the final
+release.
+
+
+Deprecating a feature
+---------------------
+
+There are a couple reasons that code in Sphinx might be deprecated:
+
+* If a feature has been improved or modified in a backwards-incompatible way,
+ the old feature or behavior will be deprecated.
+
+* Sometimes Sphinx will include a backport of a Python library that's not
+ included in a version of Python that Sphinx currently supports. When Sphinx
+ no longer needs to support the older version of Python that doesn't include
+ the library, the library will be deprecated in Sphinx.
+
+As the :ref:`deprecation-policy` describes, the first release of Sphinx that
+deprecates a feature (``A.B``) should raise a ``RemovedInSphinxXXWarning``
+(where ``XX`` is the Sphinx version where the feature will be removed) when the
+deprecated feature is invoked. Assuming we have good test coverage, these
+warnings are converted to errors when running the test suite with warnings
+enabled::
+
+ pytest -Wall
+
+Thus, when adding a ``RemovedInSphinxXXWarning`` you need to eliminate or
+silence any warnings generated when running the tests.
+
+
+.. _deprecation-policy:
+
+Deprecation policy
+------------------
+
+MAJOR and MINOR releases may deprecate certain features from previous
+releases. If a feature is deprecated in a release A.x, it will continue to
+work in all A.x.x versions (for all versions of x). It will continue to work
+in all B.x.x versions but raise deprecation warnings. Deprecated features
+will be removed at the C.0.0. It means the deprecated feature will work during
+2 MAJOR releases at least.
+
+So, for example, if we decided to start the deprecation of a function in
+Sphinx 2.x:
+
+* Sphinx 2.x will contain a backwards-compatible replica of the function
+ which will raise a ``RemovedInSphinx40Warning``.
+ This is a subclass of :exc:`python:PendingDeprecationWarning`, i.e. it
+ will not get displayed by default.
+
+* Sphinx 3.x will still contain the backwards-compatible replica, but
+ ``RemovedInSphinx40Warning`` will be a subclass of
+ :exc:`python:DeprecationWarning` then, and gets displayed by default.
+
+* Sphinx 4.0 will remove the feature outright.
+
+Deprecation warnings
+~~~~~~~~~~~~~~~~~~~~
+
+Sphinx will enable its ``RemovedInNextVersionWarning`` warnings by default, if
+:envvar:`python:PYTHONWARNINGS` is not set. Therefore you can disable them
+using:
+
+* ``PYTHONWARNINGS= make html`` (Linux/Mac)
+* ``export PYTHONWARNINGS=`` and do ``make html`` (Linux/Mac)
+* ``set PYTHONWARNINGS=`` and do ``make html`` (Windows)
+
+But you can also explicitly enable the pending ones using e.g.
+``PYTHONWARNINGS=default`` (see the :ref:`Python docs on configuring warnings
+<python:describing-warning-filters>`) for more details.
+
+Python version support policy
+-----------------------------
+
+Sphinx supports at all minor versions of Python released in the past 42 months
+from the anticipated release date with a minimum of 3 minor versions of Python.
+This policy is derived from `NEP 29`_, a scientific Python domain standard.
+
+.. _NEP 29: https://numpy.org/neps/nep-0029-deprecation_policy.html
+
+For example, a version of Sphinx released in May 2024 would support Python 3.10,
+3.11, and 3.12.
+
+This is a summary table with the current policy:
+
+=========== ======
+Date Python
+=========== ======
+26 Dec 2021 3.8+
+----------- ------
+14 Apr 2023 3.9+
+----------- ------
+05 Apr 2024 3.10+
+----------- ------
+04 Apr 2025 3.11+
+=========== ======
+
+Release procedures
+------------------
+
+The release procedures are listed in ``utils/release-checklist``.
diff --git a/doc/latex.rst b/doc/latex.rst
new file mode 100644
index 0000000..4c9a4e0
--- /dev/null
+++ b/doc/latex.rst
@@ -0,0 +1,1841 @@
+LaTeX customization
+===================
+
+.. module:: latex
+ :synopsis: LaTeX specifics.
+
+.. _contents: https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents
+
+.. raw:: latex
+
+ \begingroup
+ \sphinxsetup{%
+ TitleColor={named}{DarkGoldenrod},
+ pre_border-width=2pt,
+ pre_border-right-width=8pt,
+ pre_padding=5pt,
+ pre_border-radius=5pt,
+ pre_background-TeXcolor={named}{OldLace},
+ pre_border-TeXcolor=Gold!90,
+ pre_box-shadow=6pt 6pt,
+ pre_box-shadow-TeXcolor=gray!20,
+ %
+ div.warning_border-width=3pt,
+ div.warning_padding=6pt,
+ div.warning_padding-right=18pt,
+ div.warning_padding-bottom=18pt,
+ div.warning_border-TeXcolor=DarkCyan,
+ div.warning_background-TeXcolor=LightCyan,
+ div.warning_box-shadow=-12pt -12pt inset,
+ div.warning_box-shadow-TeXcolor=Cyan,
+ %
+ attentionborder=3pt,
+ attentionBorderColor=Crimson,
+ attentionBgColor=FloralWhite,
+ %
+ noteborder=1pt,
+ noteBorderColor=Olive,
+ noteBgColor=Olive!10,
+ div.note_border-top-width=0pt,
+ div.note_border-bottom-width=0pt,
+ hintBorderColor=LightCoral,
+ }
+ \relax
+
+Unlike :ref:`the HTML builders <html-themes>`, the ``latex`` builder does not
+benefit from prepared themes. The :ref:`latex-options`, and particularly the
+:ref:`latex_elements <latex_elements_confval>` variable, provides much of the
+interface for customization. For example:
+
+.. code-block:: latex
+
+ # inside conf.py
+ latex_engine = 'xelatex'
+ latex_elements = {
+ 'fontpkg': r'''
+ \setmainfont{DejaVu Serif}
+ \setsansfont{DejaVu Sans}
+ \setmonofont{DejaVu Sans Mono}
+ ''',
+ 'preamble': r'''
+ \usepackage[titles]{tocloft}
+ \cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm}
+ \setlength{\cftchapnumwidth}{0.75cm}
+ \setlength{\cftsecindent}{\cftchapnumwidth}
+ \setlength{\cftsecnumwidth}{1.25cm}
+ ''',
+ 'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
+ 'printindex': r'\footnotesize\raggedright\printindex',
+ }
+ latex_show_urls = 'footnote'
+
+.. note::
+
+ Keep in mind that backslashes must be doubled in Python string literals to
+ avoid interpretation as escape sequences. Alternatively, you may use raw
+ strings as is done above.
+
+.. _latex_elements_confval:
+
+The ``latex_elements`` configuration setting
+--------------------------------------------
+
+A dictionary that contains LaTeX snippets overriding those Sphinx usually puts
+into the generated ``.tex`` files. Its ``'sphinxsetup'`` key is described
+:ref:`separately <latexsphinxsetup>`. It allows also local configurations
+inserted in generated files, via :dudir:`raw` directives. For example, in
+the PDF documentation this chapter is styled especially, as will be described
+later.
+
+Keys that you may want to override include:
+
+``'papersize'``
+ Paper size option of the document class (``'a4paper'`` or
+ ``'letterpaper'``)
+
+ Default: ``'letterpaper'``
+
+``'pointsize'``
+ Point size option of the document class (``'10pt'``, ``'11pt'`` or
+ ``'12pt'``)
+
+ Default: ``'10pt'``
+
+``'pxunit'``
+ The value of the ``px`` when used in image attributes ``width`` and
+ ``height``. The default value is ``'0.75bp'`` which achieves
+ ``96px=1in`` (in TeX ``1in = 72bp = 72.27pt``.) To obtain for
+ example ``100px=1in`` use ``'0.01in'`` or ``'0.7227pt'`` (the latter
+ leads to TeX computing a more precise value, due to the smaller unit
+ used in the specification); for ``72px=1in``, simply use ``'1bp'``; for
+ ``90px=1in``, use ``'0.8bp'`` or ``'0.803pt'``.
+
+ Default: ``'0.75bp'``
+
+ .. versionadded:: 1.5
+
+``'passoptionstopackages'``
+ A string which will be positioned early in the preamble, designed to
+ contain ``\\PassOptionsToPackage{options}{foo}`` commands.
+
+ .. hint::
+
+ It may be also used for loading LaTeX packages very early in the
+ preamble. For example package ``fancybox`` is incompatible with
+ being loaded via the ``'preamble'`` key, it must be loaded earlier.
+
+ Default: ``''``
+
+ .. versionadded:: 1.4
+
+``'babel'``
+ "babel" package inclusion, default ``'\\usepackage{babel}'`` (the
+ suitable document language string is passed as class option, and
+ ``english`` is used if no language.) For Japanese documents, the
+ default is the empty string.
+
+ With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document to use
+ `polyglossia`_, but one should be aware that current `babel`_ has
+ improved its support for Unicode engines in recent years and for some
+ languages it may make sense to prefer ``babel`` over ``polyglossia``.
+
+ .. _`polyglossia`: https://ctan.org/pkg/polyglossia
+ .. _`babel`: https://ctan.org/pkg/babel
+
+ .. hint::
+
+ After modifying a core LaTeX key like this one, clean up the LaTeX
+ build repertory before next PDF build, else left-over auxiliary
+ files are likely to break the build.
+
+ Default: ``'\\usepackage{babel}'`` (``''`` for Japanese documents)
+
+ .. versionchanged:: 1.5
+ For :confval:`latex_engine` set to ``'xelatex'``, the default
+ is ``'\\usepackage{polyglossia}\n\\setmainlanguage{<language>}'``.
+
+ .. versionchanged:: 1.6
+ ``'lualatex'`` uses same default setting as ``'xelatex'``
+
+ .. versionchanged:: 1.7.6
+ For French, ``xelatex`` and ``lualatex`` default to using
+ ``babel``, not ``polyglossia``.
+
+``'fontpkg'``
+ Font package inclusion. The default is::
+
+ r"""\usepackage{tgtermes}
+ \usepackage{tgheros}
+ \renewcommand\ttdefault{txtt}
+ """
+
+ For ``'xelatex'`` and ``'lualatex'`` however the default is to use
+ the GNU FreeFont.
+
+ .. versionchanged:: 1.2
+ Defaults to ``''`` when the :confval:`language` uses the Cyrillic
+ script.
+
+ .. versionchanged:: 2.0
+ Incorporates some font substitution commands to help support occasional
+ Greek or Cyrillic in a document using ``'pdflatex'`` engine.
+
+ .. versionchanged:: 4.0.0
+
+ - The font substitution commands added at ``2.0`` have been moved
+ to the ``'fontsubstitution'`` key, as their presence here made
+ it complicated for user to customize the value of ``'fontpkg'``.
+ - The default font setting has changed: it still uses Times and
+ Helvetica clones for serif and sans serif, but via better, more
+ complete TeX fonts and associated LaTeX packages. The
+ monospace font has been changed to better match the Times clone.
+
+``'fncychap'``
+ Inclusion of the "fncychap" package (which makes fancy chapter titles),
+ default ``'\\usepackage[Bjarne]{fncychap}'`` for English documentation
+ (this option is slightly customized by Sphinx),
+ ``'\\usepackage[Sonny]{fncychap}'`` for internationalized docs (because
+ the "Bjarne" style uses numbers spelled out in English). Other
+ "fncychap" styles you can try are "Lenny", "Glenn", "Conny", "Rejne" and
+ "Bjornstrup". You can also set this to ``''`` to disable fncychap.
+
+ Default: ``'\\usepackage[Bjarne]{fncychap}'`` for English documents,
+ ``'\\usepackage[Sonny]{fncychap}'`` for internationalized documents, and
+ ``''`` for Japanese documents.
+
+``'preamble'``
+ Additional preamble content. One may move all needed macros into some file
+ :file:`mystyle.tex.txt` of the project source repertory, and get LaTeX to
+ import it at run time::
+
+ 'preamble': r'\input{mystyle.tex.txt}',
+ # or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty
+ 'preamble': r'\usepackage{mystyle}',
+
+ It is then needed to set appropriately :confval:`latex_additional_files`,
+ for example:
+
+ .. code-block:: python
+
+ latex_additional_files = ["mystyle.sty"]
+
+ Do not use ``.tex`` as suffix, else the file is submitted itself to the PDF
+ build process, use ``.tex.txt`` or ``.sty`` as in the examples above.
+
+ Default: ``''``
+
+``'figure_align'``
+ Latex figure float alignment. Whenever an image doesn't fit into the current
+ page, it will be 'floated' into the next page but may be preceded by any
+ other text. If you don't like this behavior, use 'H' which will disable
+ floating and position figures strictly in the order they appear in the
+ source.
+
+ Default: ``'htbp'`` (here, top, bottom, page)
+
+ .. versionadded:: 1.3
+
+``'atendofbody'``
+ Additional document content (right before the indices).
+
+ Default: ``''``
+
+ .. versionadded:: 1.5
+
+``'extrapackages'``
+ Additional LaTeX packages. For example:
+
+ .. code-block:: latex
+
+ latex_elements = {
+ 'extrapackages': r'\usepackage{isodate}'
+ }
+
+ The specified LaTeX packages will be loaded before
+ hyperref package and packages loaded from Sphinx extensions.
+
+ .. hint::
+ If you'd like to load additional LaTeX packages after hyperref, use
+ ``'preamble'`` key instead.
+
+ Default: ``''``
+
+ .. versionadded:: 2.3
+
+``'footer'``
+ Additional footer content (before the indices).
+
+ Default: ``''``
+
+ .. deprecated:: 1.5
+ Use ``'atendofbody'`` key instead.
+
+Keys that don't need to be overridden unless in special cases are:
+
+``'extraclassoptions'``
+ The default is the empty string. Example: ``'extraclassoptions':
+ 'openany'`` will allow chapters (for documents of the ``'manual'``
+ type) to start on any page.
+
+ Default: ``''``
+
+ .. versionadded:: 1.2
+
+ .. versionchanged:: 1.6
+ Added this documentation.
+
+``'maxlistdepth'``
+ LaTeX allows by default at most 6 levels for nesting list and
+ quote-like environments, with at most 4 enumerated lists, and 4 bullet
+ lists. Setting this key for example to ``'10'`` (as a string) will
+ allow up to 10 nested levels (of all sorts). Leaving it to the empty
+ string means to obey the LaTeX default.
+
+ .. warning::
+
+ - Using this key may prove incompatible with some LaTeX packages
+ or special document classes which do their own list customization.
+
+ - The key setting is silently *ignored* if ``\usepackage{enumitem}``
+ is executed inside the document preamble. Use then rather the
+ dedicated commands of this LaTeX package.
+
+ Default: ``6``
+
+ .. versionadded:: 1.5
+
+``'inputenc'``
+ "inputenc" package inclusion.
+
+ Default: ``'\\usepackage[utf8]{inputenc}'`` when using pdflatex, else
+ ``''``.
+
+ .. note::
+
+ If using ``utf8x`` in place of ``utf8`` it is mandatory to extend the
+ LaTeX preamble with suitable ``\PreloadUnicodePage{<number>}`` commands,
+ as per the ``utf8x`` documentation (``texdoc ucs`` on a TeXLive based
+ TeX installation). Else, unexpected and possibly hard-to-spot problems
+ (i.e. not causing a build crash) may arise in the PDF, in particular
+ regarding hyperlinks.
+
+ Even if these precautions are taken, PDF build via ``pdflatex`` engine
+ may crash due to upstream LaTeX not being fully compatible with
+ ``utf8x``. For example, in certain circumstances related to
+ code-blocks, or attempting to include images whose filenames contain
+ Unicode characters. Indeed, starting in 2015, upstream LaTeX with
+ ``pdflatex`` engine has somewhat enhanced native support for Unicode and
+ is becoming more and more incompatible with ``utf8x``. In particular,
+ since the October 2019 LaTeX release, filenames can use Unicode
+ characters, and even spaces. At Sphinx level this means e.g. that the
+ :dudir:`image` and :dudir:`figure` directives are now compatible with
+ such filenames for PDF via LaTeX output. But this is broken if
+ ``utf8x`` is in use.
+
+ .. versionchanged:: 1.4.3
+ Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all
+ compilers.
+
+``'cmappkg'``
+ "cmap" package inclusion.
+
+ Default: ``'\\usepackage{cmap}'``
+
+ .. versionadded:: 1.2
+
+``'fontenc'``
+ Customize this from its default ``'\\usepackage[T1]{fontenc}'`` to:
+
+ - ``'\\usepackage[X2,T1]{fontenc}'`` if you need occasional
+ Cyrillic letters (физика частиц),
+
+ - ``'\\usepackage[LGR,T1]{fontenc}'`` if you need occasional
+ Greek letters (Σωματιδιακή φυσική).
+
+ Use ``[LGR,X2,T1]`` rather if both are needed.
+
+ .. attention::
+
+ - Do not use this key for a :confval:`latex_engine` other than
+ ``'pdflatex'``.
+
+ - If Greek is main language, do not use this key. Since Sphinx 2.2.1,
+ ``xelatex`` will be used automatically as :confval:`latex_engine`.
+
+ - The TeX installation may need some extra packages. For example,
+ on Ubuntu xenial, packages ``texlive-lang-greek`` and ``cm-super``
+ are needed for ``LGR`` to work. And ``texlive-lang-cyrillic`` and
+ ``cm-super`` are needed for support of Cyrillic.
+
+ .. versionchanged:: 1.5
+ Defaults to ``'\\usepackage{fontspec}'`` when
+ :confval:`latex_engine` is ``'xelatex'``.
+
+ .. versionchanged:: 1.6
+ ``'lualatex'`` uses ``fontspec`` per default like ``'xelatex'``.
+
+ .. versionchanged:: 2.0
+ ``'lualatex'`` executes
+ ``\defaultfontfeatures[\rmfamily,\sffamily]{}`` to disable TeX
+ ligatures transforming `<<` and `>>` as escaping working with
+ ``pdflatex/xelatex`` failed with ``lualatex``.
+
+ .. versionchanged:: 2.0
+ Detection of ``LGR``, ``T2A``, ``X2`` to trigger support of
+ occasional Greek or Cyrillic letters (``'pdflatex'``).
+
+ .. versionchanged:: 2.3.0
+ ``'xelatex'`` executes
+ ``\defaultfontfeatures[\rmfamily,\sffamily]{}`` in order to avoid
+ contractions of ``--`` into en-dash or transforms of straight quotes
+ into curly ones in PDF (in non-literal text paragraphs) despite
+ :confval:`smartquotes` being set to ``False``.
+
+``'fontsubstitution'``
+ Ignored if ``'fontenc'`` was not configured to use ``LGR`` or ``X2`` (or
+ ``T2A``). In case ``'fontpkg'`` key is configured for usage with some
+ TeX fonts known to be available in the ``LGR`` or ``X2`` encodings, set
+ this one to be the empty string. Else leave to its default.
+
+ Ignored with :confval:`latex_engine` other than ``'pdflatex'``.
+
+ .. versionadded:: 4.0.0
+
+``'textgreek'``
+ For the support of occasional Greek letters.
+
+ It is ignored with ``'platex'``, ``'xelatex'`` or ``'lualatex'`` as
+ :confval:`latex_engine` and defaults to either the empty string or
+ to ``'\\usepackage{textalpha}'`` for ``'pdflatex'`` depending on
+ whether the ``'fontenc'`` key was used with ``LGR`` or not. Only
+ expert LaTeX users may want to customize this key.
+
+ It can also be used as ``r'\usepackage{textalpha,alphabeta}'`` to let
+ ``'pdflatex'`` support Greek Unicode input in :rst:dir:`math` context.
+ For example ``:math:`α``` (U+03B1) will render as :math:`\alpha`.
+
+ Default: ``'\\usepackage{textalpha}'`` or ``''`` if ``fontenc`` does not
+ include the ``LGR`` option.
+
+ .. versionadded:: 2.0
+
+``'geometry'``
+ "geometry" package inclusion, the default definition is:
+
+ .. code:: latex
+
+ '\\usepackage{geometry}'
+
+ with an additional ``[dvipdfm]`` for Japanese documents.
+ The Sphinx LaTeX style file executes:
+
+ .. code:: latex
+
+ \PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry}
+
+ which can be customized via corresponding :ref:`'sphinxsetup' options
+ <latexsphinxsetup>`.
+
+ Default: ``'\\usepackage{geometry}'`` (or
+ ``'\\usepackage[dvipdfm]{geometry}'`` for Japanese documents)
+
+ .. versionadded:: 1.5
+
+ .. versionchanged:: 1.5.2
+ ``dvipdfm`` option if :confval:`latex_engine` is ``'platex'``.
+
+ .. versionadded:: 1.5.3
+ The :ref:`'sphinxsetup' keys for the margins
+ <latexsphinxsetuphmargin>`.
+
+ .. versionchanged:: 1.5.3
+ The location in the LaTeX file has been moved to after
+ ``\usepackage{sphinx}`` and ``\sphinxsetup{..}``, hence also after
+ insertion of ``'fontpkg'`` key. This is in order to handle the paper
+ layout options in a special way for Japanese documents: the text
+ width will be set to an integer multiple of the *zenkaku* width, and
+ the text height to an integer multiple of the baseline. See the
+ :ref:`hmargin <latexsphinxsetuphmargin>` documentation for more.
+
+``'hyperref'``
+ "hyperref" package inclusion; also loads package "hypcap" and issues
+ ``\urlstyle{same}``. This is done after :file:`sphinx.sty` file is
+ loaded and before executing the contents of ``'preamble'`` key.
+
+ .. attention::
+
+ Loading of packages "hyperref" and "hypcap" is mandatory.
+
+ .. versionadded:: 1.5
+ Previously this was done from inside :file:`sphinx.sty`.
+
+``'maketitle'``
+ "maketitle" call. Override if you want to generate a differently styled
+ title page.
+
+ .. hint::
+
+ If the key value is set to
+ ``r'\newcommand\sphinxbackoftitlepage{<Extra
+ material>}\sphinxmaketitle'``, then ``<Extra material>`` will be
+ typeset on back of title page (``'manual'`` docclass only).
+
+ Default: ``'\\sphinxmaketitle'``
+
+ .. versionchanged:: 1.8.3
+ Original ``\maketitle`` from document class is not overwritten,
+ hence is re-usable as part of some custom setting for this key.
+
+ .. versionadded:: 1.8.3
+ ``\sphinxbackoftitlepage`` optional macro. It can also be defined
+ inside ``'preamble'`` key rather than this one.
+
+``'releasename'``
+ Value that prefixes ``'release'`` element on title page. As for *title* and
+ *author* used in the tuples of :confval:`latex_documents`, it is inserted as
+ LaTeX markup.
+
+ Default: ``'Release'``
+
+``'tableofcontents'``
+ "tableofcontents" call. The default of ``'\\sphinxtableofcontents'`` is a
+ wrapper of unmodified ``\tableofcontents``, which may itself be customized
+ by user loaded packages. Override if you want to generate a different table
+ of contents or put content between the title page and the TOC.
+
+ Default: ``'\\sphinxtableofcontents'``
+
+ .. versionchanged:: 1.5
+ Previously the meaning of ``\tableofcontents`` itself was modified
+ by Sphinx. This created an incompatibility with dedicated packages
+ modifying it also such as "tocloft" or "etoc".
+
+``'transition'``
+ Commands used to display transitions. Override if you want to display
+ transitions differently.
+
+ Default: ``'\n\n\\bigskip\\hrule\\bigskip\n\n'``
+
+ .. versionadded:: 1.2
+
+ .. versionchanged:: 1.6
+ Remove unneeded ``{}`` after ``\\hrule``.
+
+``'makeindex'``
+ "makeindex" call, the last thing before ``\begin{document}``. With
+ ``'\\usepackage[columns=1]{idxlayout}\\makeindex'`` the index will use
+ only one column. You may have to install ``idxlayout`` LaTeX package.
+
+ Default: ``'\\makeindex'``
+
+``'printindex'``
+ "printindex" call, the last thing in the file. Override if you want to
+ generate the index differently, append some content after the index, or
+ change the font. As LaTeX uses two-column mode for the index it is
+ often advisable to set this key to
+ ``'\\footnotesize\\raggedright\\printindex'``. Or, to obtain a one-column
+ index, use ``'\\def\\twocolumn[#1]{#1}\\printindex'`` (this trick may fail
+ if using a custom document class; then try the ``idxlayout`` approach
+ described in the documentation of the ``'makeindex'`` key).
+
+ Default: ``'\\printindex'``
+
+``'fvset'``
+ Customization of ``fancyvrb`` LaTeX package.
+
+ The default value is ``'\\fvset{fontsize=auto}'`` which means that the
+ font size will adjust correctly if a code-block ends up in a footnote.
+ You may need to modify this if you use custom fonts:
+ ``'\\fvset{fontsize=\\small}'`` if the monospace font is Courier-like.
+
+ Default: ``'\\fvset{fontsize=auto}'``
+
+ .. versionadded:: 1.8
+
+ .. versionchanged:: 2.0
+ For ``'xelatex'`` and ``'lualatex'`` defaults to
+ ``'\\fvset{fontsize=\\small}'`` as this
+ is adapted to the relative widths of the FreeFont family.
+
+ .. versionchanged:: 4.0.0
+ Changed default for ``'pdflatex'``. Previously it was using
+ ``'\\fvset{fontsize=\\small}'``.
+
+ .. versionchanged:: 4.1.0
+ Changed default for Chinese documents to
+ ``'\\fvset{fontsize=\\small,formatcom=\\xeCJKVerbAddon}'``
+
+Keys that are set by other options and therefore should not be overridden are:
+
+``'docclass'``
+``'classoptions'``
+``'title'``
+``'release'``
+``'author'``
+
+
+.. _latexsphinxsetup:
+
+The ``sphinxsetup`` configuration setting
+-----------------------------------------
+
+.. versionadded:: 1.5
+
+The ``'sphinxsetup'`` key of :ref:`latex_elements <latex_elements_confval>`
+provides a LaTeX-type customization interface::
+
+ latex_elements = {
+ 'sphinxsetup': 'key1=value1, key2=value2, ...',
+ }
+
+It defaults to empty. If non-empty, it will be passed as argument to the
+``\sphinxsetup`` macro inside the document preamble, like this::
+
+ \usepackage{sphinx}
+ \sphinxsetup{key1=value1, key2=value2,...}
+
+The colors used in the above are provided by the ``svgnames`` option of the
+"xcolor" package::
+
+ latex_elements = {
+ 'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
+ }
+
+It is possible to insert uses of the ``\sphinxsetup`` LaTeX macro directly
+into the body of the document, via the ``raw`` directive. This chapter is
+styled in the PDF output using the following insertion at its start. This
+uses keys described later in :ref:`additionalcss`.
+
+.. code-block:: latex
+
+ .. raw:: latex
+
+ \begingroup
+ \sphinxsetup{%
+ TitleColor={named}{DarkGoldenrod},
+ % pre_border-width is 5.1.0 alias for verbatimborder
+ pre_border-width=2pt,
+ pre_border-right-width=8pt,
+ % pre_padding is a 5.1.0 alias for verbatimsep
+ pre_padding=5pt,
+ % Rounded boxes are new at 5.1.0
+ pre_border-radius=5pt,
+ % TeXcolor reminds that syntax must be as for LaTeX \definecolor
+ pre_background-TeXcolor={named}{OldLace},
+ % ... and since 5.3.0 also xcolor \colorlet syntax is accepted and we
+ % can thus drop the {named}{...} thing if xcolor is available!
+ pre_border-TeXcolor=Gold,
+ % ... and even take more advantage of xcolor syntax:
+ pre_border-TeXcolor=Gold!90,
+ % add a shadow to code-blocks
+ pre_box-shadow=6pt 6pt,
+ pre_box-shadow-TeXcolor=gray!20,
+ %
+ % This 5.1.0 CSS-named option is alias for warningborder
+ div.warning_border-width=3pt,
+ % Prior to 5.1.0, padding for admonitions was not customizable
+ div.warning_padding=6pt,
+ div.warning_padding-right=18pt,
+ div.warning_padding-bottom=18pt,
+ % Assume xcolor has been loaded with its svgnames option
+ div.warning_border-TeXcolor=DarkCyan,
+ div.warning_background-TeXcolor=LightCyan,
+ % This one is the only option with space separated input:
+ div.warning_box-shadow=-12pt -12pt inset,
+ div.warning_box-shadow-TeXcolor=Cyan,
+ %
+ % The 5.1.0 new name would be div.attention_border-width
+ attentionborder=3pt,
+ % The 5.1.0 name here would be div.attention_border-TeXcolor
+ attentionBorderColor=Crimson,
+ % The 5.1.0 name would be div.attention_background-TeXcolor
+ attentionBgColor=FloralWhite,
+ %
+ % For note/hint/important/tip, the CSS syntax was added at 6.2.0
+ % Legacy syntax still works
+ noteborder=1pt,
+ noteBorderColor=Olive,
+ % But setting a background color via the new noteBgColor means that
+ % it will be rendered using the same interface as warning type
+ noteBgColor=Olive!10,
+ % We can customize separately the four border-widths, and mimic
+ % the legacy "light" rendering, but now with a background color:
+ % div.note_border-left-width=0pt,
+ % div.note_border-right-width=0pt,
+ % Let's rather for variety use lateral borders:
+ div.note_border-top-width=0pt,
+ div.note_border-bottom-width=0pt,
+ %
+ % As long as only border width and border color are set, *and* using
+ % for this the old interface, the rendering will be the "light" one
+ hintBorderColor=LightCoral,
+ % but if we had used div.hint_border-TeXcolor or *any* CSS-named
+ % option we would have triggered the more complex "heavybox" code.
+ }
+
+
+And this is placed at the end of the chapter source to end the scope of
+the configuration:
+
+.. code-block:: latex
+
+ .. raw:: latex
+
+ \endgroup
+
+LaTeX syntax for boolean keys requires *lowercase* ``true`` or ``false``
+e.g ``'sphinxsetup': "verbatimwrapslines=false"``. If setting the
+boolean key to ``true``, ``=true`` is optional.
+Spaces around the commas and equal signs are ignored, spaces inside LaTeX
+macros may be significant.
+Do not use quotes to enclose values, whether numerical or strings.
+
+``bookmarksdepth``
+ Controls the depth of the collapsible bookmarks panel in the PDF.
+ May be either a number (e.g. ``3``) or a LaTeX sectioning name (e.g.
+ ``subsubsection``, i.e. without backslash).
+ For details, refer to the ``hyperref`` LaTeX docs.
+
+ Default: ``5``
+
+ .. versionadded:: 4.0.0
+
+.. _latexsphinxsetuphmargin:
+
+``hmargin, vmargin``
+ The dimensions of the horizontal (resp. vertical) margins, passed as
+ ``hmargin`` (resp. ``vmargin``) option to the ``geometry`` package.
+ Example::
+
+ 'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in',
+
+ Japanese documents currently accept only the one-dimension format for
+ these parameters. The ``geometry`` package is then passed suitable options
+ to get the text width set to an exact multiple of the *zenkaku* width, and
+ the text height set to an integer multiple of the baselineskip, with the
+ closest fit for the margins.
+
+ Default: ``1in`` (equivalent to ``{1in,1in}``)
+
+ .. hint::
+
+ For Japanese ``'manual'`` docclass with pointsize ``11pt`` or ``12pt``,
+ use the ``nomag`` extra document class option (cf.
+ ``'extraclassoptions'`` key of :confval:`latex_elements`) or so-called
+ TeX "true" units::
+
+ 'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw',
+
+ .. versionadded:: 1.5.3
+
+``marginpar``
+ The ``\marginparwidth`` LaTeX dimension. For Japanese documents, the value
+ is modified to be the closest integer multiple of the *zenkaku* width.
+
+ Default: ``0.5in``
+
+ .. versionadded:: 1.5.3
+
+``verbatimwithframe``
+ Boolean to specify if :rst:dir:`code-block`\ s and literal includes are
+ framed. Setting it to ``false`` does not deactivate use of package
+ "framed", because it is still in use for the optional background color.
+
+ Default: ``true``.
+
+``verbatimwrapslines``
+ Boolean to specify if long lines in :rst:dir:`code-block`\ 's contents are
+ wrapped.
+
+ If ``true``, line breaks may happen at spaces (the last space before the
+ line break will be rendered using a special symbol), and at ascii
+ punctuation characters (i.e. not at letters or digits). Whenever a long
+ string has no break points, it is moved to next line. If its length is
+ longer than the line width it will overflow.
+
+ Default: ``true``
+
+.. _latexsphinxsetupforcewraps:
+
+``verbatimforcewraps``
+ Boolean to specify if long lines in :rst:dir:`code-block`\ 's contents
+ should be forcefully wrapped to never overflow due to long strings.
+
+ .. note::
+
+ It is assumed that the Pygments_ LaTeXFormatter has not been used with
+ its ``texcomments`` or similar options which allow additional
+ (arbitrary) LaTeX mark-up.
+
+ Also, in case of :confval:`latex_engine` set to ``'pdflatex'``, only
+ the default LaTeX handling of Unicode code points, i.e. ``utf8`` not
+ ``utf8x`` is allowed.
+
+ .. _Pygments: https://pygments.org/
+
+ Default: ``false``
+
+ .. versionadded:: 3.5.0
+
+``verbatimmaxoverfull``
+ A number. If an unbreakable long string has length larger than the total
+ linewidth plus this number of characters, and if ``verbatimforcewraps``
+ mode is on, the input line will be reset using the forceful algorithm
+ which applies breakpoints at each character.
+
+ Default: ``3``
+
+ .. versionadded:: 3.5.0
+
+``verbatimmaxunderfull``
+ A number. If ``verbatimforcewraps`` mode applies, and if after applying
+ the line wrapping at spaces and punctuation, the first part of the split
+ line is lacking at least that number of characters to fill the available
+ width, then the input line will be reset using the forceful algorithm.
+
+ As the default is set to a high value, the forceful algorithm is triggered
+ only in overfull case, i.e. in presence of a string longer than full
+ linewidth. Set this to ``0`` to force all input lines to be hard wrapped
+ at the current available linewidth::
+
+ latex_elements = {
+ 'sphinxsetup': "verbatimforcewraps, verbatimmaxunderfull=0",
+ }
+
+ This can be done locally for a given code-block via the use of raw latex
+ directives to insert suitable ``\sphinxsetup`` (before and after) into the
+ latex file.
+
+ Default: ``100``
+
+ .. versionadded:: 3.5.0
+
+``verbatimhintsturnover``
+ Boolean to specify if code-blocks display "continued on next page" and
+ "continued from previous page" hints in case of page breaks.
+
+ Default: ``true``
+
+ .. versionadded:: 1.6.3
+ .. versionchanged:: 1.7
+ the default changed from ``false`` to ``true``.
+
+``verbatimcontinuedalign``, ``verbatimcontinuesalign``
+ Horizontal position relative to the framed contents: either ``l`` (left
+ aligned), ``r`` (right aligned) or ``c`` (centered).
+
+ Default: ``r``
+
+ .. versionadded:: 1.7
+
+``parsedliteralwraps``
+ Boolean to specify if long lines in :dudir:`parsed-literal`\ 's contents
+ should wrap.
+
+ Default: ``true``
+
+ .. versionadded:: 1.5.2
+ set this option value to ``false`` to recover former behavior.
+
+``inlineliteralwraps``
+ Boolean to specify if line breaks are allowed inside inline literals: but
+ extra potential break-points (additionally to those allowed by LaTeX at
+ spaces or for hyphenation) are currently inserted only after the characters
+ ``. , ; ? ! /`` and ``\``. Due to TeX internals, white space in the line
+ will be stretched (or shrunk) in order to accommodate the linebreak.
+
+ Default: ``true``
+
+ .. versionadded:: 1.5
+ set this option value to ``false`` to recover former behavior.
+
+ .. versionchanged:: 2.3.0
+ added potential breakpoint at ``\`` characters.
+
+``verbatimvisiblespace``
+ When a long code line is split, the last space character from the source
+ code line right before the linebreak location is typeset using this.
+
+ Default: ``\textcolor{red}{\textvisiblespace}``
+
+``verbatimcontinued``
+ A LaTeX macro inserted at start of continuation code lines. Its
+ (complicated...) default typesets a small red hook pointing to the right::
+
+ \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}}
+
+ .. versionchanged:: 1.5
+ The breaking of long code lines was added at 1.4.2. The default
+ definition of the continuation symbol was changed at 1.5 to accommodate
+ various font sizes (e.g. code-blocks can be in footnotes).
+
+.. note::
+
+ Values for color keys must either:
+
+ - obey the syntax of the ``\definecolor`` LaTeX command, e.g. something
+ such as ``VerbatimColor={rgb}{0.2,0.3,0.5}`` or ``{RGB}{37,23,255}`` or
+ ``{gray}{0.75}`` or (only with package ``xcolor``) ``{HTML}{808080}`` or
+ ...
+
+ - or obey the syntax of the ``\colorlet`` command from package ``xcolor``
+ (which then must exist in the LaTeX installation),
+ e.g. ``VerbatimColor=red!10`` or ``red!50!green`` or ``-red!75`` or
+ ``MyPreviouslyDefinedColor`` or... Refer to xcolor_ documentation for
+ this syntax.
+
+ .. _xcolor: https://ctan.org/pkg/xcolor
+
+ .. versionchanged:: 5.3.0
+ Formerly only the ``\definecolor`` syntax was accepted.
+
+``TitleColor``
+ The color for titles (as configured via use of package "titlesec".)
+
+ Default: ``{rgb}{0.126,0.263,0.361}``
+
+``InnerLinkColor``
+ A color passed to ``hyperref`` as value of ``linkcolor`` and
+ ``citecolor``.
+
+ Default: ``{rgb}{0.208,0.374,0.486}``.
+
+``OuterLinkColor``
+ A color passed to ``hyperref`` as value of ``filecolor``, ``menucolor``,
+ and ``urlcolor``.
+
+ Default: ``{rgb}{0.216,0.439,0.388}``
+
+``VerbatimColor``
+ The background color for :rst:dir:`code-block`\ s.
+
+ Default: ``{gray}{0.95}``
+
+ .. versionchanged:: 6.0.0
+
+ Formerly, it was ``{rgb}{1,1,1}`` (white).
+
+``VerbatimBorderColor``
+ The frame color.
+
+ Default: ``{RGB}{32,32,32}``
+
+ .. versionchanged:: 6.0.0
+
+ Formerly it was ``{rgb}{0,0,0}`` (black).
+
+``VerbatimHighlightColor``
+ The color for highlighted lines.
+
+ Default: ``{rgb}{0.878,1,1}``
+
+ .. versionadded:: 1.6.6
+
+.. _tablecolors:
+
+``TableRowColorHeader``
+ Sets the background color for (all) the header rows of tables.
+
+ It will have an effect only if either the :confval:`latex_table_style`
+ contains ``'colorrows'`` or if the table is assigned the ``colorrows``
+ class. It is ignored for tables with ``nocolorrows`` class.
+
+ As for the other ``'sphinxsetup'`` keys, it can also be set or modified
+ from a ``\sphinxsetup{...}`` LaTeX command inserted via the :dudir:`raw`
+ directive, or also from a LaTeX environment associated to a `container
+ class <latexcontainer_>`_ and using such ``\sphinxsetup{...}``.
+
+ Default: ``{gray}{0.86}``
+
+ There is also ``TableMergeColorHeader``. If used, sets a specific color
+ for merged single-row cells in the header.
+
+ .. versionadded:: 5.3.0
+
+``TableRowColorOdd``
+ Sets the background color for odd rows in tables (the row count starts at
+ ``1`` at the first non-header row). Has an effect only if the
+ :confval:`latex_table_style` contains ``'colorrows'`` or for specific
+ tables assigned the ``colorrows`` class.
+
+ Default: ``{gray}{0.92}``
+
+ There is also ``TableMergeColorOdd``.
+
+ .. versionadded:: 5.3.0
+
+``TableRowColorEven``
+ Sets the background color for even rows in tables.
+
+ Default ``{gray}{0.98}``
+
+ There is also ``TableMergeColorEven``.
+
+ .. versionadded:: 5.3.0
+
+``verbatimsep``
+ The separation between code lines and the frame.
+
+ See :ref:`additionalcss` for its alias ``pre_padding`` and
+ additional keys.
+
+ Default: ``\fboxsep``
+
+``verbatimborder``
+ The width of the frame around :rst:dir:`code-block`\ s. See also
+ :ref:`additionalcss` for ``pre_border-width``.
+
+ Default: ``\fboxrule``
+
+``shadowsep``
+ The separation between contents and frame for contents_ and
+ :dudir:`topic` boxes.
+
+ See :ref:`additionalcss` for the alias ``div.topic_padding``.
+
+ Default: ``5pt``
+
+``shadowsize``
+ The width of the lateral "shadow" to the right and bottom.
+
+ See :ref:`additionalcss` for ``div.topic_box-shadow`` which allows to
+ configure separately the widths of the vertical and horizontal shadows.
+
+ Default: ``4pt``
+
+ .. versionchanged:: 6.1.2
+ Fixed a regression introduced at ``5.1.0`` which modified unintentionally
+ the width of topic boxes and worse had made usage of this key break PDF
+ builds.
+
+``shadowrule``
+ The width of the frame around :dudir:`topic` boxes. See also
+ :ref:`additionalcss` for ``div.topic_border-width``.
+
+ Default: ``\fboxrule``
+
+|notebdcolors|
+ The color for the two horizontal rules used by Sphinx in LaTeX for styling
+ a :dudir:`note` type admonition.
+
+ Default: ``{rgb}{0,0,0}`` (black)
+
+|notebgcolors|
+ The optional color for the background. It is a priori set to white, but
+ is not used, unless it has been set explicitly, and doing this triggers
+ Sphinx into switching to the more complex LaTeX code which is employed
+ also for ``warning`` type admonitions. There are then additional options
+ which are described in :ref:`additionalcss`.
+
+ Default: ``{rgb}{1,1,1}`` (white)
+
+ .. versionadded:: 6.2.0
+
+|notetextcolors|
+ The optional color for the contents.
+
+ Default: unset (uses ambient text color, a priori black)
+
+ .. versionadded:: 6.2.0
+
+ To be considered experimental until 7.0.0. These options have aliases
+ ``div.note_TeXcolor`` (etc) described in :ref:`additionalcss`. Using
+ the latter will let Sphinx switch to a more complex LaTeX code,
+ which supports the customizability described in :ref:`additionalcss`.
+
+|notetexextras|
+ Some extra LaTeX code (such as ``\bfseries`` or ``\footnotesize``)
+ to be executed at start of the contents.
+
+ Default: empty
+
+ .. versionadded:: 6.2.0
+
+ To be considered experimental until 7.0.0. These options have aliases
+ ``div.note_TeXextras`` (etc) described in :ref:`additionalcss`.
+
+``noteborder``, ``hintborder``, ``importantborder``, ``tipborder``
+ The width of the two horizontal rules.
+
+ If the background color is set, or the alternative :ref:`additionalcss`
+ syntax is used (e.g. ``div.note_border-width=1pt`` in place of
+ ``noteborder=1pt``), or *any* option with a CSS-alike name is used, then
+ the border is a full frame and this parameter sets its width also for left
+ and right.
+
+ Default: ``0.5pt``
+
+.. only:: not latex
+
+ |warningbdcolors|
+ The color for the admonition frame.
+
+ Default: ``{rgb}{0,0,0}`` (black)
+
+.. only:: latex
+
+ |wgbdcolorslatex|
+ The color for the admonition frame.
+
+ Default: ``{rgb}{0,0,0}`` (black)
+
+|warningbgcolors|
+ The background colors for the respective admonitions.
+
+ Default: ``{rgb}{1,1,1}`` (white)
+
+|warningborders|
+ The width of the frame. See
+ :ref:`additionalcss` for keys allowing to configure separately each
+ border width.
+
+ Default: ``1pt``
+
+``AtStartFootnote``
+ LaTeX macros inserted at the start of the footnote text at bottom of page,
+ after the footnote number.
+
+ Default: ``\mbox{ }``
+
+``BeforeFootnote``
+ LaTeX macros inserted before the footnote mark. The default removes
+ possible space before it (else, TeX could insert a line break there).
+
+ Default: ``\leavevmode\unskip``
+
+ .. versionadded:: 1.5
+
+``HeaderFamily``
+ default ``\sffamily\bfseries``. Sets the font used by headings.
+
+
+.. |notebdcolors| replace:: ``noteBorderColor``, ``hintBorderColor``,
+ ``importantBorderColor``, ``tipBorderColor``
+
+.. |notebgcolors| replace:: ``noteBgColor``, ``hintBgColor``,
+ ``importantBgColor``, ``tipBgColor``
+
+.. |notetextcolors| replace:: ``noteTextColor``, ``hintTextColor``,
+ ``importantTextColor``, ``tipTextColor``
+
+.. |notetexextras| replace:: ``noteTeXextras``, ``hintTeXextras``,
+ ``importantTeXextras``, ``tipTeXextras``
+
+.. |warningbdcolors| replace:: ``warningBorderColor``, ``cautionBorderColor``,
+ ``attentionBorderColor``, ``dangerBorderColor``,
+ ``errorBorderColor``
+
+.. |wgbdcolorslatex| replace:: ``warningBorderColor``, and
+ ``(caution|attention|danger|error)BorderColor``
+
+.. else latex goes into right margin, as it does not hyphenate the names
+
+.. |warningbgcolors| replace:: ``warningBgColor``, ``cautionBgColor``,
+ ``attentionBgColor``, ``dangerBgColor``,
+ ``errorBgColor``
+
+.. |warningborders| replace:: ``warningborder``, ``cautionborder``,
+ ``attentionborder``, ``dangerborder``,
+ ``errorborder``
+
+.. _additionalcss:
+
+Additional CSS-like ``'sphinxsetup'`` keys
+-------------------------------------------
+
+.. versionadded:: 5.1.0
+
+ For :rst:dir:`code-block`, :dudir:`topic` and contents_ directive,
+ and strong-type admonitions (:dudir:`warning`, :dudir:`error`, ...).
+
+.. versionadded:: 6.2.0
+
+ Also the :dudir:`note`, :dudir:`hint`, :dudir:`important` and :dudir:`tip`
+ admonitions can be styled this way. Using for them *any* of the listed
+ options will trigger usage of a more complex LaTeX code than the one used
+ per default (``sphinxheavybox`` vs ``sphinxlightbox``). Setting the new
+ ``noteBgColor`` (or ``hintBgColor``, ...) also triggers usage of
+ ``sphinxheavybox`` for :dudir:`note` (or :dudir:`hint`, ...).
+
+Perhaps in future these 5.1.0 (and 6.2.0) novel settings will be optionally
+imported from some genuine CSS external file, but currently they have to be used
+via the ``'sphinxsetup'`` interface (or the ``\sphinxsetup`` LaTeX command
+inserted via the :dudir:`raw` directive) and the CSS syntax is only imitated.
+
+.. important:: Low-level LaTeX errors causing a build failure can happen if
+ the input syntax is not respected.
+
+ * In particular colors must be input as for the other color related options
+ previously described, i.e. either in the ``\definecolor`` syntax or, if
+ package ``xcolor`` is available (it is then automatically used) also the
+ ``\colorlet`` syntax::
+
+ ...<other options>
+ div.warning_border-TeXcolor={rgb}{1,0,0},% (always works)
+ div.error_background-TeXcolor=red!10,% (works only if xcolor is available)
+ ...<other options>
+
+ * A colon in place of the equal sign will break LaTeX.
+
+ * ``...border-width`` or ``...padding`` expect a *single* dimension: they can not
+ be used so far with space separated dimensions.
+
+ * ``...top-right-radius`` et al. values may be either a single or *two* space
+ separated dimensions.
+
+ * Dimension specifications must use TeX units such as ``pt`` or ``cm`` or
+ ``in``. The ``px`` unit is recognized by ``pdflatex`` and ``lualatex``
+ but not by ``xelatex`` or ``platex``.
+
+ * It is allowed for such specifications to be so-called "dimensional
+ expressions", e.g. ``\fboxsep+2pt`` or ``0.5\baselineskip`` are valid
+ inputs. The expressions will be evaluated only at the typesetting time.
+ Be careful though if using as in these examples TeX control sequences to
+ double the backslash or to employ a raw Python string for the value of
+ the :ref:`'sphinxsetup' <latexsphinxsetup>` key.
+
+ * As a rule, avoid inserting unneeded spaces in the key values: especially
+ for the radii an input such ``2 pt 3pt`` will break LaTeX. Beware also
+ that ``\fboxsep \fboxsep`` will not be seen as space separated in LaTeX.
+ You must use something such as ``{\fboxsep} \fboxsep``. Or use
+ directly ``3pt 3pt`` which is a priori equivalent and simpler.
+
+The options are all named in a similar pattern which depends on a ``prefix``,
+which is then followed by an underscore, then the property name.
+
+.. csv-table::
+ :header: Directive, Option prefix, LaTeX environment
+
+ :rst:dir:`code-block`, ``pre``, ``sphinxVerbatim``
+ :dudir:`topic`, ``div.topic``, ``sphinxShadowBox``
+ contents_, ``div.topic``, ``sphinxShadowBox``
+ :dudir:`note`, ``div.note``, ``sphinxnote`` using ``sphinxheavybox``
+ :dudir:`warning`, ``div.warning``, ``sphinxwarning`` (uses ``sphinxheavybox``)
+ admonition type, ``div.<type>``, ``sphinx<type>`` (using ``sphinxheavybox``)
+
+Here are now these options as well as their common defaults.
+Replace below ``<prefix>`` by the actual prefix as explained above. Don't
+forget the underscore separating the prefix from the property names.
+
+- | ``<prefix>_border-top-width``,
+ | ``<prefix>_border-right-width``,
+ | ``<prefix>_border-bottom-width``,
+ | ``<prefix>_border-left-width``,
+ | ``<prefix>_border-width``. The latter can (currently) be only a *single*
+ dimension which then sets all four others.
+
+ The default is that all those dimensions are equal. They are set to:
+
+ * ``\fboxrule`` (i.e. a priori ``0.4pt``) for :rst:dir:`code-block`,
+ * ``\fboxrule`` for :dudir:`topic` or contents_ directive,
+ * ``1pt`` for :dudir:`warning` and other "strong" admonitions,
+ * ``0.5pt`` for :dudir:`note` and other "light" admonitions. The framing
+ style of the "lighbox" used for them in absence of usage of CSS-named
+ options will be emulated by the richer "heavybox" if setting
+ ``border-left-width`` and ``border-right-width`` both to ``0pt``.
+
+- ``<prefix>_box-decoration-break`` can be set to either ``clone`` or
+ ``slice`` and configures the behavior at page breaks.
+ It defaults to ``slice`` for :rst:dir:`code-block` (i.e. for ``<prefix>=pre``)
+ since 6.0.0. For other directives the default is ``clone``.
+- | ``<prefix>_padding-top``,
+ | ``<prefix>_padding-right``,
+ | ``<prefix>_padding-bottom``,
+ | ``<prefix>_padding-left``,
+ | ``<prefix>_padding``. The latter can (currently) be only a *single*
+ dimension which then sets all four others.
+
+ The default is that all those dimensions are equal. They are set to:
+
+ * ``\fboxsep`` (i.e. a priori ``3pt``) for :rst:dir:`code-block`,
+ * ``5pt`` for :dudir:`topic` or contents_ directive,
+ * a special value for :dudir:`warning` and other "strong" admonitions,
+ which ensures a backward compatible behavior.
+
+ .. important::
+
+ Prior to 5.1.0 there was no separate customizability of
+ padding for warning-type boxes in PDF via LaTeX output. The sum of
+ padding and border-width (as set for example for :dudir:`warning` by
+ ``warningborder``, now also named ``div.warning_border-width``) was
+ kept to a certain constant value. This limited the border-width
+ to small values else the border could overlap the text contents.
+ This behavior is kept as default.
+
+ * the same padding behavior is obeyed per default for :dudir:`note` or
+ other "light" admonitions when using ``sphinxheavybox``.
+- | ``<prefix>_border-top-left-radius``,
+ | ``<prefix>_border-top-right-radius``,
+ | ``<prefix>_border-bottom-right-radius``,
+ | ``<prefix>_border-bottom-left-radius``,
+ | ``<prefix>_border-radius``. This last key sets the first four to
+ its assigned value. Each key value can be either a single, or *two*,
+ dimensions which are then space separated.
+
+ The default is that all four corners are either circular or straight,
+ with common radii:
+
+ * ``\fboxsep`` (i.e. a priori ``3pt``) for :rst:dir:`code-block` (since 6.0.0).
+ * ``0pt`` for all other directives; this means to use straight corners.
+
+ See a remark above about traps with spaces in LaTeX.
+- ``<prefix>_box-shadow`` is special in so far as it may be:
+
+ * the ``none`` keyword,
+ * or a single dimension (giving both x-offset and y-offset),
+ * or two dimensions (separated by a space),
+ * or two dimensions followed by the keyword ``inset``.
+
+ The x-offset and y-offset may be negative. The default is ``none``,
+ *except* for the :dudir:`topic` or contents_ directives, for which it is
+ ``4pt 4pt``, i.e. the shadow has a width of ``4pt`` and extends to the right
+ and below the frame. The lateral shadow then extends into the page right
+ margin.
+- | ``<prefix>_border-TeXcolor``,
+ | ``<prefix>_background-TeXcolor``,
+ | ``<prefix>_box-shadow-TeXcolor``,
+ | ``<prefix>_TeXcolor``.
+ These are colors.
+
+ The shadow color defaults in all cases to ``{rgb}{0,0,0}`` i.e. to black.
+
+ Since 6.0.0 the border color and background color of :rst:dir:`code-block`,
+ i.e. ``pre`` prefix, default respectively to ``{RGB}{32,32,32}`` and
+ ``{gray}{0.95}``. They previously defaulted to black, respectively white.
+
+ For all other types, the border color defaults to black and the background
+ color to white.
+
+ The ``<prefix>_TeXcolor`` stands for the CSS property "color", i.e. it
+ influences the text color of the contents. As for the three other options,
+ the naming ``TeXcolor`` is to stress that the input syntax is the TeX one
+ for colors not an HTML/CSS one. If package ``xcolor`` is available in the
+ LaTeX installation, one can use directly named colors as key values.
+ Consider passing options such as ``dvipsnames``, ``svgnames`` or ``x11names``
+ to ``xcolor`` via ``'passoptionstopackages'`` key of :confval:`latex_elements`.
+
+ If ``<prefix>_TeXcolor`` is set, a ``\color`` command is inserted at
+ start of the directive contents; for admonitions, this happens after the
+ heading which reproduces the admonition type.
+
+- ``<prefix>_TeXextras``: if set, its value must be some LaTeX command or
+ commands, for example ``\itshape``. These commands will be inserted at the
+ start of the contents; for admonitions, this happens after the heading which
+ reproduces the admonition type.
+
+.. note::
+
+ - All directives support ``box-decoration-break`` to be set to ``slice``.
+
+ .. versionchanged:: 6.2.0
+
+ Formerly, only :rst:dir:`code-block` did. The default remains
+ ``clone`` for all other directives, but this will probably change at
+ 7.0.0.
+
+ - The corners of rounded boxes may be elliptical.
+
+ .. versionchanged:: 6.2.0
+
+ Formerly, only circular rounded corners were supported and a rounded
+ corner forced the whole frame to use the same constant width from
+ ``<prefix>_border-width``.
+
+ - Inset shadows are incompatible with rounded corners. In case
+ both are specified the inset shadow will simply be ignored.
+
+ .. versionchanged:: 6.2.0
+
+ Formerly it was to the contrary the rounded corners which were ignored
+ in case an inset shadow was specified.
+
+ - ``<prefix>_TeXcolor`` and ``<prefix>_TeXextras`` are new with 6.2.0.
+
+ Usefulness is doubtful in the case of :rst:dir:`code-block`:
+
+ - ``pre_TeXcolor`` will influence only the few non-Pygments highlighted
+ tokens; it does color the line numbers, but if one wants to color
+ *only* them one has to go through the ``fancyvrb`` interface.
+
+ - ``pre_TeXextras=\footnotesize`` for example may be replaced by usage of
+ the :confval:`latex_elements` key ``'fvset'``. For ``'lualatex'`` or
+ ``'xelatex'`` Sphinx includes in the preamble already
+ ``\fvset{fontsize=\small}`` and this induces ``fancyvrb`` into
+ overriding a ``\footnotesize`` coming from ``pre_TeXextras``. One has
+ to use ``pre_TeXextras=\fvset{fontsize=\footnotesize}`` syntax.
+ Simpler to set directly the :confval:`latex_elements` key
+ ``'fvset'``...
+
+ Consider these options experimental and that some implementation details
+ may change. For example if the ``pre_TeXextras`` LaTeX commands were put
+ by Sphinx in another location it could override the ``'fvset'`` effect,
+ perhaps this is what will be done in a future release.
+
+ - Rounded boxes are done using the pict2e_ interface to some basic PDF
+ graphics operations. If this LaTeX package can not be found the build
+ will proceed and render all boxes with straight corners.
+
+ - Elliptic corners use the ellipse_ LaTeX package which extends pict2e_.
+ If this LaTeX package can not be found rounded corners will be circular
+ arcs (or straight if pict2e_ is not available).
+
+.. _pict2e: https://ctan.org/pkg/pict2e
+.. _ellipse: https://ctan.org/pkg/ellipse
+
+
+The following legacy behavior is currently not customizable:
+
+- For :rst:dir:`code-block`, padding and border-width and shadow (if one adds
+ one) will go into the margin; the code lines remain at the same place
+ independently of the values of the padding and border-width, except for
+ being shifted vertically of course to not overwrite other text due to the
+ width of the border or external shadow.
+
+- For :dudir:`topic` (and contents_) the shadow (if on right) goes into the
+ page margin, but the border and the extra padding are kept within the text
+ area. Same for admonitions.
+
+- The contents_ and :dudir:`topic` directives are governed by the same options
+ with ``div.topic`` prefix: the Sphinx LaTeX mark-up uses for both directives
+ the same ``sphinxShadowBox`` environment which has currently no additional
+ branching, contrarily to the ``sphinxadmonition`` environment which branches
+ according to the admonition directive name, e.g. either to ``sphinxnote``
+ or ``sphinxwarning`` etc...
+
+
+LaTeX macros and environments
+-----------------------------
+
+The "LaTeX package" file :file:`sphinx.sty` loads various components
+providing support macros (aka commands), and environments, which are used in
+the mark-up produced on output from the ``latex`` builder, before conversion
+to ``pdf`` via the LaTeX toolchain. Also the "LaTeX class" files
+:file:`sphinxhowto.cls` and :file:`sphinxmanual.cls` define or customize some
+environments. All of these files can be found in the latex build repertory.
+
+Some of these provide facilities not available from pre-existing LaTeX
+packages and work around LaTeX limitations with lists, table cells, verbatim
+rendering, footnotes, etc...
+
+Others simply define macros with public names to make overwriting their
+defaults easy via user-added contents to the preamble. We will survey most of
+those public names here, but defaults have to be looked at in their respective
+definition files.
+
+.. hint::
+
+ Sphinx LaTeX support code is split across multiple smaller-sized files.
+ Rather than adding code to the preamble via
+ `latex_elements <latex_elements_confval_>`_\ [``'preamble'``] it is
+ also possible to replace entirely one of the component files of Sphinx
+ LaTeX code with a custom version, simply by including a modified copy in
+ the project source and adding the filename to the
+ :confval:`latex_additional_files` list. Check the LaTeX build repertory
+ for the filenames and contents.
+
+.. versionchanged:: 4.0.0
+ split of :file:`sphinx.sty` into multiple smaller units, to facilitate
+ customization of many aspects simultaneously.
+
+.. _latex-macros:
+
+Macros
+~~~~~~
+
+- Text styling commands:
+
+ .. csv-table::
+ :header: Name, ``maps argument #1 to:``
+ :align: left
+ :class: longtable
+ :delim: ;
+
+ ``\sphinxstrong``; ``\textbf{#1}``
+ ``\sphinxcode``; ``\texttt{#1}``
+ ``\sphinxbfcode``; ``\textbf{\sphinxcode{#1}}``
+ ``\sphinxemail``; ``\textsf{#1}``
+ ``\sphinxtablecontinued``; ``\textsf{#1}``
+ ``\sphinxtitleref``; ``\emph{#1}``
+ ``\sphinxmenuselection``; ``\emph{#1}``
+ ``\sphinxguilabel``; ``\emph{#1}``
+ ``\sphinxkeyboard``; ``\sphinxcode{#1}``
+ ``\sphinxaccelerator``; ``\underline{#1}``
+ ``\sphinxcrossref``; ``\emph{#1}``
+ ``\sphinxtermref``; ``\emph{#1}``
+ ``\sphinxsamedocref``; ``\emph{#1}``
+ ``\sphinxparam``; ``\emph{#1}``
+ ``\sphinxtypeparam``; ``\emph{#1}``
+ ``\sphinxoptional``; ``[#1]`` with larger brackets, see source
+
+ .. versionadded:: 1.4.5
+ Use of ``\sphinx`` prefixed macro names to limit possibilities of conflict
+ with LaTeX packages.
+
+ .. versionadded:: 1.8
+ ``\sphinxguilabel``
+
+ .. versionadded:: 3.0
+ ``\sphinxkeyboard``
+
+ .. versionadded:: 6.2.0
+ ``\sphinxparam``, ``\sphinxsamedocref``
+
+ .. versionadded:: 7.1.0
+ ``\sphinxparamcomma`` which defaults to a comma followed by a space and
+ ``\sphinxparamcommaoneperline`` which is used for one-parameter-per-line
+ signatures (see :confval:`maximum_signature_line_length`). It defaults
+ to ``\texttt{,}`` to make these end-of-line separators more distinctive.
+
+ Signatures of Python functions are rendered as ``name<space>(parameters)``
+ or ``name<space>[type parameters]<space>(parameters)`` (see :pep:`695`)
+ where the length of ``<space>`` is set to ``0pt`` by default.
+ This can be changed via ``\setlength{\sphinxsignaturelistskip}{1ex}``
+ for instance.
+
+- More text styling:
+
+ .. csv-table::
+ :header: Name, ``maps argument #1 to:``
+ :align: left
+ :class: longtable
+ :delim: ;
+
+ ``\sphinxstyleindexentry``; ``\texttt{#1}``
+ ``\sphinxstyleindexextra``; ``(\emph{#1})`` (with a space upfront)
+ ``\sphinxstyleindexpageref``; ``, \pageref{#1}``
+ ``\sphinxstyleindexpagemain``; ``\textbf{#1}``
+ ``\sphinxstyleindexlettergroup``; ``{\Large\sffamily#1}\nopagebreak\vspace{1mm}``
+ ``\sphinxstyleindexlettergroupDefault``; check source, too long for here
+ ``\sphinxstyletopictitle``; ``\textbf{#1}\par\medskip``
+ ``\sphinxstylesidebartitle``; ``\textbf{#1}\par\medskip``
+ ``\sphinxstyleothertitle``; ``\textbf{#1}``
+ ``\sphinxstylesidebarsubtitle``; ``~\\\textbf{#1} \smallskip``
+ ``\sphinxstyletheadfamily``; ``\sffamily`` (*this one has no argument*)
+ ``\sphinxstyleemphasis``; ``\emph{#1}``
+ ``\sphinxstyleliteralemphasis``; ``\emph{\sphinxcode{#1}}``
+ ``\sphinxstylestrong``; ``\textbf{#1}``
+ ``\sphinxstyleliteralstrong``; ``\sphinxbfcode{#1}``
+ ``\sphinxstyleabbreviation``; ``\textsc{#1}``
+ ``\sphinxstyleliteralintitle``; ``\sphinxcode{#1}``
+ ``\sphinxstylecodecontinued``; ``{\footnotesize(#1)}}``
+ ``\sphinxstylecodecontinues``; ``{\footnotesize(#1)}}``
+ ``\sphinxstylenotetitle``; ``\sphinxstrong{#1}<space>``
+ ``\sphinxstylehinttitle``; *idem*
+ ``\sphinxstyleimportanttitle``; *idem*
+ ``\sphinxstyletiptitle``; *idem*
+ ``\sphinxstylewarningtitle``; *idem*
+ ``\sphinxstylecautiontitle``; *idem*
+ ``\sphinxstyleattentiontitle``; *idem*
+ ``\sphinxstyledangertitle``; *idem*
+ ``\sphinxstyleerrortitle``; *idem*
+ ``\sphinxstyleseealsotitle``; ``\sphinxstrong{#1}\par\nopagebreak``
+
+ .. versionadded:: 1.5
+ These macros were formerly hard-coded as non customizable ``\texttt``,
+ ``\emph``, etc...
+
+ .. versionadded:: 1.6
+ ``\sphinxstyletheadfamily`` which defaults to ``\sffamily`` and allows
+ multiple paragraphs in header cells of tables.
+
+ .. versionadded:: 1.6.3
+ ``\sphinxstylecodecontinued`` and ``\sphinxstylecodecontinues``.
+
+ .. versionadded:: 1.8
+ ``\sphinxstyleindexlettergroup``, ``\sphinxstyleindexlettergroupDefault``.
+
+ .. versionadded:: 6.2.0
+ ``\sphinxstylenotetitle`` et al. The ``#1`` is the localized name of the
+ directive, with a final colon. Wrap it as ``\sphinxremovefinalcolon{#1}``
+ if this final colon is to be removed. Examples:
+
+ .. code-block:: latex
+
+ \renewcommand\sphinxstylewarningtitle[1]{%
+ \underline{\textbf{\sphinxremovefinalcolon{#1}}}\par
+ }
+ \renewcommand{\sphinxstylenotetitle}[1]{%
+ \textit{\textbf{\sphinxremovefinalcolon{#1}}}\par\nobreak
+ % LaTeX syntax is complex and we would be better off using \hrule.
+ {\parskip0pt\noindent}%
+ \raisebox{1ex}%
+ {\makebox[\linewidth]{\textcolor{sphinxnoteBorderColor}{\dotfill}}}
+ % It is complex to obtain nice vertical spacing for both a paragraph
+ % or a list following up; this set-up is better for a paragraph next.
+ \par\vskip-\parskip
+ }
+
+- ``\sphinxtableofcontents``: A wrapper (defined differently in
+ :file:`sphinxhowto.cls` and in :file:`sphinxmanual.cls`) of standard
+ ``\tableofcontents``. The macro ``\sphinxtableofcontentshook`` is executed
+ during its expansion right before ``\tableofcontents`` itself.
+
+ .. versionchanged:: 1.5
+ Formerly, the meaning of ``\tableofcontents`` was modified by Sphinx.
+
+ .. versionchanged:: 2.0
+ Hard-coded redefinitions of ``\l@section`` and ``\l@subsection`` formerly
+ done during loading of ``'manual'`` docclass are now executed later via
+ ``\sphinxtableofcontentshook``. This macro is also executed by the
+ ``'howto'`` docclass, but defaults to empty with it.
+
+ .. hint::
+
+ If adding to preamble the loading of ``tocloft`` package, also add to
+ preamble ``\renewcommand\sphinxtableofcontentshook{}`` else it will reset
+ ``\l@section`` and ``\l@subsection`` cancelling ``tocloft`` customization.
+
+- ``\sphinxmaketitle``: Used as the default setting of the ``'maketitle'``
+ :confval:`latex_elements` key.
+ Defined in the class files :file:`sphinxmanual.cls` and
+ :file:`sphinxhowto.cls`.
+
+ .. versionchanged:: 1.8.3
+ Formerly, ``\maketitle`` from LaTeX document class was modified by
+ Sphinx.
+
+- ``\sphinxbackoftitlepage``: For ``'manual'`` docclass, and if it is
+ defined, it gets executed at end of ``\sphinxmaketitle``, before the final
+ ``\clearpage``. Use either the ``'maketitle'`` key or the ``'preamble'`` key
+ of :confval:`latex_elements` to add a custom definition of
+ ``\sphinxbackoftitlepage``.
+
+ .. versionadded:: 1.8.3
+
+- ``\sphinxcite``: A wrapper of standard ``\cite`` for citation references.
+
+
+.. _sphinxbox:
+
+The ``\sphinxbox`` command
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 6.2.0
+
+The ``\sphinxbox[key=value,...]{inline text}`` command can be used to "box"
+inline text elements with all the customizability which has been described in
+:ref:`additionalcss`. It is a LaTeX command with one optional argument, which
+is a comma-separated list of key=value pairs, as for :ref:`latexsphinxsetup`.
+Here is the complete list of keys. They don't use any prefix.
+
+- ``border-width``,
+- ``border-top-width``, ``border-right-width``, ``border-bottom-width``,
+ ``border-left-width``,
+- ``padding``,
+- ``padding-top``, ``padding-right``, ``padding-bottom``, ``padding-left``,
+- ``border-radius``,
+- ``border-top-left-radius``, ``border-top-right-radius``,
+ ``border-bottom-right-radius``, ``border-bottom-left-radius``,
+- ``box-shadow``,
+- ``border-TeXcolor``, ``background-TeXcolor``, ``box-shadow-TeXcolor``,
+ ``TeXcolor``,
+- ``TeXextras``,
+- and ``addstrut`` which is a boolean key, i.e. to be used as ``addstrut=true``,
+ or ``addstrut`` alone where ``=true`` is omitted, or ``addstrut=false``.
+
+This last key is specific to ``\sphinxbox`` and it means to add a ``\strut``
+so that heights and depths are equalized across various instances on the same
+line with varying contents. The default is ``addstrut=false``.
+
+.. important::
+
+ Perhaps the default will turn into ``addstrut=true`` at 7.0.0 depending on
+ feedback until then.
+
+The combination ``addstrut, padding-bottom=0pt, padding-top=1pt`` is often
+satisfactory.
+
+Refer to :ref:`additionalcss` for important syntax information regarding the
+other keys. The default
+configuration uses no shadow, a border-width of ``\fboxrule``, a padding of
+``\fboxsep``, circular corners with radii ``\fboxsep`` and background and
+border colors as for the default rendering of code-blocks.
+
+When a ``\sphinxbox`` usage is nested within another one, it will ignore the
+options of the outer one: it first resets all options to their default state
+as they were prior to applying the outer box options, then it applies its own
+specific ones.
+
+One can modify these defaults via the command ``\sphinxboxsetup{key=value,...}``.
+The effect is cumulative, if one uses this command multiple times. Here the
+options are a mandatory argument so are within curly braces, not square
+brackets.
+
+Here is some example of use:
+
+.. code-block:: latex
+
+ latex_elements = {
+ 'preamble': r'''
+ % modify globally the defaults
+ \sphinxboxsetup{border-width=2pt,%
+ border-radius=4pt,%
+ background-TeXcolor=yellow!20}
+ % configure some styling element with some extra specific options:
+ \protected\def\sphinxkeyboard#1{\sphinxbox[border-TeXcolor=green]{\sphinxcode{#1}}}
+ ''',
+ }
+
+A utility ``\newsphinxbox`` is provided to create a new boxing macro, say
+``\foo`` which will act exactly like ``\sphinxbox`` but with a given extra
+configuration:
+
+.. code-block:: latex
+
+ % the specific options to \foo are within brackets
+ \newsphinxbox[border-radius=0pt, box-shadow=2pt 2pt]{\foo}
+ % then use this \foo, possibly with some extra options still:
+ \protected\def\sphinxguilabel#1{\foo{#1}}
+ \protected\def\sphinxmenuselection#1{\foo[box-shadow-TeXcolor=gray]{#1}}
+
+Boxes rendered with ``\foo`` obey as the ones using directly ``\sphinxbox``
+the current configuration as set possibly mid-way in document via
+``\sphinxboxsetup`` (from a :dudir:`raw` LaTeX mark-up), the only difference
+is that they have an initial additional set of default extras.
+
+In the above examples, you can probably use ``\renewcommand`` syntax if you
+prefer it to ``\protected\def`` (with ``[1]`` in place of ``#1`` then).
+
+
+Environments
+~~~~~~~~~~~~
+
+- A :dudir:`figure` may have an optional legend with arbitrary body
+ elements: they are rendered in a ``sphinxlegend`` environment. The default
+ definition issues ``\small``, and ends with ``\par``.
+
+ .. versionadded:: 1.5.6
+ Formerly, the ``\small`` was hardcoded in LaTeX writer and the ending
+ ``\par`` was lacking.
+
+- Environments associated with admonitions:
+
+ - ``sphinxnote``,
+ - ``sphinxhint``,
+ - ``sphinximportant``,
+ - ``sphinxtip``,
+ - ``sphinxwarning``,
+ - ``sphinxcaution``,
+ - ``sphinxattention``,
+ - ``sphinxdanger``,
+ - ``sphinxerror``.
+
+ They may be ``\renewenvironment``
+ 'd individually, and must then be defined with one argument (it is the heading
+ of the notice, for example ``Warning:`` for :dudir:`warning` directive, if
+ English is the document language). Their default definitions use either the
+ *sphinxheavybox* (for the last 5 ones) or the *sphinxlightbox*
+ environments, configured to use the parameters (colors, border thickness)
+ specific to each type, which can be set via ``'sphinxsetup'`` string.
+
+ .. versionchanged:: 1.5
+ Use of public environment names, separate customizability of the
+ parameters, such as ``noteBorderColor``, ``noteborder``,
+ ``warningBgColor``, ``warningBorderColor``, ``warningborder``, ...
+
+- Environment for the :rst:dir:`seealso` directive: ``sphinxseealso``.
+ It takes one argument which will be the localized string ``See also``
+ followed with a colon.
+
+ .. versionadded:: 6.1.0
+ .. versionchanged:: 6.2.0
+
+ Colon made part of the mark-up rather than being inserted by the
+ environment for coherence with how admonitions are handled generally.
+
+- The contents_ directive (with ``:local:`` option) and the
+ :dudir:`topic` directive are implemented by environment ``sphinxShadowBox``.
+
+ .. versionadded:: 1.4.2
+ Former code refactored into an environment allowing page breaks.
+
+ .. versionchanged:: 1.5
+ Options ``shadowsep``, ``shadowsize``, ``shadowrule``.
+
+- The literal blocks (via ``::`` or :rst:dir:`code-block`), are
+ implemented using ``sphinxVerbatim`` environment which is a wrapper of
+ ``Verbatim`` environment from package ``fancyvrb.sty``. It adds the handling
+ of the top caption and the wrapping of long lines, and a frame which allows
+ page breaks. Inside tables the used
+ environment is ``sphinxVerbatimintable`` (it does not draw a frame, but
+ allows a caption).
+
+ .. versionchanged:: 1.5
+ ``Verbatim`` keeps exact same meaning as in ``fancyvrb.sty`` (also
+ under the name ``OriginalVerbatim``); ``sphinxVerbatimintable`` is used
+ inside tables.
+
+ .. versionadded:: 1.5
+ Options ``verbatimwithframe``, ``verbatimwrapslines``,
+ ``verbatimsep``, ``verbatimborder``.
+
+ .. versionadded:: 1.6.6
+ Support for ``:emphasize-lines:`` option
+
+ .. versionadded:: 1.6.6
+ Easier customizability of the formatting via exposed to user LaTeX macros
+ such as ``\sphinxVerbatimHighlightLine``.
+
+- The bibliography uses ``sphinxthebibliography`` and the Python Module index
+ as well as the general index both use ``sphinxtheindex``; these environments
+ are wrappers of the ``thebibliography`` and respectively ``theindex``
+ environments as provided by the document class (or packages).
+
+ .. versionchanged:: 1.5
+ Formerly, the original environments were modified by Sphinx.
+
+Miscellany
+~~~~~~~~~~
+
+- Every text paragraph in document body starts with ``\sphinxAtStartPar``.
+ Currently, this is used to insert a zero width horizontal skip which
+ is a trick to allow TeX hyphenation of the first word of a paragraph
+ in a narrow context (like a table cell). For ``'lualatex'`` which
+ does not need the trick, the ``\sphinxAtStartPar`` does nothing.
+
+ .. versionadded:: 3.5.0
+
+- The section, subsection, ... headings are set using *titlesec*'s
+ ``\titleformat`` command.
+
+- For the ``'manual'`` docclass, the chapter headings can be customized using
+ *fncychap*'s commands ``\ChNameVar``, ``\ChNumVar``, ``\ChTitleVar``. File
+ :file:`sphinx.sty` has custom re-definitions in case of *fncychap*
+ option ``Bjarne``.
+
+ .. versionchanged:: 1.5
+ Formerly, use of *fncychap* with other styles than ``Bjarne`` was
+ dysfunctional.
+
+.. _latexcontainer:
+
+- Docutils :dudir:`container` directives are supported in LaTeX output: to
+ let a container class with name ``foo`` influence the final PDF via LaTeX,
+ it is only needed to define in the preamble an environment
+ ``sphinxclassfoo``. A simple example would be:
+
+ .. code-block:: latex
+
+ \newenvironment{sphinxclassred}{\color{red}}{}
+
+ Currently the class names must contain only ascii characters and avoid
+ characters special to LaTeX such as ``\``.
+
+ .. versionadded:: 4.1.0
+
+.. hint::
+
+ As an experimental feature, Sphinx can use user-defined template file for
+ LaTeX source if you have a file named ``_templates/latex.tex_t`` in your
+ project.
+
+ Additional files ``longtable.tex_t``, ``tabulary.tex_t`` and
+ ``tabular.tex_t`` can be added to ``_templates/`` to configure some aspects
+ of table rendering (such as the caption position).
+
+ .. versionadded:: 1.6
+ currently all template variables are unstable and undocumented.
+
+.. raw:: latex
+
+ \endgroup
diff --git a/doc/make.bat b/doc/make.bat
new file mode 100644
index 0000000..e2bd7ea
--- /dev/null
+++ b/doc/make.bat
@@ -0,0 +1,32 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=python ../sphinx/cmd/build.py
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.https://www.sphinx-doc.org/
+ exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
diff --git a/doc/man/index.rst b/doc/man/index.rst
new file mode 100644
index 0000000..1468022
--- /dev/null
+++ b/doc/man/index.rst
@@ -0,0 +1,22 @@
+Command-Line Tools
+==================
+
+These are the applications provided as part of Sphinx.
+
+Core Applications
+-----------------
+
+.. toctree::
+ :maxdepth: 3
+
+ sphinx-quickstart
+ sphinx-build
+
+Additional Applications
+-----------------------
+
+.. toctree::
+ :maxdepth: 3
+
+ sphinx-apidoc
+ sphinx-autogen
diff --git a/doc/man/sphinx-apidoc.rst b/doc/man/sphinx-apidoc.rst
new file mode 100644
index 0000000..efc8230
--- /dev/null
+++ b/doc/man/sphinx-apidoc.rst
@@ -0,0 +1,171 @@
+sphinx-apidoc
+=============
+
+Synopsis
+--------
+
+**sphinx-apidoc** [*OPTIONS*] -o <*OUTPUT_PATH*> <*MODULE_PATH*>
+[*EXCLUDE_PATTERN* ...]
+
+Description
+-----------
+
+:program:`sphinx-apidoc` is a tool for automatic generation of Sphinx sources
+that, using the :py:mod:`~sphinx.ext.autodoc` extension, document a whole
+package in the style of other automatic API documentation tools.
+
+*MODULE_PATH* is the path to a Python package to document, and *OUTPUT_PATH* is
+the directory where the generated sources are placed. Any *EXCLUDE_PATTERN*\s
+given are `fnmatch-style`_ file and/or directory patterns that will be excluded
+from generation.
+
+.. _fnmatch-style: https://docs.python.org/3/library/fnmatch.html
+
+.. warning::
+
+ ``sphinx-apidoc`` generates source files that use :mod:`sphinx.ext.autodoc`
+ to document all found modules. 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.
+
+Options
+-------
+
+.. program:: sphinx-apidoc
+
+.. option:: -o <OUTPUT_PATH>
+
+ Directory to place the output files. If it does not exist, it is created.
+
+.. option:: -q
+
+ Do not output anything on standard output, only write warnings and errors to
+ standard error.
+
+.. option:: -f, --force
+
+ Force overwriting of any existing generated files.
+
+.. option:: -l, --follow-links
+
+ Follow symbolic links. Defaults to ``False``.
+
+.. option:: -n, --dry-run
+
+ Do not create any files.
+
+.. option:: -s <suffix>
+
+ Suffix for the source files generated. Defaults to ``rst``.
+
+.. option:: -d <MAXDEPTH>
+
+ Maximum depth for the generated table of contents file. Defaults to ``4``.
+
+.. option:: --tocfile
+
+ Filename for a table of contents file. Defaults to ``modules``.
+
+.. option:: -T, --no-toc
+
+ Do not create a table of contents file. Ignored when :option:`--full` is
+ provided.
+
+.. option:: -F, --full
+
+ Generate a full Sphinx project (``conf.py``, ``Makefile`` etc.) using
+ the same mechanism as :program:`sphinx-quickstart`.
+
+.. option:: -e, --separate
+
+ Put documentation for each module on its own page.
+
+ .. versionadded:: 1.2
+
+.. option:: -E, --no-headings
+
+ Do not create headings for the modules/packages. This is useful, for
+ example, when docstrings already contain headings.
+
+.. option:: -P, --private
+
+ Include "_private" modules.
+
+ .. versionadded:: 1.2
+
+.. option:: --implicit-namespaces
+
+ By default sphinx-apidoc processes sys.path searching for modules only.
+ Python 3.3 introduced :pep:`420` implicit namespaces that allow module path
+ structures such as ``foo/bar/module.py`` or ``foo/bar/baz/__init__.py``
+ (notice that ``bar`` and ``foo`` are namespaces, not modules).
+
+ Interpret paths recursively according to PEP-0420.
+
+.. option:: -M, --module-first
+
+ Put module documentation before submodule documentation.
+
+These options are used when :option:`--full` is specified:
+
+.. option:: -a
+
+ Append module_path to sys.path.
+
+.. option:: -H <project>
+
+ Sets the project name to put in generated files (see :confval:`project`).
+
+.. option:: -A <author>
+
+ Sets the author name(s) to put in generated files (see
+ :confval:`copyright`).
+
+.. option:: -V <version>
+
+ Sets the project version to put in generated files (see :confval:`version`).
+
+.. option:: -R <release>
+
+ Sets the project release to put in generated files (see :confval:`release`).
+
+.. rubric:: Project templating
+
+.. versionadded:: 2.2
+ Project templating options for sphinx-apidoc
+
+.. option:: -t, --templatedir=TEMPLATEDIR
+
+ Template directory for template files. You can modify the templates of
+ sphinx project files generated by apidoc. Following Jinja2 template
+ files are allowed:
+
+ * ``module.rst_t``
+ * ``package.rst_t``
+ * ``toc.rst_t``
+ * ``root_doc.rst_t``
+ * ``conf.py_t``
+ * ``Makefile_t``
+ * ``Makefile.new_t``
+ * ``make.bat_t``
+ * ``make.bat.new_t``
+
+ In detail, please refer the system template files Sphinx provides.
+ (``sphinx/templates/apidoc`` and ``sphinx/templates/quickstart``)
+
+Environment
+-----------
+
+.. envvar:: SPHINX_APIDOC_OPTIONS
+
+ A comma-separated list of option to append to generated ``automodule``
+ directives. Defaults to ``members,undoc-members,show-inheritance``.
+
+See also
+--------
+
+:manpage:`sphinx-build(1)`, :manpage:`sphinx-autogen(1)`
+
+.. _fnmatch: https://docs.python.org/3/library/fnmatch.html
diff --git a/doc/man/sphinx-autogen.rst b/doc/man/sphinx-autogen.rst
new file mode 100644
index 0000000..caeb44b
--- /dev/null
+++ b/doc/man/sphinx-autogen.rst
@@ -0,0 +1,97 @@
+sphinx-autogen
+==============
+
+Synopsis
+--------
+
+**sphinx-autogen** [*options*] <sourcefile> ...
+
+Description
+-----------
+
+:program:`sphinx-autogen` is a tool for automatic generation of Sphinx sources
+that, using the :py:mod:`~sphinx.ext.autodoc` extension, document items included
+in :rst:dir:`autosummary` listing(s).
+
+*sourcefile* is the path to one or more reStructuredText documents containing
+:rst:dir:`autosummary` entries with the ``:toctree::`` option set. *sourcefile*
+can be an :py:mod:`fnmatch`-style pattern.
+
+Options
+-------
+
+.. program:: sphinx-autogen
+
+.. option:: -o <outputdir>
+
+ Directory to place the output file. If it does not exist, it is created.
+ Defaults to the value passed to the ``:toctree:`` option.
+
+.. option:: -s <suffix>, --suffix <suffix>
+
+ Default suffix to use for generated files. Defaults to ``rst``.
+
+.. option:: -t <templates>, --templates <templates>
+
+ Custom template directory. Defaults to ``None``.
+
+.. option:: -i, --imported-members
+
+ Document imported members.
+
+.. option:: -a, --respect-module-all
+
+ Document exactly the members in a module's ``__all__`` attribute.
+
+Example
+-------
+
+Given the following directory structure::
+
+ docs
+ ├── index.rst
+ └── ...
+ foobar
+ ├── foo
+ │ └── __init__.py
+ └── bar
+ ├── __init__.py
+ └── baz
+ └── __init__.py
+
+and assuming ``docs/index.rst`` contained the following:
+
+.. code-block:: rst
+
+ Modules
+ =======
+
+ .. autosummary::
+ :toctree: modules
+
+ foobar.foo
+ foobar.bar
+ foobar.bar.baz
+
+If you run the following:
+
+.. code-block:: console
+
+ $ PYTHONPATH=. sphinx-autogen docs/index.rst
+
+then the following stub files will be created in ``docs``::
+
+ docs
+ ├── index.rst
+ └── modules
+ ├── foobar.bar.rst
+ ├── foobar.bar.baz.rst
+ └── foobar.foo.rst
+
+and each of those files will contain a :py:mod:`~sphinx.ext.autodoc` directive
+and some other information.
+
+See also
+--------
+
+:manpage:`sphinx-build(1)`, :manpage:`sphinx-apidoc(1)`
diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst
new file mode 100644
index 0000000..a1fb9be
--- /dev/null
+++ b/doc/man/sphinx-build.rst
@@ -0,0 +1,355 @@
+sphinx-build
+============
+
+Synopsis
+--------
+
+**sphinx-build** [*options*] <*sourcedir*> <*outputdir*> [*filenames* ...]
+
+Description
+-----------
+
+:program:`sphinx-build` generates documentation from the files in
+``<sourcedir>`` and places it in the ``<outputdir>``.
+
+:program:`sphinx-build` looks for ``<sourcedir>/conf.py`` for the configuration
+settings. :manpage:`sphinx-quickstart(1)` may be used to generate template
+files, including ``conf.py``.
+
+:program:`sphinx-build` can create documentation in different formats. A
+format is selected by specifying the builder name on the command line; it
+defaults to HTML. Builders can also perform other tasks related to
+documentation processing. For a list of available builders, refer to
+:option:`sphinx-build -b`.
+
+By default, everything that is outdated is built. Output only for selected
+files can be built by specifying individual filenames.
+
+Options
+-------
+
+.. program:: sphinx-build
+
+.. option:: -b buildername
+
+ The most important option: it selects a builder. The most common builders
+ are:
+
+ **html**
+ Build HTML pages. This is the default builder.
+
+ **dirhtml**
+ Build HTML pages, but with a single directory per document. Makes for
+ prettier URLs (no ``.html``) if served from a webserver.
+
+ **singlehtml**
+ Build a single HTML with the whole content.
+
+ **htmlhelp**, **qthelp**, **devhelp**, **epub**
+ Build HTML files with additional information for building a documentation
+ collection in one of these formats.
+
+ **applehelp**
+ Build an Apple Help Book. Requires :program:`hiutil` and
+ :program:`codesign`, which are not Open Source and presently only
+ available on Mac OS X 10.6 and higher.
+
+ **latex**
+ Build LaTeX sources that can be compiled to a PDF document using
+ :program:`pdflatex`.
+
+ **man**
+ Build manual pages in groff format for UNIX systems.
+
+ **texinfo**
+ Build Texinfo files that can be processed into Info files using
+ :program:`makeinfo`.
+
+ **text**
+ Build plain text files.
+
+ **gettext**
+ Build gettext-style message catalogs (``.pot`` files).
+
+ **doctest**
+ Run all doctests in the documentation, if the :mod:`~sphinx.ext.doctest`
+ extension is enabled.
+
+ **linkcheck**
+ Check the integrity of all external links.
+
+ **xml**
+ Build Docutils-native XML files.
+
+ **pseudoxml**
+ Build compact pretty-printed "pseudo-XML" files displaying the
+ internal structure of the intermediate document trees.
+
+ See :doc:`/usage/builders/index` for a list of all builders shipped with
+ Sphinx. Extensions can add their own builders.
+
+.. _make_mode:
+
+.. option:: -M buildername
+
+ Alternative to :option:`-b`. Uses the Sphinx :program:`make_mode` module,
+ which provides the same build functionality as a default :ref:`Makefile or
+ Make.bat <makefile_options>`. In addition to all Sphinx
+ :doc:`/usage/builders/index`, the following build pipelines are available:
+
+ **latexpdf**
+ Build LaTeX files and run them through :program:`pdflatex`, or as per
+ :confval:`latex_engine` setting.
+ If :confval:`language` is set to ``'ja'``, will use automatically
+ the :program:`platex/dvipdfmx` latex to PDF pipeline.
+
+ **info**
+ Build Texinfo files and run them through :program:`makeinfo`.
+
+ .. important::
+ Sphinx only recognizes the ``-M`` option if it is placed first.
+
+ .. versionadded:: 1.2.1
+
+.. option:: -a
+
+ If given, always write all output files. The default is to only write output
+ files for new and changed source files. (This may not apply to all
+ builders.)
+
+.. option:: -E
+
+ Don't use a saved :term:`environment` (the structure caching all
+ cross-references), but rebuild it completely. The default is to only read
+ and parse source files that are new or have changed since the last run.
+
+.. option:: -t tag
+
+ Define the tag *tag*. This is relevant for :rst:dir:`only` directives that
+ only include their content if this tag is set.
+
+ .. versionadded:: 0.6
+
+.. option:: -d path
+
+ Since Sphinx has to read and parse all source files before it can write an
+ output file, the parsed source files are cached as "doctree pickles".
+ Normally, these files are put in a directory called :file:`.doctrees` under
+ the build directory; with this option you can select a different cache
+ directory (the doctrees can be shared between all builders).
+
+.. option:: -j N, --jobs N
+
+ Distribute the build over *N* processes in parallel, to make building on
+ multiprocessor machines more effective. Note that not all parts and not all
+ builders of Sphinx can be parallelized. If ``auto`` argument is given,
+ Sphinx uses the number of CPUs as *N*.
+
+ .. versionadded:: 1.2
+ This option should be considered *experimental*.
+
+ .. versionchanged:: 1.7
+ Support ``auto`` argument.
+
+ .. versionchanged:: 6.2
+ Add ``--jobs`` long option.
+
+.. option:: -c path
+
+ Don't look for the :file:`conf.py` in the source directory, but use the given
+ configuration directory instead. Note that various other files and paths
+ given by configuration values are expected to be relative to the
+ configuration directory, so they will have to be present at this location
+ too.
+
+ .. versionadded:: 0.3
+
+.. option:: -C
+
+ Don't look for a configuration file; only take options via the ``-D`` option.
+
+ .. versionadded:: 0.5
+
+.. option:: -D setting=value
+
+ Override a configuration value set in the :file:`conf.py` file. The value
+ must be a number, string, list or dictionary value.
+
+ For lists, you can separate elements with a comma like this: ``-D
+ html_theme_path=path1,path2``.
+
+ For dictionary values, supply the setting name and key like this:
+ ``-D latex_elements.docclass=scrartcl``.
+
+ For boolean values, use ``0`` or ``1`` as the value.
+
+ .. versionchanged:: 0.6
+ The value can now be a dictionary value.
+
+ .. versionchanged:: 1.3
+ The value can now also be a list value.
+
+.. option:: -A name=value
+
+ Make the *name* assigned to *value* in the HTML templates.
+
+ .. versionadded:: 0.5
+
+.. option:: -n
+
+ Run in nit-picky mode. Currently, this generates warnings for all missing
+ references. See the config value :confval:`nitpick_ignore` for a way to
+ exclude some references as "known missing".
+
+.. option:: -N, --no-color
+
+ Do not emit colored output.
+
+ .. versionchanged:: 1.6
+ Add ``--no-color`` long option.
+
+.. option:: --color
+
+ Emit colored output. Auto-detected by default.
+
+ .. versionadded:: 1.6
+
+.. option:: -v
+
+ Increase verbosity (loglevel). This option can be given up to three times
+ to get more debug logging output. It implies :option:`-T`.
+
+ .. versionadded:: 1.2
+
+.. option:: -q
+
+ Do not output anything on standard output, only write warnings and errors to
+ standard error.
+
+.. option:: -Q
+
+ Do not output anything on standard output, also suppress warnings. Only
+ errors are written to standard error.
+
+.. option:: -w file
+
+ Write warnings (and errors) to the given file, in addition to standard error.
+
+.. option:: -W
+
+ Turn warnings into errors. This means that the build stops at the first
+ warning and ``sphinx-build`` exits with exit status 1.
+
+.. option:: --keep-going
+
+ With -W option, keep going processing when getting warnings to the end
+ of build, and ``sphinx-build`` exits with exit status 1.
+
+ .. versionadded:: 1.8
+
+.. option:: -T
+
+ Display the full traceback when an unhandled exception occurs. Otherwise,
+ only a summary is displayed and the traceback information is saved to a file
+ for further analysis.
+
+ .. versionadded:: 1.2
+
+.. option:: -P
+
+ (Useful for debugging only.) Run the Python debugger, :mod:`pdb`, if an
+ unhandled exception occurs while building.
+
+.. option:: -h, --help, --version
+
+ Display usage summary or Sphinx version.
+
+ .. versionadded:: 1.2
+
+You can also give one or more filenames on the command line after the source
+and build directories. Sphinx will then try to build only these output files
+(and their dependencies).
+
+Environment Variables
+---------------------
+
+The :program:`sphinx-build` refers following environment variables:
+
+.. describe:: MAKE
+
+ A path to make command. A command name is also allowed.
+ :program:`sphinx-build` uses it to invoke sub-build process on make-mode.
+
+.. _makefile_options:
+
+.. rubric:: Makefile Options
+
+The :file:`Makefile` and :file:`make.bat` files created by
+:program:`sphinx-quickstart` usually run :program:`sphinx-build` only with the
+:option:`-b` and :option:`-d` options. However, they support the following
+variables to customize behavior:
+
+.. describe:: PAPER
+
+ This sets the ``'papersize'`` key of :confval:`latex_elements`:
+ i.e. ``PAPER=a4`` sets it to ``'a4paper'`` and ``PAPER=letter`` to
+ ``'letterpaper'``.
+
+ .. note::
+
+ Usage of this environment variable got broken at Sphinx 1.5 as
+ ``a4`` or ``letter`` ended up as option to LaTeX document in
+ place of the needed ``a4paper``, resp. ``letterpaper``. Fixed at
+ 1.7.7.
+
+.. describe:: SPHINXBUILD
+
+ The command to use instead of ``sphinx-build``.
+
+.. describe:: BUILDDIR
+
+ The build directory to use instead of the one chosen in
+ :program:`sphinx-quickstart`.
+
+.. describe:: SPHINXOPTS
+
+ Additional options for :program:`sphinx-build`. These options can
+ also be set via the shortcut variable **O** (capital 'o').
+
+.. describe:: NO_COLOR
+
+ When set (regardless of value), :program:`sphinx-build` will not use color
+ in terminal output. ``NO_COLOR`` takes precedence over ``FORCE_COLOR``. See
+ `no-color.org <https://no-color.org/>`__ for other libraries supporting this
+ community standard.
+
+ .. versionadded:: 4.5.0
+
+.. describe:: FORCE_COLOR
+
+ When set (regardless of value), :program:`sphinx-build` will use color in
+ terminal output. ``NO_COLOR`` takes precedence over ``FORCE_COLOR``.
+
+ .. versionadded:: 4.5.0
+
+.. _when-deprecation-warnings-are-displayed:
+
+Deprecation Warnings
+--------------------
+
+If any deprecation warning like ``RemovedInSphinxXXXWarning`` are displayed
+when building a user's document, some Sphinx extension is using deprecated
+features. In that case, please report it to author of the extension.
+
+To disable the deprecation warnings, please set ``PYTHONWARNINGS=`` environment
+variable to your environment. For example:
+
+* ``PYTHONWARNINGS= make html`` (Linux/Mac)
+* ``export PYTHONWARNINGS=`` and do ``make html`` (Linux/Mac)
+* ``set PYTHONWARNINGS=`` and do ``make html`` (Windows)
+* modify your Makefile/make.bat and set the environment variable
+
+See also
+--------
+
+:manpage:`sphinx-quickstart(1)`
diff --git a/doc/man/sphinx-quickstart.rst b/doc/man/sphinx-quickstart.rst
new file mode 100644
index 0000000..d050a29
--- /dev/null
+++ b/doc/man/sphinx-quickstart.rst
@@ -0,0 +1,169 @@
+sphinx-quickstart
+=================
+
+Synopsis
+--------
+
+**sphinx-quickstart**
+
+Description
+-----------
+
+:program:`sphinx-quickstart` is an interactive tool that asks some questions
+about your project and then generates a complete documentation directory and
+sample Makefile to be used with :manpage:`sphinx-build(1)`.
+
+Options
+-------
+
+.. program:: sphinx-quickstart
+
+.. option:: -q, --quiet
+
+ Quiet mode that skips the interactive wizard for specifying options.
+ This option requires `-p`, `-a` and `-v` options.
+
+.. option:: -h, --help, --version
+
+ Display usage summary or Sphinx version.
+
+.. rubric:: Structure Options
+
+.. option:: --sep
+
+ If specified, separate source and build directories.
+
+.. option:: --no-sep
+
+ If specified, create build directory under source directory.
+
+.. option:: --dot=DOT
+
+ Inside the root directory, two more directories will be created;
+ "_templates" for custom HTML templates and "_static" for custom stylesheets
+ and other static files. You can enter another prefix (such as ".") to
+ replace the underscore.
+
+.. rubric:: Project Basic Options
+
+.. option:: -p PROJECT, --project=PROJECT
+
+ Project name will be set. (see :confval:`project`).
+
+.. option:: -a AUTHOR, --author=AUTHOR
+
+ Author names. (see :confval:`copyright`).
+
+.. option:: -v VERSION
+
+ Version of project. (see :confval:`version`).
+
+.. option:: -r RELEASE, --release=RELEASE
+
+ Release of project. (see :confval:`release`).
+
+.. option:: -l LANGUAGE, --language=LANGUAGE
+
+ Document language. (see :confval:`language`).
+
+.. option:: --suffix=SUFFIX
+
+ Source file suffix. (see :confval:`source_suffix`).
+
+.. option:: --master=MASTER
+
+ Master document name. (see :confval:`root_doc`).
+
+.. rubric:: Extension Options
+
+.. option:: --ext-autodoc
+
+ Enable :py:mod:`sphinx.ext.autodoc` extension.
+
+.. option:: --ext-doctest
+
+ Enable `sphinx.ext.doctest` extension.
+
+.. option:: --ext-intersphinx
+
+ Enable `sphinx.ext.intersphinx` extension.
+
+.. option:: --ext-todo
+
+ Enable `sphinx.ext.todo` extension.
+
+.. option:: --ext-coverage
+
+ Enable `sphinx.ext.coverage` extension.
+
+.. option:: --ext-imgmath
+
+ Enable `sphinx.ext.imgmath` extension.
+
+.. option:: --ext-mathjax
+
+ Enable `sphinx.ext.mathjax` extension.
+
+.. option:: --ext-ifconfig
+
+ Enable `sphinx.ext.ifconfig` extension.
+
+.. option:: --ext-viewcode
+
+ Enable `sphinx.ext.viewcode` extension.
+
+.. option:: --ext-githubpages
+
+ Enable `sphinx.ext.githubpages` extension.
+
+.. option:: --extensions=EXTENSIONS
+
+ Enable arbitrary extensions.
+
+.. rubric:: Makefile and Batchfile Creation Options
+
+.. option:: --use-make-mode (-m), --no-use-make-mode (-M)
+
+ :file:`Makefile/make.bat` uses (or doesn't use) :ref:`make-mode <make_mode>`.
+ Default is ``use``, which generates a more concise :file:`Makefile/make.bat`.
+
+ .. versionchanged:: 1.5
+ make-mode is default.
+
+.. option:: --makefile, --no-makefile
+
+ Create (or not create) makefile.
+
+.. option:: --batchfile, --no-batchfile
+
+ Create (or not create) batchfile
+
+.. rubric:: Project templating
+
+.. versionadded:: 1.5
+ Project templating options for sphinx-quickstart
+
+.. option:: -t, --templatedir=TEMPLATEDIR
+
+ Template directory for template files. You can modify the templates of
+ sphinx project files generated by quickstart. Following Jinja2 template
+ files are allowed:
+
+ * ``root_doc.rst_t``
+ * ``conf.py_t``
+ * ``Makefile_t``
+ * ``Makefile.new_t``
+ * ``make.bat_t``
+ * ``make.bat.new_t``
+
+ In detail, please refer the system template files Sphinx provides.
+ (``sphinx/templates/quickstart``)
+
+.. option:: -d NAME=VALUE
+
+ Define a template variable
+
+See also
+--------
+
+:manpage:`sphinx-build(1)`
diff --git a/doc/support.rst b/doc/support.rst
new file mode 100644
index 0000000..b7c6f01
--- /dev/null
+++ b/doc/support.rst
@@ -0,0 +1,20 @@
+Get support
+===========
+
+For questions or to report problems with Sphinx, join the `sphinx-users`_
+mailing list on Google Groups, come to the ``#sphinx-doc`` channel on
+`libera.chat`_, or open an issue at the tracker_.
+
+.. _sphinx-users: https://groups.google.com/group/sphinx-users
+.. _libera.chat: https://web.libera.chat/?channel=#sphinx-doc
+.. _tracker: https://github.com/sphinx-doc/sphinx/issues
+
+Examples of other projects using Sphinx can be found in the :doc:`examples page
+<examples>`. A useful tutorial_ has been written by the matplotlib developers.
+
+.. _tutorial: http://matplotlib.sourceforge.net/sampledoc/
+
+There is a translation team in Transifex_ of this documentation, thanks to the
+Sphinx document translators.
+
+.. _Transifex: https://www.transifex.com/sphinx-doc/sphinx-doc/dashboard/
diff --git a/doc/tutorial/automatic-doc-generation.rst b/doc/tutorial/automatic-doc-generation.rst
new file mode 100644
index 0000000..b47673d
--- /dev/null
+++ b/doc/tutorial/automatic-doc-generation.rst
@@ -0,0 +1,165 @@
+Automatic documentation generation from code
+============================================
+
+In the :ref:`previous section <tutorial-describing-objects>` of the tutorial
+you manually documented a Python function in Sphinx. However, the description
+was out of sync with the code itself, since the function signature was not
+the same. Besides, it would be nice to reuse :pep:`Python docstrings
+<257#what-is-a-docstring>` in the documentation, rather than having to write
+the information in two places.
+
+Fortunately, :doc:`the autodoc extension </usage/extensions/autodoc>` provides this
+functionality.
+
+Reusing signatures and docstrings with autodoc
+----------------------------------------------
+
+To use autodoc, first add it to the list of enabled extensions:
+
+.. code-block:: python
+ :caption: docs/source/conf.py
+ :emphasize-lines: 4
+
+ extensions = [
+ 'sphinx.ext.duration',
+ 'sphinx.ext.doctest',
+ 'sphinx.ext.autodoc',
+ ]
+
+Next, move the content of the ``.. py:function`` directive to the function
+docstring in the original Python file, as follows:
+
+.. code-block:: python
+ :caption: lumache.py
+ :emphasize-lines: 2-11
+
+ def get_random_ingredients(kind=None):
+ """
+ Return a list of random ingredients as strings.
+
+ :param kind: Optional "kind" of ingredients.
+ :type kind: list[str] or None
+ :raise lumache.InvalidKindError: If the kind is invalid.
+ :return: The ingredients list.
+ :rtype: list[str]
+
+ """
+ return ["shells", "gorgonzola", "parsley"]
+
+Finally, replace the ``.. py:function`` directive from the Sphinx documentation
+with :rst:dir:`autofunction`:
+
+.. code-block:: rst
+ :caption: docs/source/usage.rst
+ :emphasize-lines: 3
+
+ you can use the ``lumache.get_random_ingredients()`` function:
+
+ .. autofunction:: lumache.get_random_ingredients
+
+If you now build the HTML documentation, the output will be the same!
+With the advantage that it is generated from the code itself.
+Sphinx took the reStructuredText from the docstring and included it,
+also generating proper cross-references.
+
+You can also autogenerate documentation from other objects. For example, add
+the code for the ``InvalidKindError`` exception:
+
+.. code-block:: python
+ :caption: lumache.py
+
+ class InvalidKindError(Exception):
+ """Raised if the kind is invalid."""
+ pass
+
+And replace the ``.. py:exception`` directive with :rst:dir:`autoexception`
+as follows:
+
+.. code-block:: rst
+ :caption: docs/source/usage.rst
+ :emphasize-lines: 4
+
+ or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients`
+ will raise an exception.
+
+ .. autoexception:: lumache.InvalidKindError
+
+And again, after running ``make html``, the output will be the same as before.
+
+Generating comprehensive API references
+---------------------------------------
+
+While using ``sphinx.ext.autodoc`` makes keeping the code and the documentation
+in sync much easier, it still requires you to write an ``auto*`` directive
+for every object you want to document. Sphinx provides yet another level of
+automation: the :doc:`autosummary </usage/extensions/autosummary>` extension.
+
+The :rst:dir:`autosummary` directive generates documents that contain all the
+necessary ``autodoc`` directives. To use it, first enable the autosummary
+extension:
+
+.. code-block:: python
+ :caption: docs/source/conf.py
+ :emphasize-lines: 5
+
+ extensions = [
+ 'sphinx.ext.duration',
+ 'sphinx.ext.doctest',
+ 'sphinx.ext.autodoc',
+ 'sphinx.ext.autosummary',
+ ]
+
+Next, create a new ``api.rst`` file with these contents:
+
+.. code-block:: rst
+ :caption: docs/source/api.rst
+
+ API
+ ===
+
+ .. autosummary::
+ :toctree: generated
+
+ lumache
+
+Remember to include the new document in the root toctree:
+
+.. code-block:: rst
+ :caption: docs/source/index.rst
+ :emphasize-lines: 7
+
+ Contents
+ --------
+
+ .. toctree::
+
+ usage
+ api
+
+Finally, after you build the HTML documentation running ``make html``, it will
+contain two new pages:
+
+- ``api.html``, corresponding to ``docs/source/api.rst`` and containing a table
+ with the objects you included in the ``autosummary`` directive (in this case,
+ only one).
+- ``generated/lumache.html``, corresponding to a newly created reST file
+ ``generated/lumache.rst`` and containing a summary of members of the module,
+ in this case one function and one exception.
+
+.. figure:: /_static/tutorial/lumache-autosummary.png
+ :width: 80%
+ :align: center
+ :alt: Summary page created by autosummary
+
+ Summary page created by autosummary
+
+Each of the links in the summary page will take you to the places where you
+originally used the corresponding ``autodoc`` directive, in this case in the
+``usage.rst`` document.
+
+.. note::
+
+ The generated files are based on `Jinja2
+ templates <https://jinja2docs.readthedocs.io/>`_ that
+ :ref:`can be customized <autosummary-customizing-templates>`,
+ but that is out of scope for this tutorial.
diff --git a/doc/tutorial/deploying.rst b/doc/tutorial/deploying.rst
new file mode 100644
index 0000000..e16abdf
--- /dev/null
+++ b/doc/tutorial/deploying.rst
@@ -0,0 +1,281 @@
+Appendix: Deploying a Sphinx project online
+===========================================
+
+When you are ready to show your documentation project to the world, there are
+many options available to do so. Since the HTML generated by Sphinx is static,
+you can decouple the process of building your HTML documentation from hosting
+such files in the platform of your choice. You will not need a sophisticated
+server running Python: virtually every web hosting service will suffice.
+
+Therefore, the challenge is less how or where to serve the static HTML, but
+rather how to pick a workflow that automatically updates the deployed
+documentation every time there is a change in the source files.
+
+The following sections describe some of the available options to deploy
+your online documentation, and give some background information. If you want
+to go directly to the practical part, you can skip to :ref:`publishing-sources`.
+
+Sphinx-friendly deployment options
+----------------------------------
+
+There are several possible options you have to host your Sphinx documentation.
+Some of them are:
+
+**Read the Docs**
+ `Read the Docs`_ is an online service specialized in hosting technical
+ documentation written in Sphinx, as well as MkDocs. They have a
+ number of extra features, such as versioned documentation, traffic and
+ search analytics, custom domains, user-defined redirects, and more.
+
+**GitHub Pages**
+ `GitHub Pages`_ is a simple static web hosting tightly integrated with
+ `GitHub`_: static HTML is served from one of the branches of a project,
+ and usually sources are stored in another branch so that the output
+ can be updated every time the sources change (for example using `GitHub
+ Actions`_). It is free to use and supports custom domains.
+
+**GitLab Pages**
+ `GitLab Pages`_ is a similar concept to GitHub Pages, integrated with
+ `GitLab`_ and usually automated with `GitLab CI`_ instead.
+
+**Netlify**
+ `Netlify`_ is a sophisticated hosting for static sites enhanced by
+ client-side web technologies like JavaScript (so-called `"Jamstack"`_).
+ They offer support for headless content management systems and
+ serverless computing.
+
+**Your own server**
+ You can always use your own web server to host Sphinx HTML documentation.
+ It is the option that gives more flexibility, but also more complexity.
+
+All these options have zero cost, with the option of paying for extra features.
+
+.. _Read the Docs: https://readthedocs.org/
+.. _GitHub Pages: https://pages.github.com/
+.. _GitHub: https://github.com/
+.. _GitHub Actions: https://github.com/features/actions
+.. _GitLab Pages: https://about.gitlab.com/stages-devops-lifecycle/pages/
+.. _GitLab: https://gitlab.com/
+.. _GitLab CI: https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/
+.. _Netlify: https://www.netlify.com/
+.. _"Jamstack": https://jamstack.org/
+
+Embracing the "Docs as Code" philosophy
+---------------------------------------
+
+The free offerings of most of the options listed above require your
+documentation sources to be publicly available. Moreover, these services
+expect you to use a `Version Control System`_, a technology that tracks the
+evolution of a collection of files as a series of snapshots ("commits").
+The practice of writing documentation in plain text files with the same tools
+as the ones used for software development is commonly known as `"Docs as Code"`_.
+
+The most popular Version Control System nowadays is Git_, a free and open
+source tool that is the backbone of services like GitHub and GitLab.
+Since both Read the Docs and Netlify have integrations with GitHub and GitLab,
+and both GitHub and GitLab have an integrated Pages product, the most effective
+way of automatically build your documentation online is to upload your sources
+to either of these Git hosting services.
+
+.. _Version Control System: https://en.wikipedia.org/wiki/Version_control
+.. _"Docs as Code": https://www.writethedocs.org/guide/docs-as-code/
+.. _Git: https://git-scm.com/
+
+.. _publishing-sources:
+
+Publishing your documentation sources
+-------------------------------------
+
+GitHub
+~~~~~~
+
+The quickest way to upload an existing project to GitHub is to:
+
+1. `Sign up for a GitHub account <https://github.com/signup>`_.
+2. `Create a new repository <https://github.com/new>`_.
+3. Open `the "Upload files" page`_ of your new repository.
+4. Select the files on your operating system file browser (in your case
+ ``README.rst``, ``lumache.py``, the makefiles under the ``docs`` directory,
+ and everything under ``docs/source``) and drag them to the GitHub interface
+ to upload them all.
+5. Click on the :guilabel:`Commit changes` button.
+
+.. _the "Upload files" page: https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository
+
+.. note::
+
+ Make sure you don't upload the ``docs/build`` directory, as it contains the
+ output generated by Sphinx and it will change every time you change the
+ sources, complicating your workflow.
+
+These steps do not require access to the command line or installing any
+additional software. To learn more, you can:
+
+- Follow `this interactive GitHub course`_ to learn more about how the GitHub
+ interface works.
+- Read `this quickstart tutorial`_ to install extra software on your machine
+ and have more flexibility. You can either use the Git command line, or the
+ GitHub Desktop application.
+
+.. _this interactive GitHub course: https://lab.github.com/githubtraining/introduction-to-github
+.. _this quickstart tutorial: https://docs.github.com/en/get-started/quickstart
+
+GitLab
+~~~~~~
+
+Similarly to GitHub, the fastest way to upload your project to GitLab is
+using the web interface:
+
+1. `Sign up for a GitLab account <https://gitlab.com/users/sign_up>`_.
+2. `Create a new blank project <https://gitlab.com/projects/new>`_.
+3. Upload the project files (in your case ``README.rst``, ``lumache.py``, the
+ makefiles under the ``docs`` directory, and everything under
+ ``docs/source``) one by one using the :guilabel:`Upload File` button [#f1]_.
+
+Again, these steps do not require additional software on your computer. To
+learn more, you can:
+
+- Follow `this tutorial`_ to install Git on your machine.
+- Browse the `GitLab User documentation`_ to understand the possibilities of
+ the platform.
+
+.. _this tutorial: https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html
+.. _GitLab User documentation: https://docs.gitlab.com/ee/user/index.html
+
+.. note::
+
+ Make sure you don't upload the ``docs/build`` directory, as it contains the
+ output generated by Sphinx and it will change every time you change the
+ sources, complicating your workflow.
+
+.. [#f1] At the time of writing, `uploading whole directories to GitLab using
+ only the web
+ interface <https://gitlab.com/gitlab-org/gitlab/-/issues/228490>`_ is
+ not yet implemented.
+
+Publishing your HTML documentation
+----------------------------------
+
+Read the Docs
+~~~~~~~~~~~~~
+
+`Read the Docs`_ offers integration with both GitHub and GitLab. The quickest
+way of getting started is to follow :doc:`the RTD
+tutorial <readthedocs:tutorial/index>`, which is loosely based on this one.
+You can publish your sources on GitHub as explained :ref:`in the previous
+section <publishing-sources>`, then skip directly to
+:ref:`readthedocs:tutorial/index:Sign up for Read the Docs`.
+If you choose GitLab instead, the process is similar.
+
+GitHub Pages
+~~~~~~~~~~~~
+
+`GitHub Pages`_ requires you to :ref:`publish your
+sources <publishing-sources>` on `GitHub`_. After that, you will need an
+automated process that performs the ``make html`` step every time the sources
+change. That can be achieved using `GitHub Actions`_.
+
+After you have published your sources on GitHub, create a file named
+``.github/workflows/sphinx.yml`` in your repository with the following
+contents:
+
+.. code-block:: yaml
+ :caption: .github/workflows/
+
+ name: "Sphinx: Render docs"
+
+ on: push
+
+ jobs:
+ build:
+ runs-on: ubuntu-latest
+ permissions:
+ contents: write
+ steps:
+ - uses: actions/checkout@v3
+ - name: Build HTML
+ uses: ammaraskar/sphinx-action@master
+ - name: Upload artifacts
+ uses: actions/upload-artifact@v3
+ with:
+ name: html-docs
+ path: docs/build/html/
+ - name: Deploy
+ uses: peaceiris/actions-gh-pages@v3
+ if: github.ref == 'refs/heads/main'
+ with:
+ github_token: ${{ secrets.GITHUB_TOKEN }}
+ publish_dir: docs/build/html
+
+This contains a GitHub Actions workflow with a single job of four steps:
+
+1. Checkout the code.
+2. Build the HTML documentation using Sphinx.
+3. Attach the HTML output the artifacts to the GitHub Actions job, for easier
+ inspection.
+4. If the change happens on the default branch, take the contents of
+ ``docs/build/html`` and push it to the ``gh-pages`` branch.
+
+Next, you need to specify the dependencies for the ``make html`` step to be
+successful. For that, create a file ``docs/requirements.txt`` and add the
+following contents:
+
+.. code-block::
+ :caption: docs/requirements.txt
+
+ furo==2021.11.16
+
+And finally, you are ready to `enable GitHub Pages on your repository`_. For
+that, go to :guilabel:`Settings`, then :guilabel:`Pages` on the left sidebar,
+select the ``gh-pages`` branch in the "Source" dropdown menu, and click
+:guilabel:`Save`. After a few minutes, you should be able to see your HTML at
+the designated URL.
+
+.. _enable GitHub Pages on your repository: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
+
+GitLab Pages
+~~~~~~~~~~~~
+
+`GitLab Pages`_, on the other hand, requires you to :ref:`publish your
+sources <publishing-sources>` on `GitLab`_. When you are ready, you can
+automate the process of running ``make html`` using `GitLab CI`_.
+
+After you have published your sources on GitLab, create a file named
+``.gitlab-ci.yml`` in your repository with these contents:
+
+.. code-block:: yaml
+ :caption: .gitlab-ci.yml
+
+ stages:
+ - deploy
+
+ pages:
+ stage: deploy
+ image: python:3.9-slim
+ before_script:
+ - apt-get update && apt-get install make --no-install-recommends -y
+ - python -m pip install sphinx furo
+ script:
+ - cd docs && make html
+ after_script:
+ - mv docs/build/html/ ./public/
+ artifacts:
+ paths:
+ - public
+ rules:
+ - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
+
+This contains a GitLab CI workflow with one job of several steps:
+
+1. Install the necessary dependencies.
+2. Build the HTML documentation using Sphinx.
+3. Move the output to a known artifacts location.
+
+.. note::
+ You will need to `validate your account`_ by entering a payment method
+ (you will be charged a small amount that will then be reimbursed).
+
+.. _validate your account: https://about.gitlab.com/blog/2021/05/17/prevent-crypto-mining-abuse/#validating-an-account
+
+After that, if the pipeline is successful, you should be able to see your HTML
+at the designated URL.
diff --git a/doc/tutorial/describing-code.rst b/doc/tutorial/describing-code.rst
new file mode 100644
index 0000000..24fea38
--- /dev/null
+++ b/doc/tutorial/describing-code.rst
@@ -0,0 +1,276 @@
+Describing code in Sphinx
+=========================
+
+In the :doc:`previous sections of the tutorial </tutorial/index>` you can read
+how to write narrative or prose documentation in Sphinx. In this section you
+will describe code objects instead.
+
+Sphinx supports documenting code objects in several languages, namely Python,
+C, C++, JavaScript, and reStructuredText. Each of them can be documented using
+a series of directives and roles grouped by
+:doc:`domain </usage/restructuredtext/domains>`. For the remainder of the
+tutorial you will use the Python domain, but all the concepts seen in this
+section apply for the other domains as well.
+
+.. _tutorial-describing-objects:
+
+Python
+------
+
+Documenting Python objects
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sphinx offers several roles and directives to document Python objects,
+all grouped together in :ref:`the Python domain <python-domain>`. For example,
+you can use the :rst:dir:`py:function` directive to document a Python function,
+as follows:
+
+.. code-block:: rst
+ :caption: docs/source/usage.rst
+
+ Creating recipes
+ ----------------
+
+ To retrieve a list of random ingredients,
+ you can use the ``lumache.get_random_ingredients()`` function:
+
+ .. py:function:: lumache.get_random_ingredients(kind=None)
+
+ Return a list of random ingredients as strings.
+
+ :param kind: Optional "kind" of ingredients.
+ :type kind: list[str] or None
+ :return: The ingredients list.
+ :rtype: list[str]
+
+Which will render like this:
+
+.. figure:: /_static/tutorial/lumache-py-function.png
+ :width: 80%
+ :align: center
+ :alt: HTML result of documenting a Python function in Sphinx
+
+ The rendered result of documenting a Python function in Sphinx
+
+Notice several things:
+
+- Sphinx parsed the argument of the ``.. py:function`` directive and
+ highlighted the module, the function name, and the parameters appropriately.
+- The directive content includes a one-line description of the function,
+ as well as an :ref:`info field list <info-field-lists>` containing the function
+ parameter, its expected type, the return value, and the return type.
+
+.. note::
+
+ The ``py:`` prefix specifies the :term:`domain`. You may configure the
+ default domain so you can omit the prefix, either globally using the
+ :confval:`primary_domain` configuration, or use the
+ :rst:dir:`default-domain` directive to change it from the point it is called
+ until the end of the file.
+ For example, if you set it to ``py`` (the default), you can write
+ ``.. function::`` directly.
+
+Cross-referencing Python objects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, most of these directives generate entities that can be
+cross-referenced from any part of the documentation by using
+:ref:`a corresponding role <python-roles>`. For the case of functions,
+you can use :rst:role:`py:func` for that, as follows:
+
+.. code-block:: rst
+ :caption: docs/source/usage.rst
+
+ The ``kind`` parameter should be either ``"meat"``, ``"fish"``,
+ or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients`
+ will raise an exception.
+
+When generating code documentation, Sphinx will generate a
+cross-reference automatically just by using the name of the object,
+without you having to explicitly use a role for that. For example, you
+can describe the custom exception raised by the function using the
+:rst:dir:`py:exception` directive:
+
+.. code-block:: rst
+ :caption: docs/source/usage.rst
+
+ .. py:exception:: lumache.InvalidKindError
+
+ Raised if the kind is invalid.
+
+Then, add this exception to the original description of the function:
+
+.. code-block:: rst
+ :caption: docs/source/usage.rst
+ :emphasize-lines: 7
+
+ .. py:function:: lumache.get_random_ingredients(kind=None)
+
+ Return a list of random ingredients as strings.
+
+ :param kind: Optional "kind" of ingredients.
+ :type kind: list[str] or None
+ :raise lumache.InvalidKindError: If the kind is invalid.
+ :return: The ingredients list.
+ :rtype: list[str]
+
+And finally, this is how the result would look:
+
+.. figure:: /_static/tutorial/lumache-py-function-full.png
+ :width: 80%
+ :align: center
+ :alt: HTML result of documenting a Python function in Sphinx
+ with cross-references
+
+ HTML result of documenting a Python function in Sphinx with cross-references
+
+Beautiful, isn't it?
+
+Including doctests in your documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Since you are now describing code from a Python library, it will become useful
+to keep both the documentation and the code as synchronized as possible.
+One of the ways to do that in Sphinx is to include code snippets in the
+documentation, called *doctests*, that are executed when the documentation is
+built.
+
+To demonstrate doctests and other Sphinx features covered in this tutorial,
+Sphinx will need to be able to import the code. To achieve that, write this
+at the beginning of ``conf.py``:
+
+.. code-block:: python
+ :caption: docs/source/conf.py
+ :emphasize-lines: 3-5
+
+ # If extensions (or modules to document with autodoc) are in another directory,
+ # add these directories to sys.path here.
+ import pathlib
+ import sys
+ sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix())
+
+.. note::
+
+ An alternative to changing the :py:data:`sys.path` variable is to create a
+ ``pyproject.toml`` file and make the code installable,
+ so it behaves like any other Python library. However, the ``sys.path``
+ approach is simpler.
+
+Then, before adding doctests to your documentation, enable the
+:doc:`doctest </usage/extensions/doctest>` extension in ``conf.py``:
+
+.. code-block:: python
+ :caption: docs/source/conf.py
+ :emphasize-lines: 3
+
+ extensions = [
+ 'sphinx.ext.duration',
+ 'sphinx.ext.doctest',
+ ]
+
+Next, write a doctest block as follows:
+
+.. code-block:: rst
+ :caption: docs/source/usage.rst
+
+ >>> import lumache
+ >>> lumache.get_random_ingredients()
+ ['shells', 'gorgonzola', 'parsley']
+
+Doctests include the Python instructions to be run preceded by ``>>>``,
+the standard Python interpreter prompt, as well as the expected output
+of each instruction. This way, Sphinx can check whether the actual output
+matches the expected one.
+
+To observe how a doctest failure looks like (rather than a code error as
+above), let's write the return value incorrectly first. Therefore, add a
+function ``get_random_ingredients`` like this:
+
+.. code-block:: python
+ :caption: lumache.py
+
+ def get_random_ingredients(kind=None):
+ return ["eggs", "bacon", "spam"]
+
+You can now run ``make doctest`` to execute the doctests of your documentation.
+Initially this will display an error, since the actual code does not behave
+as specified:
+
+.. code-block:: console
+
+ (.venv) $ make doctest
+ Running Sphinx v4.2.0
+ loading pickled environment... done
+ ...
+ running tests...
+
+ Document: usage
+ ---------------
+ **********************************************************************
+ File "usage.rst", line 44, in default
+ Failed example:
+ lumache.get_random_ingredients()
+ Expected:
+ ['shells', 'gorgonzola', 'parsley']
+ Got:
+ ['eggs', 'bacon', 'spam']
+ **********************************************************************
+ ...
+ make: *** [Makefile:20: doctest] Error 1
+
+As you can see, doctest reports the expected and the actual results,
+for easy examination. It is now time to fix the function:
+
+.. code-block:: python
+ :caption: lumache.py
+ :emphasize-lines: 2
+
+ def get_random_ingredients(kind=None):
+ return ["shells", "gorgonzola", "parsley"]
+
+And finally, ``make test`` reports success!
+
+For big projects though, this manual approach can become a bit tedious.
+In the next section, you will see :doc:`how to automate the
+process </tutorial/automatic-doc-generation>`.
+
+Other languages (C, C++, others)
+--------------------------------
+
+Documenting and cross-referencing objects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sphinx also supports documenting and cross-referencing objects written in
+other programming languages. There are four additional built-in domains:
+C, C++, JavaScript, and reStructuredText. Third-party extensions may
+define domains for more languages, such as
+
+- `Fortran <https://sphinx-fortran.readthedocs.io>`_,
+- `Julia <http://bastikr.github.io/sphinx-julia>`_, or
+- `PHP <https://github.com/markstory/sphinxcontrib-phpdomain>`_.
+
+For example, to document a C++ type definition, you would use the built-in
+:rst:dir:`cpp:type` directive, as follows:
+
+.. code-block:: rst
+
+ .. cpp:type:: std::vector<int> CustomList
+
+ A typedef-like declaration of a type.
+
+Which would give the following result:
+
+.. cpp:type:: std::vector<int> CustomList
+
+ A typedef-like declaration of a type.
+
+All such directives then generate references that can be
+cross-referenced by using the corresponding role. For example, to reference
+the previous type definition, you can use the :rst:role:`cpp:type` role
+as follows:
+
+.. code-block:: rst
+
+ Cross reference to :cpp:type:`CustomList`.
+
+Which would produce a hyperlink to the previous definition: :cpp:type:`CustomList`.
diff --git a/doc/tutorial/end.rst b/doc/tutorial/end.rst
new file mode 100644
index 0000000..9f35b07
--- /dev/null
+++ b/doc/tutorial/end.rst
@@ -0,0 +1,6 @@
+Where to go from here
+=====================
+
+This tutorial covered the very first steps to create a documentation project
+with Sphinx. To continue learning more about Sphinx, check out the `rest of the
+documentation <../contents.html>`__.
diff --git a/doc/tutorial/first-steps.rst b/doc/tutorial/first-steps.rst
new file mode 100644
index 0000000..fd5c631
--- /dev/null
+++ b/doc/tutorial/first-steps.rst
@@ -0,0 +1,92 @@
+First steps to document your project using Sphinx
+=================================================
+
+Building your HTML documentation
+--------------------------------
+
+The ``index.rst`` file that ``sphinx-quickstart`` created has some content
+already, and it gets rendered as the front page of your HTML documentation. It
+is written in reStructuredText, a powerful markup language.
+
+Modify the file as follows:
+
+.. code-block:: rst
+ :caption: docs/source/index.rst
+
+ Welcome to Lumache's documentation!
+ ===================================
+
+ **Lumache** (/lu'make/) is a Python library for cooks and food lovers that
+ creates recipes mixing random ingredients. It pulls data from the `Open Food
+ Facts database <https://world.openfoodfacts.org/>`_ and offers a *simple* and
+ *intuitive* API.
+
+ .. note::
+
+ This project is under active development.
+
+This showcases several features of the reStructuredText syntax, including:
+
+- a **section header** using ``===`` for the underline,
+- two examples of :ref:`rst-inline-markup`: ``**strong emphasis**`` (typically
+ bold) and ``*emphasis*`` (typically italics),
+- an **inline external link**,
+- and a ``note`` **admonition** (one of the available :ref:`directives
+ <rst-directives>`)
+
+Now to render it with the new content, you can use the ``sphinx-build`` command
+as before, or leverage the convenience script as follows:
+
+.. code-block:: console
+
+ (.venv) $ cd docs
+ (.venv) $ make html
+
+After running this command, you will see that ``index.html`` reflects the new
+changes!
+
+Building your documentation in other formats
+--------------------------------------------
+
+Sphinx supports a variety of formats apart from HTML, including PDF, EPUB,
+:ref:`and more <builders>`. For example, to build your documentation
+in EPUB format, run this command from the ``docs`` directory:
+
+.. code-block:: console
+
+ (.venv) $ make epub
+
+After that, you will see the files corresponding to the e-book under
+``docs/build/epub/``. You can either open ``Lumache.epub`` with an
+EPUB-compatible e-book viewer, like `Calibre <https://calibre-ebook.com/>`_,
+or preview ``index.xhtml`` on a web browser.
+
+.. note::
+
+ To quickly display a complete list of possible output formats, plus some
+ extra useful commands, you can run :code:`make help`.
+
+Each output format has some specific configuration options that you can tune,
+:ref:`including EPUB <epub-options>`. For instance, the default value of
+:confval:`epub_show_urls` is ``inline``, which means that, by default, URLs are
+shown right after the corresponding link, in parentheses. You can change that
+behavior by adding the following code at the end of your ``conf.py``:
+
+.. code-block:: python
+
+ # EPUB options
+ epub_show_urls = 'footnote'
+
+With this configuration value, and after running ``make epub`` again, you will
+notice that URLs appear now as footnotes, which avoids cluttering the text.
+Sweet! Read on to explore :doc:`other ways to customize
+Sphinx </tutorial/more-sphinx-customization>`.
+
+.. note::
+
+ Generating a PDF using Sphinx can be done running ``make latexpdf``,
+ provided that the system has a working LaTeX installation,
+ as explained in the documentation of :class:`sphinx.builders.latex.LaTeXBuilder`.
+ Although this is perfectly feasible, such installations are often big,
+ and in general LaTeX requires careful configuration in some cases,
+ so PDF generation is out of scope for this tutorial.
diff --git a/doc/tutorial/getting-started.rst b/doc/tutorial/getting-started.rst
new file mode 100644
index 0000000..5cf0b38
--- /dev/null
+++ b/doc/tutorial/getting-started.rst
@@ -0,0 +1,120 @@
+Getting started
+===============
+
+Setting up your project and development environment
+---------------------------------------------------
+
+In a new directory, create a file called ``README.rst`` with the following
+content.
+
+.. code-block:: rst
+ :caption: README.rst
+
+ Lumache
+ =======
+
+ **Lumache** (/lu'make/) is a Python library for cooks and food lovers that
+ creates recipes mixing random ingredients.
+
+It is a good moment to create a Python virtual environment and install the
+required tools. For that, open a command line terminal, ``cd`` into the
+directory you just created, and run the following commands:
+
+.. code-block:: console
+
+ $ python -m venv .venv
+ $ source .venv/bin/activate
+ (.venv) $ python -m pip install sphinx
+
+.. note::
+
+ The installation method used above is described in more detail in
+ :ref:`install-pypi`. For the rest of this tutorial, the instructions will
+ assume a Python virtual environment.
+
+If you executed these instructions correctly, you should have the Sphinx command
+line tools available. You can do a basic verification running this command:
+
+.. code-block:: console
+
+ (.venv) $ sphinx-build --version
+ sphinx-build 4.0.2
+
+If you see a similar output, you are on the right path!
+
+Creating the documentation layout
+---------------------------------
+
+Then from the command line, run the following command:
+
+.. code-block:: console
+
+ (.venv) $ sphinx-quickstart docs
+
+This will present to you a series of questions required to create the basic
+directory and configuration layout for your project inside the ``docs`` folder.
+To proceed, answer each question as follows:
+
+- ``> Separate source and build directories (y/n) [n]``: Write "``y``" (without
+ quotes) and press :kbd:`Enter`.
+- ``> Project name``: Write "``Lumache``" (without quotes) and press
+ :kbd:`Enter`.
+- ``> Author name(s)``: Write "``Graziella``" (without quotes) and press
+ :kbd:`Enter`.
+- ``> Project release []``: Write "``0.1``" (without quotes) and press
+ :kbd:`Enter`.
+- ``> Project language [en]``: Leave it empty (the default, English) and press
+ :kbd:`Enter`.
+
+After the last question, you will see the new ``docs`` directory with the
+following content.
+
+.. code-block:: text
+
+ docs
+ ├── build
+ ├── make.bat
+ ├── Makefile
+ └── source
+ ├── conf.py
+ ├── index.rst
+ ├── _static
+ └── _templates
+
+The purpose of each of these files is:
+
+``build/``
+ An empty directory (for now) that will hold the rendered documentation.
+
+``make.bat`` and ``Makefile``
+ Convenience scripts to simplify some common Sphinx operations, such as
+ rendering the content.
+
+``source/conf.py``
+ A Python script holding the configuration of the Sphinx project. It contains
+ the project name and release you specified to ``sphinx-quickstart``, as well
+ as some extra configuration keys.
+
+``source/index.rst``
+ The :term:`root document` of the project, which serves as welcome page and
+ contains the root of the "table of contents tree" (or *toctree*).
+
+Thanks to this bootstrapping step, you already have everything needed to render
+the documentation as HTML for the first time. To do that, run this command:
+
+.. code-block:: console
+
+ (.venv) $ sphinx-build -b html docs/source/ docs/build/html
+
+And finally, open ``docs/build/html/index.html`` in your browser. You should see
+something like this:
+
+.. figure:: /_static/tutorial/lumache-first-light.png
+ :width: 80%
+ :align: center
+ :alt: Freshly created documentation of Lumache
+
+ Freshly created documentation of Lumache
+
+There we go! You created your first HTML documentation using Sphinx.
+Now you can start :doc:`customizing it </tutorial/first-steps>`.
diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst
new file mode 100644
index 0000000..d7f4861
--- /dev/null
+++ b/doc/tutorial/index.rst
@@ -0,0 +1,39 @@
+.. _tutorial:
+
+==================================
+Tutorial: Build your first project
+==================================
+
+In this tutorial you will build a simple documentation project using Sphinx, and
+view it in your browser as HTML. The project will include narrative,
+handwritten documentation, as well as autogenerated API documentation.
+
+The tutorial is aimed towards Sphinx newcomers willing to learn the fundamentals
+of how projects are created and structured. You will create a fictional
+software library to generate random food recipes that will serve as a guide
+throughout the process, with the objective of properly documenting it.
+
+To showcase Sphinx capabilities for code documentation you will use Python,
+which also supports *automatic* documentation generation.
+
+.. note::
+
+ Several other languages are natively supported in Sphinx for *manual* code
+ documentation, however they require extensions for *automatic* code
+ documentation, like `Breathe <https://breathe.readthedocs.io/>`_.
+
+To follow the instructions you will need access to a Linux-like command line and
+a basic understanding of how it works, as well as a working Python installation
+for development, since you will use *Python virtual environments* to create the
+project.
+
+.. toctree::
+
+ getting-started
+ first-steps
+ more-sphinx-customization
+ narrative-documentation
+ describing-code
+ automatic-doc-generation
+ deploying
+ end
diff --git a/doc/tutorial/more-sphinx-customization.rst b/doc/tutorial/more-sphinx-customization.rst
new file mode 100644
index 0000000..c28263c
--- /dev/null
+++ b/doc/tutorial/more-sphinx-customization.rst
@@ -0,0 +1,78 @@
+More Sphinx customization
+=========================
+
+There are two main ways to customize your documentation beyond what is possible
+with core Sphinx: extensions and themes.
+
+Enabling a built-in extension
+-----------------------------
+
+In addition to these configuration values, you can customize Sphinx even more
+by using :doc:`extensions </usage/extensions/index>`. Sphinx ships several
+:ref:`builtin ones <builtin-extensions>`, and there are many more
+:ref:`maintained by the community <third-party-extensions>`.
+
+For example, to enable the :mod:`sphinx.ext.duration` extension,
+locate the ``extensions`` list in your ``conf.py`` and add one element as
+follows:
+
+.. code-block:: python
+ :caption: docs/source/conf.py
+
+ # Add any Sphinx extension module names here, as strings. They can be
+ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+ # ones.
+ extensions = [
+ 'sphinx.ext.duration',
+ ]
+
+After that, every time you generate your documentation, you will see a short
+durations report at the end of the console output, like this one:
+
+.. code-block:: console
+
+ (.venv) $ make html
+ ...
+ The HTML pages are in build/html.
+
+ ====================== slowest reading durations =======================
+ 0.042 temp/source/index
+
+Using a third-party HTML theme
+------------------------------
+
+Themes, on the other hand, are a way to customize the appearance of your
+documentation. Sphinx has several :ref:`builtin themes <builtin-themes>`, and
+there are also `third-party ones <https://sphinx-themes.org/>`_.
+
+For example, to use the `Furo <https://pradyunsg.me/furo/>`_ third-party theme
+in your HTML documentation, first you will need to install it with ``pip`` in
+your Python virtual environment, like this:
+
+.. code-block:: console
+
+ (.venv) $ pip install furo
+
+And then, locate the ``html_theme`` variable on your ``conf.py`` and replace
+its value as follows:
+
+.. code-block:: python
+ :caption: docs/source/conf.py
+
+ # The theme to use for HTML and HTML Help pages. See the documentation for
+ # a list of builtin themes.
+ #
+ html_theme = 'furo'
+
+With this change, you will notice that your HTML documentation has now a new
+appearance:
+
+.. figure:: /_static/tutorial/lumache-furo.png
+ :width: 80%
+ :align: center
+ :alt: HTML documentation of Lumache with the Furo theme
+
+ HTML documentation of Lumache with the Furo theme
+
+It is now time to :doc:`expand the narrative documentation and split it into
+several documents </tutorial/narrative-documentation>`.
diff --git a/doc/tutorial/narrative-documentation.rst b/doc/tutorial/narrative-documentation.rst
new file mode 100644
index 0000000..a81204d
--- /dev/null
+++ b/doc/tutorial/narrative-documentation.rst
@@ -0,0 +1,130 @@
+Narrative documentation in Sphinx
+=================================
+
+Structuring your documentation across multiple pages
+----------------------------------------------------
+
+The file ``index.rst`` created by ``sphinx-quickstart`` is the :term:`root
+document`, whose main function is to serve as a welcome page and to contain the
+root of the "table of contents tree" (or *toctree*). Sphinx allows you to
+assemble a project from different files, which is helpful when the project
+grows.
+
+As an example, create a new file ``docs/source/usage.rst`` (next to
+``index.rst``) with these contents:
+
+.. code-block:: rst
+ :caption: docs/source/usage.rst
+
+ Usage
+ =====
+
+ Installation
+ ------------
+
+ To use Lumache, first install it using pip:
+
+ .. code-block:: console
+
+ (.venv) $ pip install lumache
+
+This new file contains two :ref:`section <rst-sections>` headers, normal
+paragraph text, and a :rst:dir:`code-block` directive that renders
+a block of content as source code, with appropriate syntax highlighting
+(in this case, generic ``console`` text).
+
+The structure of the document is determined by the succession of heading
+styles, which means that, by using ``---`` for the "Installation" section
+after ``===`` for the "Usage" section, you have declared "Installation" to
+be a *subsection* of "Usage".
+
+To complete the process, add a ``toctree`` :ref:`directive <rst-directives>` at
+the end of ``index.rst`` including the document you just created, as follows:
+
+.. code-block:: rst
+ :caption: docs/source/index.rst
+
+ Contents
+ --------
+
+ .. toctree::
+
+ usage
+
+This step inserts that document in the root of the *toctree*, so now it belongs
+to the structure of your project, which so far looks like this:
+
+.. code-block:: text
+
+ index
+ └── usage
+
+If you build the HTML documentation running ``make html``, you will see
+that the ``toctree`` gets rendered as a list of hyperlinks, and this allows you
+to navigate to the new page you just created. Neat!
+
+.. warning::
+
+ Documents outside a *toctree* will result in ``WARNING: document isn't
+ included in any toctree`` messages during the build process, and will be
+ unreachable for users.
+
+Adding cross-references
+-----------------------
+
+One powerful feature of Sphinx is the ability to seamlessly add
+:ref:`cross-references <xref-syntax>` to specific parts of the documentation:
+a document, a section, a figure, a code object, etc. This tutorial is full of
+them!
+
+To add a cross-reference, write this sentence right after the
+introduction paragraph in ``index.rst``:
+
+.. code-block:: rst
+ :caption: docs/source/index.rst
+
+ Check out the :doc:`usage` section for further information.
+
+The :rst:role:`doc` :ref:`role <rst-roles-alt>` you used automatically
+references a specific document in the project, in this case the ``usage.rst``
+you created earlier.
+
+Alternatively, you can also add a cross-reference to an arbitrary part of the
+project. For that, you need to use the :rst:role:`ref` role, and add an
+explicit *label* that acts as :duref:`a target <hyperlink-targets>`.
+
+For example, to reference the "Installation" subsection, add a label right
+before the heading, as follows:
+
+.. code-block:: rst
+ :caption: docs/source/usage.rst
+ :emphasize-lines: 4
+
+ Usage
+ =====
+
+ .. _installation:
+
+ Installation
+ ------------
+
+ ...
+
+And make the sentence you added in ``index.rst`` look like this:
+
+.. code-block:: rst
+ :caption: docs/source/index.rst
+
+ Check out the :doc:`usage` section for further information, including how to
+ :ref:`install <installation>` the project.
+
+Notice a trick here: the ``install`` part specifies how the link will look like
+(we want it to be a specific word, so the sentence makes sense), whereas the
+``<installation>`` part refers to the actual label we want to add a
+cross-reference to. If you do not include an explicit title, hence using
+``:ref:`installation```, the section title will be used (in this case,
+``Installation``). Both the ``:doc:`` and the ``:ref:`` roles will be rendered
+as hyperlinks in the HTML documentation.
+
+What about :doc:`documenting code objects in Sphinx </tutorial/describing-code>`?
+Read on!
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