   Generated by Sphinx 4.4.0.

Sphinx Documentation
********************

     Sphinx 4.4.0, Jan 27, 2022

     Georg Brandl

     Copyright © 2007-2022, Georg Brandl and the Sphinx team

 — The Detailed Node Listing —

Using Sphinx

Getting Started

Installing Sphinx

Linux

macOS

Windows

Installation from PyPI

reStructuredText

reStructuredText Primer

Hyperlinks

Roles

Cross-referencing syntax

Directives

Table of contents

Field Lists

Domains

Basic Markup

The Python Domain

The C Domain

The C++ Domain

Directives for Declaring Entities

Constrained Templates

Cross-referencing

Markdown

Configuration

Options for the Python domain

Builders

Extensions

Built-in extensions

sphinx.ext.autodoc – Include documentation from docstrings

sphinx.ext.autosectionlabel – Allow reference sections using its title

sphinx.ext.autosummary – Generate autodoc summaries

sphinx.ext.doctest – Test snippets in the documentation

sphinx.ext.imgconverter – A reference image converter using Imagemagick

sphinx.ext.inheritance_diagram – Include inheritance diagrams

sphinx.ext.intersphinx – Link to other projects’ documentation

sphinx.ext.linkcode – Add external links to source code

Math support for HTML outputs in Sphinx

sphinx.ext.napoleon – Support for NumPy and Google style docstrings

Overview

sphinx.ext.todo – Support for todo items

sphinx.ext.viewcode – Add links to highlighted source code

Third-party extensions

HTML Theming

Themes

Internationalization

Translating with sphinx-intl

Setuptools integration

Sphinx Web Support

Web Support Quick Start

Integrating Sphinx Documents Into Your Webapp

The WebSupport Class

Search Adapters

Storage Backends

Sphinx tutorial

Getting started

First steps to document your project using Sphinx

More Sphinx customization

Narrative documentation in Sphinx

Describing code in Sphinx

Python

Other languages (C, C++, others)

Automatic documentation generation from code

Appendix: Deploying a Sphinx project online

Publishing your documentation sources

Publishing your HTML documentation

Extending Sphinx

Developing extensions overview

Extension tutorials

Developing a “Hello world” extension

Developing a “TODO” extension

Developing a “recipe” extension

Developing autodoc extension for IntEnum

Configuring builders

HTML theme development

Templating

Man Pages

Core Applications

sphinx-quickstart

sphinx-build

Additional Applications

sphinx-apidoc

sphinx-autogen

Templating

Working with the builtin templates

LaTeX customization

LaTeX macros and environments

Developing extensions for Sphinx

APIs used for writing extensions

Application API

Docutils markup API

Directives

Domain API

Doctree node classes added by Sphinx

Nodes for domain-specific object descriptions

i18n API

Utilities

Sphinx internals

Contributing to Sphinx

Writing code

Writing documentation

Sphinx’s release process

Deprecation policy

Organization of the Sphinx project

Core developers

Sphinx FAQ

Texinfo info

Changelog

Release 4.4.0 (released Jan 17, 2022)

Release 4.3.2 (released Dec 19, 2021)

Release 4.3.1 (released Nov 28, 2021)

Release 4.3.0 (released Nov 11, 2021)

Release 4.2.0 (released Sep 12, 2021)

Release 4.1.2 (released Jul 27, 2021)

Release 4.1.1 (released Jul 15, 2021)

Release 4.1.0 (released Jul 12, 2021)

Release 4.0.3 (released Jul 05, 2021)

Release 4.0.2 (released May 20, 2021)

Release 4.0.1 (released May 11, 2021)

Release 4.0.0 (released May 09, 2021)

Release 3.5.4 (released Apr 11, 2021)

Release 3.5.3 (released Mar 20, 2021)

Release 3.5.2 (released Mar 06, 2021)

Release 3.5.1 (released Feb 16, 2021)

Release 3.5.0 (released Feb 14, 2021)

Release 3.4.3 (released Jan 08, 2021)

Release 3.4.2 (released Jan 04, 2021)

Release 3.4.1 (released Dec 25, 2020)

Release 3.4.0 (released Dec 20, 2020)

Release 3.3.1 (released Nov 12, 2020)

Release 3.3.0 (released Nov 02, 2020)

Release 3.2.1 (released Aug 14, 2020)

Release 3.2.0 (released Aug 08, 2020)

Release 3.1.2 (released Jul 05, 2020)

Release 3.1.1 (released Jun 14, 2020)

Release 3.1.0 (released Jun 08, 2020)

Release 3.0.4 (released May 27, 2020)

Release 3.0.3 (released Apr 26, 2020)

Release 3.0.2 (released Apr 19, 2020)

Release 3.0.1 (released Apr 11, 2020)

Release 3.0.0 (released Apr 06, 2020)

Release 2.4.5 (released Nov 18, 2021)

Release 2.4.4 (released Mar 05, 2020)

Release 2.4.3 (released Feb 22, 2020)

Release 2.4.2 (released Feb 19, 2020)

Release 2.4.1 (released Feb 11, 2020)

Release 2.4.0 (released Feb 09, 2020)

Release 2.3.1 (released Dec 22, 2019)

Release 2.3.0 (released Dec 15, 2019)

Release 2.2.2 (released Dec 03, 2019)

Release 2.2.1 (released Oct 26, 2019)

Release 2.2.0 (released Aug 19, 2019)

Release 2.1.2 (released Jun 19, 2019)

Release 2.1.1 (released Jun 10, 2019)

Release 2.1.0 (released Jun 02, 2019)

Release 2.0.1 (released Apr 08, 2019)

Release 2.0.0 (released Mar 29, 2019)

Release 1.8.6 (released Nov 18, 2021)

Release 1.8.5 (released Mar 10, 2019)

Release 1.8.4 (released Feb 03, 2019)

Release 1.8.3 (released Dec 26, 2018)

Release 1.8.2 (released Nov 11, 2018)

Release 1.8.1 (released Sep 22, 2018)

Release 1.8.0 (released Sep 13, 2018)

Release 1.7.9 (released Sep 05, 2018)

Release 1.7.8 (released Aug 29, 2018)

Release 1.7.7 (released Aug 19, 2018)

Release 1.7.6 (released Jul 17, 2018)

Release 1.7.5 (released May 29, 2018)

Release 1.7.4 (released Apr 25, 2018)

Release 1.7.3 (released Apr 23, 2018)

Release 1.7.2 (released Mar 21, 2018)

Release 1.7.1 (released Feb 23, 2018)

Release 1.7.0 (released Feb 12, 2018)

Release 1.6.7 (released Feb 04, 2018)

Release 1.6.6 (released Jan 08, 2018)

Release 1.6.5 (released Oct 23, 2017)

Release 1.6.4 (released Sep 26, 2017)

Release 1.6.3 (released Jul 02, 2017)

Release 1.6.2 (released May 28, 2017)

Release 1.6.1 (released May 16, 2017)

Release 1.5.6 (released May 15, 2017)

Release 1.5.5 (released Apr 03, 2017)

Release 1.5.4 (released Apr 02, 2017)

Release 1.5.3 (released Feb 26, 2017)

Release 1.5.2 (released Jan 22, 2017)

Release 1.5.1 (released Dec 13, 2016)

Release 1.5 (released Dec 5, 2016)

Release 1.4.9 (released Nov 23, 2016)

Release 1.4.8 (released Oct 1, 2016)

Release 1.4.7 (released Oct 1, 2016)

Release 1.4.6 (released Aug 20, 2016)

Release 1.4.5 (released Jul 13, 2016)

Release 1.4.4 (released Jun 12, 2016)

Release 1.4.3 (released Jun 5, 2016)

Release 1.4.2 (released May 29, 2016)

Release 1.4.1 (released Apr 12, 2016)

Release 1.4 (released Mar 28, 2016)

Release 1.3.6 (released Feb 29, 2016)

Release 1.3.5 (released Jan 24, 2016)

Release 1.3.4 (released Jan 12, 2016)

Release 1.3.3 (released Dec 2, 2015)

Release 1.3.2 (released Nov 29, 2015)

Release 1.3.1 (released Mar 17, 2015)

Release 1.3 (released Mar 10, 2015)

Release 1.3b3 (released Feb 24, 2015)

Release 1.3b2 (released Dec 5, 2014)

Release 1.3b1 (released Oct 10, 2014)

Release 1.2.3 (released Sep 1, 2014)

Release 1.2.2 (released Mar 2, 2014)

Release 1.2.1 (released Jan 19, 2014)

Release 1.2 (released Dec 10, 2013)

Release 1.2 beta3 (released Oct 3, 2013)

Release 1.2 beta2 (released Sep 17, 2013)

Release 1.2 beta1 (released Mar 31, 2013)

Release 1.1 (Oct 9, 2011)

Release 1.0 (Jul 23, 2010)

Projects using Sphinx

1 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 Extending Sphinx.

1.1 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 reStructuredText or
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, see
reStructuredText, along with its significant extensibility capabilities.

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
installation guide followed by the intro to the default
markup format used by Sphinx, see reStucturedText.

For a great “introduction” to writing docs in general – the whys and
hows, see also Write the docs(1), written by Eric Holscher.

   ---------- Footnotes ----------

   (1)
https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/

1.1.1 Setting up the documentation sources
------------------------------------------

The root directory of a Sphinx collection of plain-text document sources
is called the source directory.  This directory also contains
the Sphinx configuration file ‘conf.py’, where you can configure all
aspects of how Sphinx reads your sources and builds your documentation.
(1)

Sphinx comes with a script called ‘sphinx-quickstart’ that sets up a
source directory and creates a default ‘conf.py’ with the most useful
configuration values from a few questions it asks you.  To use this,
run:

     $ sphinx-quickstart

   ---------- Footnotes ----------

   (1) This is the usual layout.  However, ‘conf.py’ can also live in
another directory, the configuration directory.  Refer to the
sphinx-build man page for more information.

1.1.2 Defining document structure
---------------------------------

Let’s assume you’ve run ‘sphinx-quickstart’.  It created a source
directory with ‘conf.py’ and a root document, ‘index.rst’.  The main
function of the 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.

reStructuredText directives
...........................

‘toctree’ is a reStructuredText `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:

     .. toctree::
        :maxdepth: 2

You add documents listing them in the `content' of the directive:

     .. toctree::
        :maxdepth: 2

        usage/installation
        usage/quickstart
        ...

This is exactly how the ‘toctree’ for this documentation looks.  The
documents to include are given as document name.s, which in
short means that you leave off the file name extension and use forward
slashes (‘/’) as directory separators.

Read more about the 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.)

1.1.3 Adding content
--------------------

In Sphinx source files, you can use most features of standard
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 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.

See reStructuredText for a more in-depth introduction to
reStructuredText, including markup added by Sphinx.

1.1.4 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 ‘sphinx-build’ program:

     $ sphinx-build -b html sourcedir builddir

where `sourcedir' is the source directory, and `builddir' is
the directory in which you want to place the built documentation.  The
-b option selects a builder; in this example Sphinx will
build HTML files.

Refer to the sphinx-build man page for all options that
‘sphinx-build’ supports.

However, ‘sphinx-quickstart’ script creates a ‘Makefile’ and a
‘make.bat’ which make life even easier for you.  These can be executed
by running ‘make’ with the name of the builder.  For example.

     $ make html

This will build HTML docs in the build directory you chose.  Execute
‘make’ without an argument to see which targets are available.

     How do I generate PDF documents?: ‘make latexpdf’ runs the
     LaTeX builder and readily invokes the pdfTeX toolchain for
     you.

     Todo: Move this whole section into a guide on rST or directives

1.1.5 Documenting objects
-------------------------

One of Sphinx’s main objectives is easy documentation of `objects' (in a
very general sense) in any `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.

     .. 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:

 -- 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 `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.

     .. 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 py;class or py;method.  There
is also a cross-referencing `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 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.

See Domains for all the available domains and their
directives/roles.

1.1.6 Basic configuration
-------------------------

Earlier we mentioned that the ‘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 sys.path(1) 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 ‘conf.py’ by ‘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
‘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.

See Configuration for documentation of all available config
values.

     Todo: Move this entire doc to a different section

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/library/sys.html#sys.path

1.1.7 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 `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 ‘conf.py’ by
putting the string ‘'sphinx.ext.autodoc'’ into the list assigned to the
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 sys.path(1)
in your ‘conf.py’.

     Warning: 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.

See sphinx.ext.autodoc for the complete description of the
features of autodoc.

     Todo: Move this doc to another section

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/library/sys.html#sys.path

1.1.8 Intersphinx
-----------------

Many Sphinx documents including the Python documentation(1) are
published on the Internet.  When you want to make links to such
documents from your documentation, you can do it with
sphinx.ext.intersphinx.

In order to use intersphinx, you need to activate it in ‘conf.py’ by
putting the string ‘'sphinx.ext.intersphinx'’ into the extensions
list and set up the intersphinx_mapping config value.

For example, to link to ‘io.open()’ in the Python library manual, you
need to setup your 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
intersphinx_mapping. (this needs access to the URL in order to
download the list of valid targets).  Intersphinx also works for some
other domain.’s roles including ‘:ref:’, however it doesn’t
work for ‘:doc:’ as that is non-domain role.

See sphinx.ext.intersphinx for the complete description of
the features of intersphinx.

   ---------- Footnotes ----------

   (1) https://docs.python.org/3

1.1.9 More topics to be covered
-------------------------------

   - Other extensions.:

   - Static files

   - Selecting a theme.

   - Setuptools integration.

   - Templating.

   - Using extensions

   - Writing extensions.

1.2 Installing Sphinx
=====================

1.2.1 Overview
--------------

Sphinx is written in Python(1) and supports Python 3.6+.  It builds upon
the shoulders of many third-party libraries such as Docutils(2) and
Jinja(3), which are installed when Sphinx is installed.

   ---------- Footnotes ----------

   (1) https://docs.python-guide.org/

   (2) https://docutils.sourceforge.io/

   (3) https://jinja.palletsprojects.com/

1.2.2 Linux
-----------

1.2.2.1 Debian/Ubuntu
.....................

Install either ‘python3-sphinx’ using ‘apt-get’:

     $ apt-get install python3-sphinx

If it not already present, this will install Python for you.

1.2.2.2 RHEL, CentOS
....................

Install ‘python-sphinx’ using ‘yum’:

     $ yum install python-sphinx

If it not already present, this will install Python for you.

1.2.2.3 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').

1.2.3 macOS
-----------

Sphinx can be installed using Homebrew(1), MacPorts(2), or as part of a
Python distribution such as Anaconda(3).

   ---------- Footnotes ----------

   (1) https://brew.sh/

   (2) https://www.macports.org/

   (3) https://www.anaconda.com/download/#macos

1.2.3.1 Homebrew
................

     $ brew install sphinx-doc

For more information, refer to the package overview(1).

   ---------- Footnotes ----------

   (1) https://formulae.brew.sh/formula/sphinx-doc

1.2.3.2 MacPorts
................

Install either ‘python3x-sphinx’ using ‘port’:

     $ sudo port install py38-sphinx

To set up the executable paths, use the ‘port select’ command:

     $ sudo port select --set python python38
     $ sudo port select --set sphinx py38-sphinx

For more information, refer to the package overview(1).

   ---------- Footnotes ----------

   (1) https://www.macports.org/ports.php?by=library&substr=py38-sphinx

1.2.3.3 Anaconda
................

     $ conda install sphinx

1.2.4 Windows
-------------

Sphinx can be install using Chocolatey(1) or installed manually.

   ---------- Footnotes ----------

   (1) https://chocolatey.org/

1.2.4.1 Chocolatey
..................

     $ choco install sphinx

You would need to install Chocolatey(1) before running this.

For more information, refer to the chocolatey page(2).

   ---------- Footnotes ----------

   (1) https://chocolatey.org/install

   (2) https://chocolatey.org/packages/sphinx/

1.2.4.2 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' (‘⊞Win-r’ and type ‘cmd’).
Once the command prompt is open, type ‘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(1) Python on Windows installation
guides.  You must install Python 3(2).

Once Python is installed, you can install Sphinx using ‘pip’.  Refer to
the pip installation instructions below for more information.

   ---------- Footnotes ----------

   (1) https://docs.python-guide.org/

   (2) https://docs.python-guide.org/starting/install3/win/

1.2.5 Installation from PyPI
----------------------------

Sphinx packages are published on the Python Package Index(1).  The
preferred tool for installing packages from `PyPI' is ‘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' (‘⊞Win-r’ and type ‘cmd’)
and run the same command.

     C:\> pip install -U sphinx

After installation, type ‘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

   ---------- Footnotes ----------

   (1) https://pypi.org/project/Sphinx/

1.2.5.1 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(1).

     Warning: Note that in some Linux distributions, such as Debian and
     Ubuntu, this might require an extra installation step as follows.

               $ apt-get install python3-venv

   ---------- Footnotes ----------

   (1)
https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment

1.2.6 Docker
------------

Docker images for Sphinx are published on the Docker Hub(1).  There are
two kind of images:

   - sphinxdoc/sphinx(2)

   - sphinxdoc/sphinx-latexpdf(3)

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:

          $ docker run -it --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-quickstart

     And you can following command this to build HTML document:

          $ docker run --rm -v /path/to/document:/docs sphinxdoc/sphinx make html

For more details, please read README file(4) of docker images.

   ---------- Footnotes ----------

   (1) https://hub.docker.com/

   (2) https://hub.docker.com/repository/docker/sphinxdoc/sphinx

   (3)
https://hub.docker.com/repository/docker/sphinxdoc/sphinx-latexpdf

   (4) https://hub.docker.com/repository/docker/sphinxdoc/sphinx

1.2.7 Installation from source
------------------------------

You can install Sphinx directly from a clone of the Git repository(1).
This can be done either by cloning the repo and installing from the
local clone, on simply installing directly via ‘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(2) or
zip(3) format.  Once downloaded and extracted, these can be installed
with ‘pip’ as above.

   ---------- Footnotes ----------

   (1) https://github.com/sphinx-doc/sphinx

   (2) https://github.com/sphinx-doc/sphinx/archive/master.tar.gz

   (3) https://github.com/sphinx-doc/sphinx/archive/master.zip

1.3 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(1).

   ---------- Footnotes ----------

   (1) https://docutils.sourceforge.io/rst.html

1.3.1 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.

See also
........

The authoritative reStructuredText User Documentation(1).  The “ref”
links in this document link to the description of the individual
constructs in the reST reference.

   ---------- Footnotes ----------

   (1) https://docutils.sourceforge.io/rst.html

1.3.1.1 Paragraphs
..................

The paragraph (ref(1)) 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.

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#paragraphs

1.3.1.2 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 Roles for more information.

1.3.1.3 Lists and Quote-like blocks
...................................

List markup (ref(1)) 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 (ref(2)) 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 (ref(3)) are created by just indenting them more than
the surrounding paragraphs.

Line blocks (ref(4)) 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 (ref(5), with caveats noted in Field Lists)

   * option lists (ref(6))

   * quoted literal blocks (ref(7))

   * doctest blocks (ref(8))

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bullet-lists

   (2)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#definition-lists

   (3)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#block-quotes

   (4)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks

   (5)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists

   (6)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#option-lists

   (7)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#quoted-literal-blocks

   (8)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#doctest-blocks

1.3.1.4 Literal blocks
......................

Literal code blocks (ref(1)) 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 highlight directive and on a
project-wide basis using the highlight_language configuration
option.  The code-block directive can be used to set
highlighting on a block-by-block basis.  These directives are discussed
later.

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#literal-blocks

1.3.1.5 Doctest blocks
......................

Doctest blocks (ref(1)) are interactive Python sessions cut-and-pasted
into docstrings.  They do not require the literal blocks.
syntax.  The doctest block must end with a blank line and should `not'
end with an unused prompt:

     >>> 1 + 1
     2

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#doctest-blocks

1.3.1.6 Tables
..............

For `grid tables' (ref(1)), 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' (ref(2)) 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 Tables for more
information.

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#grid-tables

   (2)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#simple-tables

1.3.1.7 Hyperlinks
..................

1.3.1.8 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 (ref(1)), like
this:

     This is a paragraph that contains `a link`_.

     .. _a link: https://domain.invalid/

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-targets

1.3.1.9 Internal links
......................

Internal linking is done via a special reST role provided by Sphinx, see
the section on specific markup, see Cross-referencing arbitrary locations.

1.3.1.10 Sections
.................

Section headers (ref(1)) 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’s Style Guide for documenting(2) 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.

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#sections

   (2) https://docs.python.org/devguide/documenting.html#style-guide

1.3.1.11 Field Lists
....................

Field lists (ref(1)) 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 Field Lists
for more information.

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists

1.3.1.12 Roles
..............

A role or “custom interpreted text role” (ref(1)) 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:

   * emphasis(2) – equivalent of ‘*emphasis*’

   * strong(3) – equivalent of ‘**strong**’

   * literal(4) – equivalent of ‘``literal``’

   * subscript(5) – subscript text

   * superscript(6) – superscript text

   * title-reference(7) – for titles of books, periodicals, and other
     materials

Refer to Roles for roles added by Sphinx.

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#roles

   (2) https://docutils.sourceforge.io/docs/ref/rst/roles.html#emphasis

   (3) https://docutils.sourceforge.io/docs/ref/rst/roles.html#strong

   (4) https://docutils.sourceforge.io/docs/ref/rst/roles.html#literal

   (5) https://docutils.sourceforge.io/docs/ref/rst/roles.html#subscript

   (6)
https://docutils.sourceforge.io/docs/ref/rst/roles.html#superscript

   (7)
https://docutils.sourceforge.io/docs/ref/rst/roles.html#title-reference

1.3.1.13 Explicit Markup
........................

“Explicit markup” (ref(1)) 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.)

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#explicit-markup-blocks

1.3.1.14 Directives
...................

A directive (ref(1)) 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: attention(2), caution(3), danger(4), error(5),
     hint(6), important(7), note(8), tip(9), warning(10) and the generic
     admonition(11).  (Most themes style only “note” and “warning”
     specially.)

   * Images:

        - image(12) (see also Images below)

        - figure(13) (an image with caption and optional legend)

   * Additional body elements:

        - contents(14) (a local, i.e.  for the current file only, table
          of contents)

        - container(15) (a container with a custom class, useful to
          generate an outer ‘<div>’ in HTML)

        - rubric(16) (a heading without relation to the document
          sectioning)

        - topic(17), sidebar(18) (special highlighted body elements)

        - parsed-literal(19) (literal block that supports inline markup)

        - epigraph(20) (a block quote with optional attribution line)

        - highlights(21), pull-quote(22) (block quotes with their own
          class attribute)

        - compound(23) (a compound paragraph)

   * Special tables:

        - table(24) (a table with title)

        - csv-table(25) (a table generated from comma-separated values)

        - list-table(26) (a table generated from a list of lists)

   * Special directives:

        - raw(27) (include raw target-format markup)

        - include(28) (include reStructuredText from another file) – in
          Sphinx, when given an absolute include file path, this
          directive takes it as relative to the source directory

        - class(29) (assign a class attribute to the next element) (30)

   * HTML specifics:

        - meta(31) (generation of HTML ‘<meta>’ tags, see also
          HTML Metadata below)

        - title(32) (override document title)

   * Influencing markup:

        - default-role(33) (set a new default role)

        - role(34) (create a new role)

     Since these are only per-file, better use Sphinx’s facilities for
     setting the default_role.

     Warning: Do `not' use the directives sectnum(35), header(36) and
     footer(37).

Directives added by Sphinx are described in 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.

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#directives

   (2)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#attention

   (3)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#caution

   (4)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#danger

   (5)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#error

   (6) https://docutils.sourceforge.io/docs/ref/rst/directives.html#hint

   (7)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#important

   (8) https://docutils.sourceforge.io/docs/ref/rst/directives.html#note

   (9) https://docutils.sourceforge.io/docs/ref/rst/directives.html#tip

   (10)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#warning

   (11)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions

   (12)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#image

   (13)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure

   (14)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents

   (15)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#container

   (16)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#rubric

   (17)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic

   (18)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#sidebar

   (19)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#parsed-literal

   (20)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#epigraph

   (21)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#highlights

   (22)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#pull-quote

   (23)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#compound-paragraph

   (24)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#table

   (25)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table

   (26)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table

   (27)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#raw-data-pass-through

   (28)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#include

   (29)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#class

   (30) When the default domain contains a ‘class’ directive, this
directive will be shadowed.  Therefore, Sphinx re-exports it as
‘rst-class’.

   (31)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#meta

   (32)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata-document-title

   (33)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#default-role

   (34)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#role

   (35)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#sectnum

   (36)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#header

   (37)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#footer

1.3.1.15 Images
...............

reST supports an image directive (ref(1)), 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 ‘gnu.pdf’ and ‘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
Builders.

Note that image file names should not contain spaces.

Changed in version 0.4: Added the support for file names ending in an
asterisk.

Changed in version 0.6: Image paths can now be absolute.

Changed in version 1.5: latex target supports pixels (default is
‘96px=1in’).

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#image

1.3.1.16 Footnotes
..................

For footnotes (ref(1)), 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 (‘[#]_’).

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#footnotes

1.3.1.17 Citations
..................

Standard reST citations (ref(1)) 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 ‘#’.

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#citations

1.3.1.18 Substitutions
......................

reST supports “substitutions” (ref(1)), 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 reST reference for substitutions(2) for details.

If you want to use some substitutions for all documents, put them into
rst_prolog or rst_epilog or put them into a
separate file and include it into all documents you want to use them in,
using the ‘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 Substitutions.

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions

   (2)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions

1.3.1.19 Comments
.................

Every explicit markup block which isn’t a valid markup construct (like
the footnotes above) is regarded as a comment (ref(1)).  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.

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#comments

1.3.1.20 HTML Metadata
......................

The ‘meta’ directive (ref(1)) allows specifying the HTML metadata
element(2) 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:

     <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.

   ---------- Footnotes ----------

   (1) https://docutils.sourceforge.io/docs/ref/rst/directives.html#meta

   (2) https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta

1.3.1.21 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
source_encoding config value.

1.3.1.22 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
     the reference(1) for the details.

   * `No nested inline markup:' Something like ‘*see :func:`foo`*’ is
     not possible.

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions

1.3.2 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 default_role config value to set
     it to a known role – the any role to find anything or
     the py;obj role to find Python objects are very useful
     for this.

See Domains for roles added by domains.

1.3.2.1 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.

1.3.2.2 Cross-referencing anything
..................................

 -- reStructuredText Role: :any:

     New in version 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 doc, ref or option.

          Custom objects added to the standard domain by extensions (see
          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 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 any role also works together with the
     intersphinx extension: when no local cross-reference is found,
     all object types of intersphinx inventories are also searched.

1.3.2.3 Cross-referencing objects
.................................

These roles are described with their respective domains:

   * Python.

   * C.

   * C++.

   * JavaScript.

   * ReST.

1.3.2.4 Cross-referencing arbitrary locations
.............................................

 -- reStructuredText 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 table(1) 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 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.

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#table

1.3.2.5 Cross-referencing documents
...................................

New in version 0.6.

There is also a way to directly link to documents:

 -- reStructuredText 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.

1.3.2.6 Referencing downloadable files
......................................

New in version 0.6.

 -- reStructuredText 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>`.

1.3.2.7 Cross-referencing figures by figure number
..................................................

New in version 1.3.

Changed in version 1.5: ‘numref’ role can also refer sections.  And
‘numref’ allows ‘{name}’ for the link text.

 -- reStructuredText 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 numfig_format.
     setting is used as fall-back default.

     If numfig is ‘False’, figures are not numbered, so this
     role inserts not a reference but the label or the link text.

1.3.2.8 Cross-referencing other items of interest
.................................................

The following roles do possibly create a cross-reference, but do not
refer to objects:

 -- reStructuredText Role: :envvar:

     An environment variable.  Index entries are generated.  Also
     generates a link to the matching envvar directive, if it
     exists.

 -- reStructuredText Role: :token:

     The name of a grammar token (used to create links between
     productionlist directives).

 -- reStructuredText Role: :keyword:

     The name of a keyword in Python.  This creates a link to a
     reference label with that name, if it exists.

 -- reStructuredText Role: :option:

     A command-line option to an executable program.  This generates a
     link to a option directive, if it exists.

The following role creates a cross-reference to a term in a
glossary.:

 -- reStructuredText 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.

1.3.2.9 Math
............

 -- reStructuredText Role: :math:

     Role for inline math.  Use like this:

          Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.

 -- reStructuredText Role: :eq:

     Same as math;numref.

1.3.2.10 Other semantic markup
..............................

The following roles don’t do anything special except formatting the text
in a different style:

 -- reStructuredText 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.

     Example: ‘:abbr:`LIFO (last-in, first-out)`’.

     New in version 0.6.

 -- reStructuredText Role: :command:

     The name of an OS-level command, such as ‘rm’.

 -- reStructuredText Role: :dfn:

     Mark the defining instance of a term in the text.  (No index
     entries are generated.)

 -- reStructuredText 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/python2.{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.

 -- reStructuredText 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 curses(1) 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.

     Changed in version 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 (example: ‘:guilabel:`&Cancel`’).  To
     include a literal ampersand, double it.

 -- reStructuredText 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`’.

 -- reStructuredText 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`’.

 -- reStructuredText Role: :makevar:

     The name of a ‘make’ variable.

 -- reStructuredText Role: :manpage:

     A reference to a Unix manual page including the section, e.g.
     ‘:manpage:`ls(1)`’.  Creates a hyperlink to an external site
     rendering the manpage if manpages_url is defined.

 -- reStructuredText 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`

     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
     guilabel.

 -- reStructuredText Role: :mimetype:

     The name of a MIME type, or a component of a MIME type (the major
     or minor portion, taken alone).

 -- reStructuredText Role: :newsgroup:

     The name of a Usenet newsgroup.

     Todo: Is this not part of the standard domain?

 -- reStructuredText 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.

 -- reStructuredText Role: :regexp:

     A regular expression.  Quotes should not be included.

 -- reStructuredText 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
     file.  For example, in ‘:samp:`print 1+{variable}`’, the part
     ‘variable’ would be emphasized.

     If you don’t need the “variable part” indication, use the standard
     ‘``code``’ instead.

     Changed in version 1.8: Allowed to escape curly braces with
     backslash

There is also an index role to generate index entries.

The following roles generate external links:

 -- reStructuredText 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`’.

 -- reStructuredText 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`’.

Note that there are no special roles for including hyperlinks as you can
use the standard reST markup for that purpose.

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/library/curses.html#module-curses

1.3.2.11 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 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 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 today_fmt and
     today.

1.3.3 Directives
----------------

See As previously discussed, 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 Domains for roles added by domains.

See also
........

Refer to the reStructuredText Primer for an overview of the
directives provided by Docutils.

1.3.3.1 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 include(1) directive.

     Note: To create table of contents for current document (.rst file),
     use the standard reST contents directive(2).

 -- reStructuredText 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.  (3)

     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 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
     cross-referencing 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 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.)
     (4)

     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 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 exclude_patterns to explicitly exclude documents or
     directories from building completely.  Use the “orphan” metadata
     to let a document be built, but notify Sphinx that it
     is not reachable via a toctree.

     The “root document” (selected by 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.

     Changed in version 0.3: Added “globbing” option.

     Changed in version 0.6: Added “numbered” and “hidden” options as
     well as external links and support for “self” references.

     Changed in version 1.0: Added “titlesonly” option.

     Changed in version 1.1: Added numeric argument to “numbered”.

     Changed in version 1.2: Added “includehidden” option.

     Changed in version 1.3: Added “caption” and “name” option.

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#include

   (2)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents

   (3) The LaTeX writer only refers the ‘maxdepth’ option of first
toctree directive in the document.

   (4) 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.

1.3.3.2 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 object descriptions, and from
     index directives.

     The Python module index contains one entry per 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.

1.3.3.3 Paragraph-level markup
..............................

These directives create short paragraphs and can be used inside
information units as well as normal text.

 -- reStructuredText 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.

 -- reStructuredText 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 note in that it is recommended over note.
     for information regarding security.

 -- reStructuredText 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.

 -- reStructuredText Directive: .. versionchanged:: version

     Similar to versionadded, but describes when and what
     changed in the named feature in some way (new parameters, changed
     side effects, etc.).

 -- reStructuredText Directive: .. deprecated:: version

     Similar to 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.

 -- reStructuredText Directive: .. seealso::

     Many sections include a list of references to module documentation
     or external documents.  These lists are created using the
     seealso directive.

     The 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 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`

     New in version 0.5: The short form.

 -- reStructuredText 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.

 -- reStructuredText Directive: .. centered::

     This directive creates a centered boldfaced line of text.  Use it
     as follows:

          .. centered:: LICENSE AGREEMENT

     Deprecated since version 1.1: This presentation-only directive is a
     legacy from older versions.  Use a ‘rst-class’ directive instead
     and add an appropriate style.

 -- reStructuredText 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

     New in version 0.6.

1.3.3.4 Showing code examples
.............................

There are multiple ways to show syntax-highlighted literal code blocks
in Sphinx:

   * using reST doctest blocks.;

   * using reST literal blocks, optionally in combination with
     the highlight directive;

   * using the code-block directive;

   * and using the 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
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
literalinclude directive is useful for including entire code
files in your documentation.

In all cases, Syntax highlighting is provided by Pygments(1).  When
using literal blocks, this is configured using any 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 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
     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(2)

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.

 -- reStructuredText 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.

     options
     .......

      -- reStructuredText directive-option: :linenothreshold: threshold
               (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

      -- reStructuredText directive-option: :force: (no value)

          If given, minor errors on highlighting are ignored.

          New in version 2.1.

 -- reStructuredText Directive: .. code-block:: [language]

     Example:

          .. code-block:: ruby

             Some Ruby code.

     The directive’s alias name ‘sourcecode’ works as well.  This
     directive takes a language name as an argument.  It can be any
     lexer alias supported by Pygments(3).  If it is not given, the
     setting of highlight directive will be used.  If not
     set, see highlight_language will be used.

     Changed in version 2.0: The ‘language’ argument becomes optional.

     options
     .......

      -- reStructuredText directive-option: :linenos: (no value)

          Enable to generate line numbers for the code block:

               .. code-block:: ruby
                  :linenos:

                  Some more Ruby code.

      -- reStructuredText directive-option: :lineno-start: number
               (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.

          New in version 1.3.

      -- reStructuredText directive-option: :emphasize-lines: line
               numbers (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.'

          New in version 1.1.

          Changed in version 1.6.6: LaTeX supports the ‘emphasize-lines’
          option.

      -- reStructuredText directive-option: :caption: caption of code
               block (text)

          Set a caption to the code block.

          New in version 1.3.

      -- reStructuredText directive-option: :name: a label for hyperlink
               (text)

          Define implicit target name that can be referenced by using
          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
          ref or the numref role, it is necessary
          that both `name' and `caption' be defined.  The argument of
          `name' can then be given to numref to generate the
          cross-reference.  Example:

               See :numref:`this-py` for an example.

          When using ref, it is possible to generate a
          cross-reference with only `name' defined, provided an explicit
          title is given.  Example:

               See :ref:`this code snippet <this-py>` for an example.

          New in version 1.3.

      -- reStructuredText directive-option: :dedent: number (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 textwrap.dedent()(4).
          For example:

               .. code-block:: ruby
                  :linenos:
                  :dedent: 4

                      some ruby code

          New in version 1.3.

          Changed in version 3.5: Support automatic dedent.

      -- reStructuredText directive-option: :force: (no value)

          If given, minor errors on highlighting are ignored.

          New in version 2.1.

 -- reStructuredText 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.  (5) For
     example, to include the Python source 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 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
     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]’:

               [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: [initialized]’ and ‘:end-before: [initialized]’
          options keep lines between comments:

               if __name__ == "__main__":
                   # [initialize]
                   app.start(":8000")
                   # [initialize]

     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.

     Changed in version 0.4.3: Added the ‘encoding’ option.

     Changed in version 0.6: Added the ‘pyobject’, ‘lines’,
     ‘start-after’ and ‘end-before’ options, as well as support for
     absolute filenames.

     Changed in version 1.0: Added the ‘prepend’, ‘append’, and
     ‘tab-width’ options.

     Changed in version 1.3: Added the ‘diff’, ‘lineno-match’,
     ‘caption’, ‘name’, and ‘dedent’ options.

     Changed in version 1.5: Added the ‘start-at’, and ‘end-at’ options.

     Changed in version 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’.

     Changed in version 2.1: Added the ‘force’ option.

     Changed in version 3.5: Support automatic dedent.

   ---------- Footnotes ----------

   (1) https://pygments.org

   (2) https://pygments.org/docs/lexers

   (3) https://pygments.org/docs/lexers/

   (4) https://docs.python.org/3/library/textwrap.html#textwrap.dedent

   (5) There is a standard ‘.. include’ directive, but it raises errors
if the file is not found.  This one only emits a warning.

1.3.3.5 Glossary
................

 -- reStructuredText Directive: .. glossary::

     This directive must contain a reST definition-list-like markup with
     terms and definitions.  The definitions will then be referenceable
     with the 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.

     New in version 0.6: You can now give the glossary directive a
     ‘:sorted:’ flag that will automatically sort the entries
     alphabetically.

     Changed in version 1.1: Now supports multiple terms and inline
     markup in terms.

     Changed in version 1.4: Index key for glossary term should be
     considered `experimental'.

     Changed in version 4.4: In internationalized documentation, the
     ‘:sorted:’ flag sorts according to translated terms.

1.3.3.6 Meta-information markup
...............................

 -- reStructuredText 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 show_authors to ‘True’ to make them
     produce a paragraph in the output.

 -- reStructuredText Directive: .. codeauthor:: name <email>

     The codeauthor directive, which can appear multiple
     times, names the authors of the described code, just like
     sectionauthor names the author(s) of a piece of
     documentation.  It too only produces output if the
     show_authors configuration value is ‘True’.

1.3.3.7 Index-generating markup
...............................

Sphinx automatically creates index entries from all object descriptions
(like functions, classes or attributes) like discussed in 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.

 -- reStructuredText 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
             module: __main__
             module: sys
             triple: module; search; path

          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 subentry by
          separating the subentry text with a semicolon (this notation
          is also used below to describe what entries are created).

     pair

          ‘pair: loop; statement’ is a shortcut that creates two index
          entries, namely ‘loop; statement’ and ‘statement; loop’.

     triple

          Likewise, ‘triple: module; search; path’ is a shortcut that
          creates three index entries, which are ‘module; search path’,
          ‘search; path, module’ and ‘path; module search’.

     see

          ‘see: entry; other’ creates an index entry that refers from
          ‘entry’ to ‘other’.

     seealso

          Like ‘see’, but inserts “see also” instead of “see”.

     module, keyword, operator, object, exception, statement, builtin

          These all create two index entries.  For example, ‘module:
          hashlib’ creates the entries ‘module; hashlib’ and ‘hashlib;
          module’.  (These are Python-specific and therefore
          deprecated.)

     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.

     Changed in version 1.1: Added ‘see’ and ‘seealso’ types, as well as
     marking main entries.

     options
     .......

      -- reStructuredText directive-option: :name: a label for hyperlink
               (text)

          Define implicit target name that can be referenced by using
          ref.  For example:

               .. index:: Python
                  :name: py-index

     New in version 3.0.

 -- reStructuredText Role: :index:

     While the 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>`.

     New in version 1.1.

1.3.3.8 Including content based on tags
.......................................

 -- reStructuredText 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 ‘conf.py’, see here) 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 (1).  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(2) 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’.

     New in version 0.6.

     Changed in version 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.

   ---------- Footnotes ----------

   (1) 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.

   (2)
https://docs.python.org/3/reference/lexical_analysis.html#identifiers

1.3.3.9 Tables
..............

Use reStructuredText tables, i.e.  either

   - grid table syntax (ref(1)),

   - simple table syntax (ref(2)),

   - csv-table(3) syntax,

   - or list-table(4) syntax.

The table(5) directive serves as optional wrapper of the `grid' and
`simple' syntaxes.

They work fine in HTML output, however there are some gotchas when using
tables in LaTeX: the column width is hard to determine correctly
automatically.  For this reason, the following directive exists:

 -- reStructuredText Directive: .. tabularcolumns:: column spec

     This directive gives a “column spec” for the next table occurring
     in the source file.  The spec is the second argument to the LaTeX
     ‘tabulary’ package’s environment (which Sphinx uses to translate
     tables).  It can have values like

          |l|l|l|

     which means three left-adjusted, nonbreaking columns.  For columns
     with longer text that should automatically be broken, use either
     the standard ‘p{width}’ construct, or tabulary’s automatic
     specifiers:

     ‘L’       flush left column with automatic width

     ‘R’       flush right column with automatic width

     ‘C’       centered column with automatic width

     ‘J’       justified column with automatic width

     The automatic widths of the ‘LRCJ’ columns are attributed by
     ‘tabulary’ in proportion to the observed shares in a first pass
     where the table cells are rendered at their natural “horizontal”
     widths.

     By default, Sphinx uses a table layout with ‘J’ for every column.

     New in version 0.3.

     Changed in version 1.6: Merged cells may now contain multiple
     paragraphs and are much better handled, thanks to custom Sphinx
     LaTeX macros.  This novel situation motivated the switch to ‘J’
     specifier and not ‘L’ by default.

          Hint: Sphinx actually uses ‘T’ specifier having done
          ‘\newcolumntype{T}{J}’.  To revert to previous default, insert
          ‘\newcolumntype{T}{L}’ in the LaTeX preamble (see
          latex_elements).

          A frequent issue with tabulary is that columns with little
          contents are “squeezed”.  The minimal column width is a
          tabulary parameter called ‘\tymin’.  You may set it globally
          in the LaTeX preamble via ‘\setlength{\tymin}{40pt}’ for
          example.

          Else, use the tabularcolumns directive with an
          explicit ‘p{40pt}’ (for example) for that column.  You may use
          also ‘l’ specifier but this makes the task of setting column
          widths more difficult if some merged cell intersects that
          column.

          Warning: Tables with more than 30 rows are rendered using
          ‘longtable’, not ‘tabulary’, in order to allow pagebreaks.
          The ‘L’, ‘R’, … specifiers do not work for these tables.

          Tables that contain list-like elements such as object
          descriptions, blockquotes or any kind of lists cannot be set
          out of the box with ‘tabulary’.  They are therefore set with
          the standard LaTeX ‘tabular’ (or ‘longtable’) environment if
          you don’t give a ‘tabularcolumns’ directive.  If you do, the
          table will be set with ‘tabulary’ but you must use the
          ‘p{width}’ construct (or Sphinx’s ‘\X’ and ‘\Y’ specifiers
          described below) for the columns containing these elements.

          Literal blocks do not work with ‘tabulary’ at all, so tables
          containing a literal block are always set with ‘tabular’.  The
          verbatim environment used for literal blocks only works in
          ‘p{width}’ (and ‘\X’ or ‘\Y’) columns, hence Sphinx generates
          such column specs for tables containing literal blocks.

     Since Sphinx 1.5, the ‘\X{a}{b}’ specifier is used (there `is' a
     backslash in the specifier letter).  It is like ‘p{width}’ with the
     width set to a fraction ‘a/b’ of the current line width.  You can
     use it in the tabularcolumns. (it is not a problem if
     some LaTeX macro is also called ‘\X’.)

     It is `not' needed for ‘b’ to be the total number of columns, nor
     for the sum of the fractions of the ‘\X’ specifiers to add up to
     one.  For example ‘|\X{2}{5}|\X{1}{5}|\X{1}{5}|’ is legitimate and
     the table will occupy 80% of the line width, the first of its three
     columns having the same width as the sum of the next two.

     This is used by the ‘:widths:’ option of the table(6) directive.

     Since Sphinx 1.6, there is also the ‘\Y{f}’ specifier which admits
     a decimal argument, such has ‘\Y{0.15}’: this would have the same
     effect as ‘\X{3}{20}’.

     Changed in version 1.6: Merged cells from complex grid tables
     (either multi-row, multi-column, or both) now allow blockquotes,
     lists, literal blocks, … as do regular cells.

     Sphinx’s merged cells interact well with ‘p{width}’, ‘\X{a}{b}’,
     ‘\Y{f}’ and tabulary’s columns.

          Note: tabularcolumns conflicts with ‘:widths:’
          option of table directives.  If both are specified, ‘:widths:’
          option will be ignored.

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#grid-tables

   (2)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#simple-tables

   (3)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table

   (4)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table

   (5)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#table

   (6)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#table

1.3.3.10 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 autodoc, you either have to double all backslashes, or use
Python raw strings (‘r"raw"’).

 -- reStructuredText 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(1).

     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
     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}

See also
........

See Math support for HTML outputs in Sphinx.

     Rendering options for math with HTML builders.

See latex_engine.

     Explains how to configure LaTeX builder to support Unicode literals
     in math mark-up.

   ---------- Footnotes ----------

   (1) https://www.ams.org/publications/authors/tex/amslatex

1.3.3.11 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:

 -- reStructuredText 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 token.

     The `productionGroup' argument to 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`

1.3.4 Field Lists
-----------------

See As previously discussed, 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.

1.3.4.1 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.

1.3.4.2 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.

     New in version 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:

     New in version 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.

     New in version 3.0.

1.3.5 Domains
-------------

New in version 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 directive.
s and role.s) to describe and link to 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
Domain API.

1.3.5.1 Basic Markup
....................

Most domains provide a number of `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 ‘:noindexentry:’.
If you want to typeset an object description, without even making it
available for cross-referencing, you can give the directive option flag
‘:noindex:’ (which implies ‘:noindexentry:’).  Though, note that not
every directive in every domain may support these options.

New in version 3.2: The directive option ‘noindexentry’ in the Python,
C, C++, and Javascript domains.

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)
        :noindex:

(This example also shows how to use the ‘:noindex:’ 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.

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 primary_domain or via this directive:

 -- reStructuredText Directive: .. default-domain:: name

     Select a new default domain.  While the 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`.

1.3.5.2 Cross-referencing syntax
................................

For cross-reference roles provided by domains, the same facilities exist
as for general cross-references.  See Cross-referencing 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.

1.3.5.3 The Python Domain
.........................

The Python domain (name `py') provides the following directives for
module declarations:

 -- reStructuredText 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).  It does not create content
     (like e.g.  see py;class does).

     This directive will also cause an entry in the global module index.

     options
     .......

      -- reStructuredText directive-option: :platform: platforms (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.

      -- reStructuredText directive-option: :synopsis: purpose (text)

          Consist of one sentence describing the module’s purpose – it
          is currently only used in the Global Module Index.

      -- reStructuredText directive-option: :deprecated: (no argument)

          Mark a module as deprecated; it will be designated as such in
          various locations then.

 -- reStructuredText Directive: .. py:currentmodule:: name

     This directive tells Sphinx that the classes, functions etc.
     documented from here are in the given module (like py;module),
     but it will not create index entries, an entry in the Global
     Module Index, or a link target for 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
     py;module directive, the others only py;currentmodule.

The following directives are provided for module and class contents:

 -- reStructuredText Directive: .. py:function:: name(parameters)

     Describes a module-level function.  The signature should include
     the parameters as given in the Python function definition, see
     Python Signatures.  For example:

          .. py:function:: Timer.repeat(repeat=3, number=1000000)

     For methods you should use 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 Info field lists.

     options
     .......

      -- reStructuredText directive-option: :async: (no value)

          Indicate the function is an async function.

          New in version 2.1.

      -- reStructuredText directive-option: :canonical: (full qualified
               name including module name)

          Describe the location where the object is defined if the
          object is imported from other modules

          New in version 4.0.

 -- reStructuredText 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.

     options
     .......

      -- reStructuredText directive-option: :type: type of the variable
               (text)

          New in version 2.4.

      -- reStructuredText directive-option: :value: initial value of the
               variable (text)

          New in version 2.4.

      -- reStructuredText directive-option: :canonical: (full qualified
               name including module name)

          Describe the location where the object is defined if the
          object is imported from other modules

          New in version 4.0.

 -- reStructuredText Directive: .. py:exception:: name

     Describes an exception class.  The signature can, but need not
     include parentheses with constructor arguments.

     options
     .......

      -- reStructuredText directive-option: :final: (no value)

          Indicate the class is a final class.

          New in version 3.1.

 -- reStructuredText Directive: .. py:class:: name

 -- reStructuredText Directive: .. py:class:: name(parameters)

     Describes a class.  The signature can optionally include
     parentheses with parameters which will be shown as the constructor
     arguments.  See also Python 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.

     options
     .......

      -- reStructuredText directive-option: :canonical: (full qualified
               name including module name)

          Describe the location where the object is defined if the
          object is imported from other modules

          New in version 4.0.

      -- reStructuredText directive-option: :final: (no value)

          Indicate the class is a final class.

          New in version 3.1.

 -- reStructuredText 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.

     options
     .......

      -- reStructuredText directive-option: :type: type of the attribute
               (text)

          New in version 2.4.

      -- reStructuredText directive-option: :value: initial value of the
               attribute (text)

          New in version 2.4.

      -- reStructuredText directive-option: :canonical: (full qualified
               name including module name)

          Describe the location where the object is defined if the
          object is imported from other modules

          New in version 4.0.

 -- reStructuredText Directive: .. py:property:: name

     Describes an object property.

     New in version 4.0.

     options
     .......

      -- reStructuredText directive-option: :abstractmethod: (no value)

          Indicate the property is abstract.

      -- reStructuredText directive-option: :classmethod: (no value)

          Indicate the property is a classmethod.

      -- reStructuredText directive-option: :type: type of the property
               (text)

 -- reStructuredText Directive: .. py:method:: name(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
     Python Signatures and Info field lists.

     options
     .......

      -- reStructuredText directive-option: :abstractmethod: (no value)

          Indicate the method is an abstract method.

          New in version 2.1.

      -- reStructuredText directive-option: :async: (no value)

          Indicate the method is an async method.

          New in version 2.1.

      -- reStructuredText directive-option: :canonical: (full qualified
               name including module name)

          Describe the location where the object is defined if the
          object is imported from other modules

          New in version 4.0.

      -- reStructuredText directive-option: :classmethod: (no value)

          Indicate the method is a class method.

          New in version 2.1.

      -- reStructuredText directive-option: :final: (no value)

          Indicate the class is a final method.

          New in version 3.1.

      -- reStructuredText directive-option: :property: (no value)

          Indicate the method is a property.

          New in version 2.1.

          Deprecated since version 4.0: Use py;property.
          instead.

      -- reStructuredText directive-option: :staticmethod: (no value)

          Indicate the method is a static method.

          New in version 2.1.

 -- reStructuredText Directive: .. py:staticmethod:: name(parameters)

     Like py;method, but indicates that the method is a static
     method.

     New in version 0.4.

 -- reStructuredText Directive: .. py:classmethod:: name(parameters)

     Like py;method, but indicates that the method is a class
     method.

     New in version 0.6.

 -- reStructuredText Directive: .. py:decorator:: name

 -- reStructuredText Directive: .. py:decorator:: name(parameters)

     Describes a decorator function.  The signature should represent the
     usage as a decorator.  For example, given the functions

          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 py;func role.

 -- reStructuredText Directive: .. py:decoratormethod:: name

 -- reStructuredText Directive: .. py:decoratormethod:: name(signature)

     Same as py;decorator, but for decorators that are
     methods.

     Refer to a decorator method using the py;meth role.

1.3.5.4 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:

      -- Function: compile (source[, filename[, symbol]])

It is customary to put the opening bracket before the comma.

1.3.5.5 Info field lists
........................

New in version 0.4.

Changed in version 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 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:

      -- Function: send_message (sender, recipient, message_body[,
               priority=1])

          Send a message to a recipient

          Parameters:

             * ‘sender’ (str(1)) – The person sending the message

             * ‘recipient’ (str(2)) – The recipient of the message

             * ‘message_body’ (str(3)) – The body of the message

             * ‘priority’ (‘integer’‘ or ’‘None’) – The priority of the
               message, can be a number 1-5

          Returns: the message id

          Return type: int(4)

          Raises:

             * ValueError(5) – if the message_body exceeds 160
               characters

             * TypeError(6) – 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

New in version 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

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/library/stdtypes.html#str

   (2) https://docs.python.org/3/library/stdtypes.html#str

   (3) https://docs.python.org/3/library/stdtypes.html#str

   (4) https://docs.python.org/3/library/functions.html#int

   (5) https://docs.python.org/3/library/exceptions.html#ValueError

   (6) https://docs.python.org/3/library/exceptions.html#TypeError

1.3.5.6 Cross-referencing Python objects
........................................

The following roles refer to objects in modules and are possibly
hyperlinked if a matching identifier is found:

 -- reStructuredText Role: :py:mod:

     Reference a module; a dotted name may be used.  This should also be
     used for package names.

 -- reStructuredText 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
     add_function_parentheses config value is ‘True’ (the
     default).

 -- reStructuredText Role: :py:data:

     Reference a module-level variable.

 -- reStructuredText Role: :py:const:

     Reference a “defined” constant.  This may be a Python variable that
     is not intended to be changed.

 -- reStructuredText Role: :py:class:

     Reference a class; a dotted name may be used.

 -- reStructuredText 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.

 -- reStructuredText Role: :py:attr:

     Reference a data attribute of an object.

          Note: The role is also able to refer to property.

 -- reStructuredText Role: :py:exc:

     Reference an exception.  A dotted name may be used.

 -- reStructuredText Role: :py:obj:

     Reference an object of unspecified type.  Useful e.g.  as the
     default_role.

     New in version 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 codecs(1) module, ‘:py:func:`open`’ always
refers to the built-in function, while ‘:py:func:`.open`’ refers to
codecs.open()(2).

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()’.

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/library/codecs.html#module-codecs

   (2) https://docs.python.org/3/library/codecs.html#codecs.open

1.3.5.7 The C Domain
....................

The C domain (name `c') is suited for documentation of C API.

 -- reStructuredText Directive: .. c:member:: declaration
 -- reStructuredText Directive: .. 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.

 -- reStructuredText 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 Info field lists).

        * ‘param’, ‘parameter’, ‘arg’, ‘argument’, Description of a
          parameter.

        * ‘type’: Type of a parameter, written as if passed to the
          c;expr role.

        * ‘returns’, ‘return’: Description of the return value.

        * ‘rtype’: Return type, written as if passed to the
          c;expr role.

        * ‘retval’, ‘retvals’: An alternative to ‘returns’ for
          describing the result of the function.

     New in version 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(1) *PyType_GenericAlloc (PyTypeObject
               *type, Py_ssize_t nitems)

          Parameters:

             * ‘type’ – description of the first parameter.

             * ‘nitems’ – description of the second parameter.

          Returns: a result.

          Return values:

             * ‘NULL’ – under some conditions.

             * ‘NULL’ – under some other conditions as well.

 -- reStructuredText Directive: .. c:macro:: name

 -- reStructuredText Directive: .. 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 c;function directive.

     New in version 3.0: The function style variant.

 -- reStructuredText Directive: .. c:struct:: name

     Describes a C struct.

     New in version 3.0.

 -- reStructuredText Directive: .. c:union:: name

     Describes a C union.

     New in version 3.0.

 -- reStructuredText Directive: .. c:enum:: name

     Describes a C enum.

     New in version 3.0.

 -- reStructuredText Directive: .. c:enumerator:: name

     Describes a C enumerator.

     New in version 3.0.

 -- reStructuredText Directive: .. c:type:: typedef-like declaration

 -- reStructuredText Directive: .. c:type:: name

     Describes a C type, either as a typedef, or the alias for an
     unspecified type.

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/c-api/structures.html#c.PyObject

1.3.5.8 Cross-referencing C constructs
......................................

The following roles create cross-references to C-language constructs if
they are defined in the documentation:

 -- reStructuredText Role: :c:member:
 -- reStructuredText Role: :c:data:
 -- reStructuredText Role: :c:var:
 -- reStructuredText Role: :c:func:
 -- reStructuredText Role: :c:macro:
 -- reStructuredText Role: :c:struct:
 -- reStructuredText Role: :c:union:
 -- reStructuredText Role: :c:enum:
 -- reStructuredText Role: :c:enumerator:
 -- reStructuredText Role: :c:type:

     Reference a C declaration, as defined above.  Note that
     c;member, c;data, and c;var are
     equivalent.

     New in version 3.0: The var, struct, union, enum, and enumerator
     roles.

1.3.5.9 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: struct Data

      -- C Union: union [anonymous]

           -- C Variable: int a

           -- C Variable: double b

Explicit ref: Data.[anonymous].a.  Short-hand ref:
Data.a.

New in version 3.0.

1.3.5.10 Aliasing Declarations
..............................

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.

 -- reStructuredText Directive: .. c:alias:: name

     Insert one or more alias declarations.  Each entity can be
     specified as they can in the ‘c:any’ role.

     For example:

          .. c:var:: int data
          .. c:function:: int f(double k)

          .. c:alias:: data
                       f

     becomes

      -- C Variable: int data

      -- C Function: int f (double k)

      -- Alias: int data.

      -- Alias: int f.(double k)

     New in version 3.2.

     Options
     .......

      -- reStructuredText 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.

          New in version 3.3.

      -- reStructuredText directive-option: :noroot:

          Skip the mentioned declarations and only render nested
          declarations.  Requires ‘maxdepth’ either 0 or at least 2.

          New in version 3.5.

1.3.5.11 Inline Expressions and Types
.....................................

 -- reStructuredText Role: :c:expr:
 -- reStructuredText Role: :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 Variable: int a = 42

      -- C Function: int f (int i)

     An expression: a. * See f.(see a) (or as
     text: a. * See f.(see a)).

     A type: const Data.* (or as text const Data.
     *).

     New in version 3.0.

1.3.5.12 Namespacing
....................

New in version 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.

 -- reStructuredText 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.

 -- reStructuredText 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’.

 -- reStructuredText 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

1.3.5.13 Configuration Variables
................................

See Options for the C domain.

1.3.5.14 The C++ Domain
.......................

The C++ domain (name `cpp') supports documenting C++ projects.

1.3.5.15 Directives for Declaring Entities
..........................................

The following directives are available.  All declarations can start with
a visibility statement (‘public’, ‘private’ or ‘protected’).

 -- reStructuredText Directive: .. cpp:class:: class specifier
 -- reStructuredText Directive: .. cpp:struct:: class specifier

     Describe a class/struct, possibly with specification of
     inheritance, e.g.,:

          .. cpp:class:: MyClass : public MyBase, MyOtherBase

     The difference between cpp;class and 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>

     New in version 2.0: The cpp;struct directive.

 -- reStructuredText 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)

 -- reStructuredText Directive: .. cpp:member:: (member) variable
          declaration
 -- reStructuredText Directive: .. 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)

 -- reStructuredText Directive: .. cpp:type:: typedef declaration

 -- reStructuredText Directive: .. cpp:type:: name

 -- reStructuredText Directive: .. 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.

      -- C++ Type: typedef std::vector<int> MyList

          A typedef-like declaration of a type.

      -- C++ Type: type MyContainer::const_iterator

          Declaration of a type alias with unspecified type.

      -- C++ Type: using MyType = std::unordered_map<int, std::string>

          Declaration of a type alias.

      -- C++ Type: template<typename T>using MyContainer =
               std::vector<T.>

 -- reStructuredText Directive: .. cpp:enum:: unscoped enum declaration
 -- reStructuredText Directive: .. cpp:enum-struct:: scoped enum
          declaration
 -- reStructuredText Directive: .. 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.

 -- reStructuredText Directive: .. cpp:enumerator:: name

 -- reStructuredText Directive: .. cpp:enumerator:: name = constant

     Describe an enumerator, optionally with its value defined, e.g.,:

          .. cpp:enumerator:: MyEnum::myEnumerator

          .. cpp:enumerator:: MyEnum::myOtherEnumerator = 42

 -- reStructuredText Directive: .. cpp:union:: name

     Describe a union.

     New in version 1.8.

 -- reStructuredText 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:

      -- C++ Concept: template<typename It>concept std::Iterator

          Proxy to an element of a notional sequence that can be
          compared, indirected, or incremented.

          `Notation'

           -- Var: It r

               An lvalue.

          `Valid Expressions'

             - *See r, when r is dereferenceable.

             - ++See r, with return type It.&, when
               r is incrementable.

     New in version 1.5.

1.3.5.16 Options
................

Some directives support options:

   - ‘:noindexentry:’, see Basic Markup.

   - ‘:tparam-line-spec:’, for templated declarations.  If specified,
     each template parameter will be rendered on a separate line.

     New in version 1.6.

1.3.5.17 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:

 -- C++ Class: class Data

      -- C++ Union: union [anonymous]

           -- Var: int a

           -- Var: double b

Explicit ref: Data;;[anonymous];;a.  Short-hand ref:
Data;;a.

New in version 1.8.

1.3.5.18 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.

 -- reStructuredText Directive: .. cpp:alias:: name or function
          signature

     Insert one or more alias declarations.  Each entity can be
     specified as they can in the 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

      -- Alias: int a.

      -- Alias: void f.(double d) const

      -- Alias: void f.(double d)

      -- Alias: void f.(int i)

      -- Alias: void f.()

     whereas:

          .. cpp:alias:: void overload_example::C::f(double d) const
                         void overload_example::C::f(double d)

     becomes

      -- Alias: void f.(double d) const

      -- Alias: void f.(double d)

     New in version 2.0.

     Options
     .......

      -- reStructuredText 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.

          New in version 3.5.

      -- reStructuredText directive-option: :noroot:

          Skip the mentioned declarations and only render nested
          declarations.  Requires ‘maxdepth’ either 0 or at least 2.

          New in version 3.5.

1.3.5.19 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.

1.3.5.20 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.

1.3.5.21 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.

 -- C++ Function: std::Iterator.{It}void advance (It &it)

     A function template with a template parameter constrained to be an
     Iterator.

 -- C++ Class: std::LessThanComparable{T}class MySortedContainer

     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++.

1.3.5.22 Inline Expressions and Types
.....................................

 -- reStructuredText Role: :cpp:expr:
 -- reStructuredText Role: :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:

      -- Var: int a = 42

      -- C++ Function: int f (int i)

     An expression: a. * See f.(see a) (or as
     text: a. * See f.(see a)).

     A type: const MySortedContainer.<int>& (or as text const
     MySortedContainer.<int>&).

     New in version 1.7: The cpp;expr role.

     New in version 1.8: The cpp;texpr role.

1.3.5.23 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.

 -- reStructuredText 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

 -- reStructuredText 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’.

     New in version 1.4.

 -- reStructuredText 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

     New in version 1.4.

1.3.5.24 Info field lists
.........................

All the C++ directives for declaring entities support the following info
fields (see also Info field lists):

   * ‘tparam’: Description of a template parameter.

The 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.

New in version 4.3: The ‘retval’ field type.

1.3.5.25 Cross-referencing
..........................

These roles link to the given declaration types:

 -- reStructuredText Role: :cpp:any:
 -- reStructuredText Role: :cpp:class:
 -- reStructuredText Role: :cpp:struct:
 -- reStructuredText Role: :cpp:func:
 -- reStructuredText Role: :cpp:member:
 -- reStructuredText Role: :cpp:var:
 -- reStructuredText Role: :cpp:type:
 -- reStructuredText Role: :cpp:concept:
 -- reStructuredText Role: :cpp:enum:
 -- reStructuredText Role: :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.

     New in version 2.0: The cpp;struct role as alias for
     the cpp;class role.

     Note on References with Templates Parameters/Arguments: These roles
     follow the Sphinx Cross-referencing 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, see cpp;expr and cpp;texpr,
     where angle brackets do not need escaping.

1.3.5.26 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’.

1.3.5.27 Overloaded (member) functions
......................................

When a (member) function is referenced using just its name, the
reference will point to an arbitrary matching overload.  The
cpp;any and 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:

 -- C++ Class: class C

      -- C++ Function: void f (double d) const

      -- C++ Function: void f (double d)

      -- C++ Function: void f (int i)

      -- C++ Function: void f ()

References using the cpp;func role:

   - Arbitrary overload: ‘C::f’, see C;;f().

   - Also arbitrary overload: ‘C::f()’, see C;;f().

   - Specific overload: ‘void C::f()’, see void C;;f().

   - Specific overload: ‘void C::f(int)’, see void C;;f(int).

   - Specific overload: ‘void C::f(double)’, see void C;;f(double).

   - Specific overload: ‘void C::f(double) const’, see void C;;f(double) const.

Note that the add_function_parentheses configuration
variable does not influence specific overload references.

1.3.5.28 Templated declarations
...............................

Assume the following declarations.

 -- C++ Class: class Wrapper

      -- C++ Class: template<typename TOuter>class Outer

           -- C++ Class: template<typename TInner>class 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’ (see
     template<typename TOuter> Wrapper;;Outer)

   - ‘template\<typename TOuter> template\<typename TInner>
     Wrapper::Outer<TOuter>::Inner’ (‘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’ (see Wrapper;;Outer)

   - ‘Wrapper::Outer::Inner’ (see Wrapper;;Outer;;Inner)

   - ‘template\<typename TInner> Wrapper::Outer::Inner’ (see
     template<typename TInner> Wrapper;;Outer;;Inner)

1.3.5.29 (Full) Template Specialisations
........................................

Assume the following declarations.

 -- C++ Class: template<typename TOuter>class Outer

      -- C++ Class: template<typename TInner>class Inner

 -- C++ Class: template<>class Outer<int>

      -- C++ Class: template<typename TInner>class Inner

      -- C++ Class: template<>class 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>’ (see template<> Outer<int>)
and ‘template\<> template\<> Outer\<int>::Inner\<bool>’ (see
template<> template<> Outer<int>;;Inner<bool>).  As a shorthand
the empty template parameter list can be omitted, e.g., ‘Outer\<int>’
(see Outer<int>) and ‘Outer\<int>::Inner\<bool>’ (see
Outer<int>;;Inner<bool>).

1.3.5.30 Partial Template Specialisations
.........................................

Assume the following declaration.

 -- C++ Class: template<typename T>class Outer<T.*>

References to partial specialisations must always include the template
parameter lists, e.g., ‘template\<typename T> Outer\<T*>’ (see
template<typename T> Outer<T*>).  Currently the lookup only
succeed if the template parameter identifiers are equal strings.

1.3.5.31 Configuration Variables
................................

See Options for the C++ domain.

1.3.5.32 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 add_object_type(). API, are placed.

There is a set of directives allowing documenting command-line programs:

 -- reStructuredText 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 option. (in the example case,
     you’d use something like ‘:option:`dest_dir`’, ‘:option:`-m`’, or
     ‘:option:`--module`’).

     ‘cmdoption’ directive is a deprecated alias for the ‘option’
     directive.

 -- reStructuredText Directive: .. envvar:: name

     Describes an environment variable that the documented code or
     program uses or defines.  Referenceable by envvar.

 -- reStructuredText Directive: .. program:: name

     Like py;currentmodule, this directive produces no
     output.  Instead, it serves to notify Sphinx that all following
     option directives document options for the program
     called `name'.

     If you use program, you have to qualify the references
     in your 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).

     New in version 0.5.

There is also a very generic object description directive, which is not
tied to any domain:

 -- reStructuredText Directive: .. describe:: text
 -- reStructuredText Directive: .. 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.

1.3.5.33 The JavaScript Domain
..............................

The JavaScript domain (name `js') provides the following directives:

 -- reStructuredText 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 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 ‘noindex’
     option is specified.  If this option is specified, the directive
     will only update the current module name.

     New in version 1.6.

 -- reStructuredText Directive: .. js:function:: name(signature)

     Describes a JavaScript function or method.  If you want to describe
     arguments as optional use square brackets as documented.
     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:

           -- JavaScript Function: $.getJSON (href, callback[, errback])

               Arguments:

                  * ‘href’ (‘string()’) – An URI to the location of the
                    resource.

                  * ‘callback’ – Gets called with the object.

                  * ‘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.

 -- reStructuredText Directive: .. js:method:: name(signature)

     This directive is an alias for js;function, however it
     describes a function that is implemented as a method on a class
     object.

     New in version 1.6.

 -- reStructuredText 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:

           -- JavaScript Class: MyAnimal (name[, age])

               Arguments:

                  * ‘name’ (‘string()’) – The name of the animal

                  * ‘age’ (‘number()’) – an optional age for the animal

 -- reStructuredText Directive: .. js:data:: name

     Describes a global variable or constant.

 -- reStructuredText Directive: .. js:attribute:: object.name

     Describes the attribute `name' of `object'.
These roles are provided to refer to the described objects:

 -- reStructuredText Role: :js:mod:
 -- reStructuredText Role: :js:func:
 -- reStructuredText Role: :js:meth:
 -- reStructuredText Role: :js:class:
 -- reStructuredText Role: :js:data:
 -- reStructuredText Role: :js:attr:

1.3.5.34 The reStructuredText domain
....................................

The reStructuredText domain (name `rst') provides the following
directives:

 -- reStructuredText 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:

           -- reStructuredText Directive: .. foo::

               Foo description.

           -- reStructuredText Directive: .. bar:: baz

               Bar description.

 -- reStructuredText 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:

           -- reStructuredText Directive: .. toctree::

                -- reStructuredText directive-option: :caption: caption
                         of ToC

                -- reStructuredText directive-option: :glob:

     options
     .......

      -- reStructuredText directive-option: :type: description of
               argument (text)

          Describe the type of option value.

          For example:

               .. rst:directive:: toctree

                  .. rst:directive:option:: maxdepth
                     :type: integer or no value

          New in version 2.1.

 -- reStructuredText Directive: .. rst:role:: name

     Describes a reST role.  For example:

          .. rst:role:: foo

             Foo description.

     will be rendered as:

           -- reStructuredText Role: :foo:

               Foo description.
These roles are provided to refer to the described objects:

 -- reStructuredText Role: :rst:dir:
 -- reStructuredText Role: :rst:role:

1.3.5.35 The Math Domain
........................

The math domain (name `math') provides the following roles:

 -- reStructuredText Role: :math:numref:

     Role for cross-referencing equations defined by 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.

     New in version 1.8.

1.3.5.36 More domains
.....................

The sphinx-contrib(1) repository contains more domains available as
extensions; currently Ada(2), CoffeeScript(3), Erlang(4), HTTP(5),
Lasso(6), MATLAB(7), PHP(8), and Ruby(9) domains.  Also available are
domains for Chapel(10), Common Lisp(11), dqn(12), Go(13), Jinja(14),
Operation(15), and Scala(16).

   ---------- Footnotes ----------

   (1) https://github.com/sphinx-contrib

   (2) https://pypi.org/project/sphinxcontrib-adadomain/

   (3) https://pypi.org/project/sphinxcontrib-coffee/

   (4) https://pypi.org/project/sphinxcontrib-erlangdomain/

   (5) https://pypi.org/project/sphinxcontrib-httpdomain/

   (6) https://pypi.org/project/sphinxcontrib-lassodomain/

   (7) https://pypi.org/project/sphinxcontrib-matlabdomain/

   (8) https://pypi.org/project/sphinxcontrib-phpdomain/

   (9)
https://bitbucket.org/birkenfeld/sphinx-contrib/src/default/rubydomain

   (10) https://pypi.org/project/sphinxcontrib-chapeldomain/

   (11) https://pypi.org/project/sphinxcontrib-cldomain/

   (12) https://pypi.org/project/sphinxcontrib-dqndomain/

   (13) https://pypi.org/project/sphinxcontrib-golangdomain/

   (14) https://pypi.org/project/sphinxcontrib-jinjadomain/

   (15) https://pypi.org/project/sphinxcontrib-operationdomain/

   (16) https://pypi.org/project/sphinxcontrib-scaladomain/

1.4 Markdown
============

Markdown(1) 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(2).  MyST-Parser is a Docutils bridge to markdown-it-py(3),
a Python package for parsing the CommonMark(4) Markdown flavor.

   ---------- Footnotes ----------

   (1) https://daringfireball.net/projects/markdown/

   (2) https://myst-parser.readthedocs.io/en/latest/

   (3) https://github.com/executablebooks/markdown-it-py

   (4) https://commonmark.org/

1.4.1 Configuration
-------------------

To configure your Sphinx project for Markdown support, proceed as
follows:

  1. Install the Markdown parser `MyST-Parser':

          pip install --upgrade myst-parser

  2. Add `myst_parser' to the list of configured extensions.:

          extensions = ['myst_parser']

          Note: MyST-Parser requires Sphinx 2.1 or newer.

  3. If you want to use Markdown files with extensions other than ‘.md’,
     adjust the 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',
          }

  4. You can further configure `MyST-Parser' to allow custom syntax that
     standard `CommonMark' doesn’t support.  Read more in the
     MyST-Parser documentation(1).

   ---------- Footnotes ----------

   (1)
https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html

1.5 Configuration
=================

The configuration directory must contain a file named
‘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(1) can be added to the configuration
     directory to adjust Docutils(2) configuration if not otherwise
     overridden or set by Sphinx.

The configuration file is executed as Python code at build time (using
importlib.import_module()(3), 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 ‘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.
   * There is a special object named ‘tags’ available in the config
     file.  It can be used to query and change the tags (see
     Including content based on 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.

   ---------- Footnotes ----------

   (1) https://docutils.sourceforge.io/docs/user/config.html

   (2) https://docutils.sourceforge.io/

   (3)
https://docs.python.org/3/library/importlib.html#importlib.import_module

1.5.1 Project information
-------------------------

 -- Configuration Value: project

     The documented project’s name.

 -- Configuration Value: author

     The author name(s) of the document.  The default value is
     ‘'unknown'’.

 -- Configuration Value: copyright

     A copyright statement in the style ‘'2008, Author Name'’.

 -- Configuration Value: project_copyright

     An alias of copyright.

     New in version 3.5.

 -- Configuration Value: version

     The major project version, used as the replacement for ‘|version|’.
     For example, for the Python documentation, this may be something
     like ‘2.6’.

 -- Configuration Value: 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 version
     and release, just set them both to the same value.

1.5.2 General configuration
---------------------------

 -- Configuration Value: extensions

     A list of strings that are module names of extensions.
     These can be extensions coming with Sphinx (named ‘sphinx.ext.*’)
     or custom ones.

     Note that you can extend sys.path(1) 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
     configuration directory, use os.path.abspath()(2) 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 ‘setup()’ function in it.

 -- Configuration Value: 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’).

     Changed in version 1.3: Can now be a list of extensions.

     Changed in version 1.8: Support file type mapping

 -- Configuration Value: source_encoding

     The encoding of all reST source files.  The recommended encoding,
     and the default value, is ‘'utf-8-sig'’.

     New in version 0.5: Previously, Sphinx accepted only UTF-8 encoded
     sources.

 -- Configuration Value: 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
     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 Markdown for more information on
          using Markdown with Sphinx.

     New in version 1.3.

     Deprecated since version 1.8: Now Sphinx provides an API
     Sphinx.add_source_parser() to register a source parser.
     Please use it instead.

 -- Configuration Value: master_doc

     Same as root_doc.

     Changed in version 4.0: Renamed ‘master_doc’ to ‘root_doc’.

 -- Configuration Value: root_doc

     The document name of the “root” document, that is, the document
     that contains the root toctree directive.  Default is
     ‘'index'’.

     Changed in version 2.0: The default is changed to ‘'index'’ from
     ‘'contents'’.

     Changed in version 4.0: Renamed ‘root_doc’ from ‘master_doc’.

 -- Configuration Value: exclude_patterns

     A list of glob-style patterns that should be excluded when looking
     for source files.  (3) 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
          (replaces entry in ‘unused_docs’)

        - ‘'library/xml'’ – ignores the ‘library/xml’ directory

        - ‘'library/xml*'’ – ignores all files and directories starting
          with ‘library/xml’

        - ‘'**/.svn'’ – ignores all ‘.svn’ directories

     exclude_patterns is also consulted when looking for
     static files in html_static_path and
     html_extra_path.

     New in version 1.0.

 -- Configuration Value: 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.

     Changed in version 1.3: As these files are not meant to be built,
     they are automatically added to exclude_patterns.

 -- Configuration Value: template_bridge

     A string with the fully-qualified name of a callable (or simply a
     class) that returns an instance of 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.)

 -- Configuration Value: rst_epilog

     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
     rst_prolog).  An example:

          rst_epilog = """
          .. |psf| replace:: Python Software Foundation
          """

     New in version 0.6.

 -- Configuration Value: rst_prolog

     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
     rst_epilog).  An example:

          rst_prolog = """
          .. |psf| replace:: Python Software Foundation
          """

     New in version 1.0.

 -- Configuration Value: primary_domain

     The name of the default domain.  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 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”).

     New in version 1.0.

 -- Configuration Value: 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 ‘default-role’ directive.

     New in version 0.4.

 -- Configuration Value: 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.

     New in version 0.5.

 -- Configuration Value: 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’

        * ‘download.not_readable’

        * ‘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’

        * ‘epub.unknown_project_files’

        * ‘epub.duplicated_toc_entry’

        * ‘autosectionlabel.*’

     You can choose from these types.

     Now, this option should be considered `experimental'.

     New in version 1.4.

     Changed in version 1.5: Added ‘misc.highlighting_failure’

     Changed in version 1.5.1: Added ‘epub.unknown_project_files’

     Changed in version 1.6: Added ‘ref.footnote’

     Changed in version 2.1: Added ‘autosectionlabel.*’

     Changed in version 3.3.0: Added ‘epub.duplicated_toc_entry’

     Changed in version 4.3: Added ‘toc.excluded’ and ‘toc.not_readable’

 -- Configuration Value: 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.

     New in version 1.0.

     Changed in version 1.4: also accepts micro version string

 -- Configuration Value: needs_extensions

     This value can be a dictionary specifying version requirements for
     extensions in 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 Developing extensions for Sphinx for how to do
     that).

     New in version 1.3.

 -- Configuration Value: manpages_url

     A URL to cross-reference manpage directives.  If this is
     defined to ‘https://manpages.debian.org/{path}’, the
     ‘: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.

     New in version 1.7.

 -- Configuration Value: 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 -n command-line switch.

     New in version 1.0.

 -- Configuration Value: nitpick_ignore

     A 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')’.

     New in version 1.1.

 -- Configuration Value: nitpick_ignore_regex

     An extended version of 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')’.

     New in version 4.1.

 -- Configuration Value: numfig

     If true, figures, tables and code-blocks are automatically numbered
     if they have a caption.  The 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.

     New in version 1.3.

 -- Configuration Value: 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'’.

     New in version 1.3.

 -- Configuration Value: 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 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…

     New in version 1.3.

     Changed in version 1.7: The LaTeX builder obeys this setting (if
     numfig is set to ‘True’).

 -- Configuration Value: smartquotes

     If true, the Docutils Smart Quotes transform(4), originally based
     on SmartyPants(5) (limited to English) and currently applying to
     many languages, will be used to convert quotes and dashes to
     typographically correct entities.  Default: ‘True’.

     New in version 1.6.6: It replaces deprecated
     html_use_smartypants.  It applies by default to all builders
     except ‘man’ and ‘text’ (see smartquotes_excludes)

     A docutils.conf(6) file located in the configuration directory (or
     a global ‘~/.docutils’ file) is obeyed unconditionally if it
     `deactivates' smart quotes via the corresponding Docutils
     option(7).  But if it `activates' them, then smartquotes
     does prevail.

 -- Configuration Value: smartquotes_action

     This string customizes the Smart Quotes transform.  See the file
     ‘smartquotes.py’ at the Docutils repository(8) for details.  The
     default ‘'qDe'’ educates normal `q'uote characters ‘"’, ‘'’, em-
     and en-`D'ashes ‘---’, ‘--’, and `e'llipses ‘...’.

     New in version 1.6.6.

 -- Configuration Value: smartquotes_excludes

     This is a ‘dict’ whose default is:

          {'languages': ['ja'], 'builders': ['man', 'text']}

     Each entry gives a sufficient condition to ignore the
     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 ‘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 ‘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:

               make latex O="-D smartquotes_action="

          This can follow some ‘make html’ with no problem, in contrast
          to the situation from the prior note.  It requires Docutils
          0.14 or later.

     New in version 1.6.6.

 -- Configuration Value: 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"’.

     New in version 2.3.

 -- Configuration Value: tls_verify

     If true, Sphinx verifies server certifications.  Default is ‘True’.

     New in version 1.5.

 -- Configuration Value: 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.

     New in version 1.5.

          Tip: Sphinx uses requests(9) 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.

 -- Configuration Value: today
 -- Configuration Value: today_fmt

     These values determine how to format the current date, used as the
     replacement for ‘|today|’.

        * If you set today to a non-empty value, it is used.

        * Otherwise, the current time is formatted using
          time.strftime()(10) and the format given in today_fmt.

     The default is now today and a today_fmt of
     ‘'%b %d, %Y'’ (or, if translation is enabled with language,
     an equivalent format for the selected locale).

 -- Configuration Value: 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 Showing code examples
     for more details.

     New in version 0.5.

     Changed in version 1.4: The default is now ‘'default'’.  If you
     prefer Python 2 only highlighting, you can set it back to
     ‘'python'’.

 -- Configuration Value: 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(11).

     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
     highlight_language.:

          # configuration for the ``highlight_language``
          highlight_options = {'stripall': True}

     New in version 1.3.

     Changed in version 3.5: Allow to configure highlight options for
     multiple languages

 -- Configuration Value: 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.

     Changed in version 0.3: If the value is a fully-qualified name of a
     custom Pygments style class, this is then used as custom style.

 -- Configuration Value: 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’.

 -- Configuration Value: add_module_names

     A boolean that decides whether module names are prepended to all
     object names (for object types where a “module” of some
     kind is defined), e.g.  for py;function directives.
     Default is ‘True’.

 -- Configuration Value: show_authors

     A boolean that decides whether codeauthor and
     sectionauthor directives produce any output in the built
     files.

 -- Configuration Value: 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 ‘[]’.

     New in version 0.6.

 -- Configuration Value: 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.

     New in version 0.6.

 -- Configuration Value: 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 doctest
     for more possibilities of including doctests.

     New in version 1.0.

     Changed in version 1.1: Now also removes ‘<BLANKLINE>’.

 -- Configuration Value: 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.

          New in version 3.0.

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/library/sys.html#sys.path

   (2) https://docs.python.org/3/library/os.path.html#os.path.abspath

   (3) 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.

   (4) https://docutils.sourceforge.io/docs/user/smartquotes.html

   (5) https://daringfireball.net/projects/smartypants/

   (6) https://docutils.sourceforge.io/docs/user/config.html

   (7)
https://docutils.sourceforge.io/docs/user/config.html#smart-quotes

   (8) https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/

   (9) https://requests.readthedocs.io/en/master/

   (10) https://docs.python.org/3/library/time.html#time.strftime

   (11) https://pygments.org/docs/lexers

1.5.3 Options for internationalization
--------------------------------------

These options influence Sphinx’s `Native Language Support'.  See the
documentation on Internationalization for details.

 -- Configuration Value: 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
     locale_dirs.  Sphinx will search language-specific figures
     named by 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 ‘None’, which means that no
     translation will be done.

     New in version 0.5.

     Changed in version 1.4: Support figure substitution

     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

        * ‘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

 -- Configuration Value: locale_dirs

     New in version 0.5.

     Directories in which to search for additional message catalogs (see
     language), relative to the source directory.  The
     directories on this path are searched by the standard gettext(1)
     module.

     Internal messages are fetched from a text domain of ‘sphinx’; so if
     you add the directory ‘./locale’ to this setting, the message
     catalogs (compiled from ‘.po’ format using ‘msgfmt’) must be in
     ‘./locale/`language'/LC_MESSAGES/sphinx.mo’.  The text domain of
     individual documents depends on gettext_compact.

     The default is ‘['locales']’.

          Note: The -v option for sphinx-build command is
          useful to check the locale_dirs config works as expected.  It
          emits debug messages if message catalog directory not found.

     Changed in version 1.5: Use ‘locales’ directory as a default value

 -- Configuration Value: gettext_allow_fuzzy_translations

     If true, “fuzzy” messages in the message catalogs are used for
     translation.  The default is ‘False’.

     New in version 4.3.

 -- Configuration Value: gettext_compact

     New in version 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’.

     Changed in version 3.3: The string value is now accepted.

 -- Configuration Value: 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 ‘pip
     install python-levenshtein’.

     The default is ‘False’.

     New in version 1.3.

 -- Configuration Value: gettext_location

     If true, Sphinx generates location information for messages in
     message catalogs.

     The default is ‘True’.

     New in version 1.3.

 -- Configuration Value: gettext_auto_build

     If true, Sphinx builds mo file for each translation catalog files.

     The default is ‘True’.

     New in version 1.3.

 -- Configuration Value: 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 ‘[]’.

     New in version 1.3.

     Changed in version 4.0: The alt text for image is translated by
     default.

 -- Configuration Value: 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.

     New in version 1.4.

     Changed in version 1.5: Added ‘{path}’ and ‘{basename}’ tokens.

     Changed in version 3.2: Added ‘{docpath}’ token.

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/library/gettext.html#module-gettext

1.5.4 Options for Math
----------------------

These options influence Math notations.

 -- Configuration Value: math_number_all

     Set this option to ‘True’ if you want all displayed math to be
     numbered.  The default is ‘False’.

 -- Configuration Value: 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’.

 -- Configuration Value: math_numfig

     If ‘True’, displayed math equations are numbered across pages when
     numfig is enabled.  The numfig_secnum_depth.
     setting is respected.  The eq, not numref, role
     must be used to reference equation numbers.  Default is ‘True’.

     New in version 1.7.

1.5.5 Options for HTML output
-----------------------------

These options influence HTML as well as HTML Help output, and other
builders that use Sphinx’s HTMLWriter class.

 -- Configuration Value: html_theme

     The “theme” that the HTML output should use.  See the section about theming.
     The default is ‘'alabaster'’.

     New in version 0.6.

 -- Configuration Value: 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 this section.

     New in version 0.6.

 -- Configuration Value: 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.

     New in version 0.6.

 -- Configuration Value: html_style

     The style sheet to use for HTML pages.  A file of that name must
     exist either in Sphinx’s ‘static/’ path, or in one of the custom
     paths given in 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.

 -- Configuration Value: 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 ‘'<PROJECT> v<REVISION> documentation'’.

 -- Configuration Value: 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 html_title.

     New in version 0.4.

 -- Configuration Value: 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(1).  Default: ‘''’.

     New in version 1.8.

 -- Configuration Value: 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)

     New in version 3.2.

     Changed in version 4.0: It defaults to ‘'inline'’.

     Deprecated since version 4.0.

 -- Configuration Value: 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 -A command-line option of ‘sphinx-build’.

     New in version 0.5.

 -- Configuration Value: html_logo

     If given, this must be the name of an image file (path relative to
     the 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’.

     New in version 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.

     Changed in version 4.0: Also accepts the URL for the logo file.

 -- Configuration Value: html_favicon

     If given, this must be the name of an image file (path relative to
     the 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’.

     New in version 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.

     Changed in version 4.0: Also accepts the URL for the favicon.

 -- Configuration Value: 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
     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
     ‘Sphinx.add_css_files()’.

     New in version 1.8.

     Changed in version 3.5: Support priority attribute

 -- Configuration Value: 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
     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
     ‘Sphinx.add_css_files()’.

     New in version 1.8.

     Changed in version 3.5: Support priority attribute

 -- Configuration Value: 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
     ‘_static’ directory after the theme’s static files, so a file named
     ‘default.css’ will overwrite the theme’s ‘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
          html_extra_path.  It allows to copy dotfiles under the
          directories.

     Changed in version 0.4: The paths in html_static_path.
     can now contain subdirectories.

     Changed in version 1.0: The entries in html_static_path.
     can now be single files.

     Changed in version 1.8: The files under html_static_path
     are excluded from source files.

 -- Configuration Value: html_extra_path

     A list of paths that contain extra files not directly related to
     the documentation, such as ‘robots.txt’ or ‘.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.

     New in version 1.2.

     Changed in version 1.4: The dotfiles in the extra directory will be
     copied to the output directory.  And it refers
     exclude_patterns on copying extra files and directories, and
     ignores if path matches to patterns.

 -- Configuration Value: html_last_updated_fmt

     If this is 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'’ (or a locale-dependent
     equivalent).

 -- Configuration Value: html_use_smartypants

     If true, quotes and dashes are converted to typographically correct
     entities.  Default: ‘True’.

     Deprecated since version 1.6: To disable smart quotes, use rather
     smartquotes.

 -- Configuration Value: html_add_permalinks

     Sphinx will add “permalinks” for each heading and description
     environment as paragraph signs that become visible when the mouse
     hovers over them.

     This value determines the text for the permalink; it defaults to
     ‘"¶"’.  Set it to ‘None’ or the empty string to disable permalinks.

     New in version 0.6: Previously, this was always activated.

     Changed in version 1.1: This can now be a string to select the
     actual text of the link.  Previously, only boolean values were
     accepted.

     Deprecated since version 3.5: This has been replaced by
     html_permalinks.

 -- Configuration Value: html_permalinks

     If true, Sphinx will add “permalinks” for each heading and
     description environment.  Default: ‘True’.

     New in version 3.5.

 -- Configuration Value: html_permalinks_icon

     A text for permalinks for each heading and description environment.
     HTML tags are allowed.  Default: a paragraph sign; ‘¶’

     New in version 3.5.

 -- Configuration Value: html_sidebars

     Custom sidebar templates, must be a dictionary that maps document
     names to template names.

     The keys can contain glob-style patterns (2), 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 since version 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 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).

     New in version 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.

 -- Configuration Value: 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’.

 -- Configuration Value: 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'’.

     New in version 1.0.

 -- Configuration Value: html_use_index

     If true, add an index to the HTML documents.  Default is ‘True’.

     New in version 0.4.

 -- Configuration Value: 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’.

     New in version 0.4.

 -- Configuration Value: html_copy_source

     If true, the reST sources are included in the HTML build as
     ‘_sources/`name'’.  The default is ‘True’.

 -- Configuration Value: html_show_sourcelink

     If true (and html_copy_source is true as well), links
     to the reST sources will be added to the sidebar.  The default is
     ‘True’.

     New in version 0.6.

 -- Configuration Value: html_sourcelink_suffix

     Suffix to be appended to source links (see
     html_show_sourcelink), unless they have this suffix already.
     Default is ‘'.txt'’.

     New in version 1.5.

 -- Configuration Value: html_use_opensearch

     If nonempty, an OpenSearch(3) 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 ‘''’.

 -- Configuration Value: html_file_suffix

     This is the file name suffix for generated HTML files.  The default
     is ‘".html"’.

     New in version 0.4.

 -- Configuration Value: html_link_suffix

     Suffix for generated links to HTML files.  The default is whatever
     html_file_suffix is set to; it can be set differently
     (e.g.  to support different web server setups).

     New in version 0.6.

 -- Configuration Value: html_show_copyright

     If true, “(C) Copyright …” is shown in the HTML footer.  Default is
     ‘True’.

     New in version 1.0.

 -- Configuration Value: html_show_sphinx

     If true, “Created using Sphinx” is shown in the HTML footer.
     Default is ‘True’.

     New in version 0.4.

 -- Configuration Value: 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.

     New in version 1.0.

 -- Configuration Value: 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’.

     New in version 1.0.

 -- Configuration Value: html_secnumber_suffix

     Suffix for section numbers.  Default: ‘". "’.  Set to ‘" "’ to
     suppress the final dot on section numbers.

     New in version 1.0.

 -- Configuration Value: html_search_language

     Language to be used for generating the HTML full-text search index.
     This defaults to the global language selected with 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

          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(4) (‘en’)

             * PyStemmer(5) (all languages)

     New in version 1.1: With support for ‘en’ and ‘ja’.

     Changed in version 1.3: Added additional languages.

 -- Configuration Value: 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
     ‘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(6) is required.

     Deprecated since version 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’.

     New in version 1.1.

     Changed in version 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.

 -- Configuration Value: 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.

     New in version 1.2.

 -- Configuration Value: html_scaled_image_link

     If true, images 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 this feature manually with giving
     ‘no-scaled-link’ class to the image:

          .. image:: sphinx.png
             :scale: 50%
             :class: no-scaled-link

     New in version 1.3.

     Changed in version 3.0: It is disabled for images having
     ‘no-scaled-link’ class

 -- Configuration Value: html_math_renderer

     The name of math_renderer extension for HTML output.  The default
     is ‘'mathjax'’.

     New in version 1.8.

 -- Configuration Value: html_experimental_html5_writer

     Output is processed with HTML5 writer.  Default is ‘False’.

     New in version 1.6.

     Deprecated since version 2.0.

 -- Configuration Value: html4_writer

     Output is processed with HTML4 writer.  Default is ‘False’.

   ---------- Footnotes ----------

   (1) https://datatracker.ietf.org/doc/html/rfc6596

   (2) 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.

   (3) https://github.com/dewitt/opensearch

   (4) https://pypi.org/project/PorterStemmer/

   (5) https://pypi.org/project/PyStemmer/

   (6) https://pypi.org/project/Janome/

1.5.6 Options for Single HTML output
------------------------------------

 -- Configuration Value: 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
     html_sidebars.  By default, it is same as html_sidebars.

1.5.7 Options for HTML help output
----------------------------------

 -- Configuration Value: htmlhelp_basename

     Output file base name for HTML help builder.  Default is ‘'pydoc'’.

 -- Configuration Value: htmlhelp_file_suffix

     This is the file name suffix for generated HTML help files.  The
     default is ‘".html"’.

     New in version 2.0.

 -- Configuration Value: htmlhelp_link_suffix

     Suffix for generated links to HTML files.  The default is
     ‘".html"’.

     New in version 2.0.

1.5.8 Options for Apple Help output
-----------------------------------

New in version 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 ‘hiutil’ and ‘codesign’ command line tools,
     neither of which are Open Source.

     You can disable the use of these tools using
     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.

 -- Configuration Value: applehelp_bundle_name

     The basename for the Apple Help Book.  Defaults to the
     project name.

 -- Configuration Value: applehelp_bundle_id

     The bundle ID for the help book bundle.

          Warning: You `must' set this value in order to generate Apple
          Help.

 -- Configuration Value: applehelp_dev_region

     The development region.  Defaults to ‘'en-us'’, which is Apple’s
     recommended setting.

 -- Configuration Value: applehelp_bundle_version

     The bundle version (as a string).  Defaults to ‘'1'’.

 -- Configuration Value: 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.

 -- Configuration Value: applehelp_kb_product

     The product tag for use with applehelp_kb_url.  Defaults
     to ‘'<PROJECT>-<RELEASE>'’.

 -- Configuration Value: 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
     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.

 -- Configuration Value: 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.

 -- Configuration Value: 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.

 -- Configuration Value: applehelp_min_term_length

     Controls the minimum term length for the help indexer.  Defaults to
     ‘None’, which means the default will be used.

 -- Configuration Value: 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 language, or if that is not set, to ‘en’.

 -- Configuration Value: 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 language, or if that is not set, to ‘en’.

 -- Configuration Value: applehelp_title

     Specifies the help book title.  Defaults to ‘'<PROJECT> Help'’.

 -- Configuration Value: 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.

 -- Configuration Value: applehelp_codesign_flags

     A `list' of additional arguments to pass to ‘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.

 -- Configuration Value: applehelp_indexer_path

     The path to the ‘hiutil’ program.  Defaults to ‘'/usr/bin/hiutil'’.

 -- Configuration Value: applehelp_codesign_path

     The path to the ‘codesign’ program.  Defaults to
     ‘'/usr/bin/codesign'’.

 -- Configuration Value: 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’.

1.5.9 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(1).

 -- Configuration Value: epub_basename

     The basename for the epub file.  It defaults to the project
     name.

 -- Configuration Value: 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.

 -- Configuration Value: 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 this section.

     New in version 1.2.

 -- Configuration Value: epub_title

     The title of the document.  It defaults to the html_title
     option but can be set independently for epub creation.  It
     defaults to the project option.

     Changed in version 2.0: It defaults to the ‘project’ option.

 -- Configuration Value: epub_description

     The description of the document.  The default value is ‘'unknown'’.

     New in version 1.4.

     Changed in version 1.5: Renamed from ‘epub3_description’

 -- Configuration Value: epub_author

     The author of the document.  This is put in the Dublin Core
     metadata.  It defaults to the author option.

 -- Configuration Value: 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'’.

     New in version 1.4.

     Changed in version 1.5: Renamed from ‘epub3_contributor’

 -- Configuration Value: epub_language

     The language of the document.  This is put in the Dublin Core
     metadata.  The default is the language option or ‘'en'’
     if unset.

 -- Configuration Value: 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 author option.

 -- Configuration Value: epub_copyright

     The copyright of the document.  It defaults to the copyright
     option but can be set independently for epub creation.

 -- Configuration Value: 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'’.

 -- Configuration Value: epub_scheme

     The publication scheme for the 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'’.

 -- Configuration Value: epub_uid

     A unique identifier for the document.  This is put in the Dublin
     Core metadata.  You may use a XML’s Name format(2) string.  You
     can’t use hyphen, period, numbers as a first character.  The
     default value is ‘'unknown'’.

 -- Configuration Value: 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
     ‘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 ‘()’.

     New in version 1.1.

 -- Configuration Value: 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 html_css_files.

     New in version 1.8.

 -- Configuration Value: epub_guide

     Meta data for the guide element of ‘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', u'Cover Page'),)

     The default value is ‘()’.

 -- Configuration Value: 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 ‘toc.ncx’.
     Example:

          epub_pre_files = [
              ('index.html', 'Welcome'),
          ]

     The default value is ‘[]’.

 -- Configuration Value: 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 ‘toc.ncx’.  The default value is
     ‘[]’.

 -- Configuration Value: 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
     ‘[]’.

 -- Configuration Value: epub_tocdepth

     The depth of the table of contents in the 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.

 -- Configuration Value: 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’.

 -- Configuration Value: 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

     New in version 1.2.

 -- Configuration Value: 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.

     New in version 1.2.

 -- Configuration Value: 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.

     New in version 1.2.

 -- Configuration Value: 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’.

     New in version 1.2.

 -- Configuration Value: epub_use_index

     If true, add an index to the epub document.  It defaults to the
     html_use_index option but can be set independently for
     epub creation.

     New in version 1.2.

 -- Configuration Value: epub_writing_mode

     It specifies writing direction.  It can accept ‘'horizontal'’
     (default) and ‘'vertical'’

     ‘epub_writing_mode’                   ‘'horizontal'’                        ‘'vertical'’

     ------------------------------------------------------------------------------------------------------------------

     writing-mode (3)                      ‘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.

   ---------- Footnotes ----------

   (1) https://dublincore.org/

   (2) https://www.w3.org/TR/REC-xml/#NT-NameStartChar

   (3) ‘https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode’

1.5.10 Options for LaTeX output
-------------------------------

These options influence LaTeX output.

 -- Configuration Value: 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 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
          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.

     Changed in version 2.1.0: Use ‘xelatex’ (and LaTeX package ‘xeCJK’)
     by default for Chinese documents.

     Changed in version 2.2.1: Use ‘xelatex’ by default for Greek
     documents.

     Changed in version 2.3: Add ‘uplatex’ support.

     Changed in version 4.0: ‘uplatex’ becomes the default setting of
     Japanese documents.

     Contrarily to MathJaX math rendering in HTML output,
     LaTeX requires some extra configuration to support Unicode literals
     in 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 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 \alpha.

 -- Configuration Value: 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 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 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 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.

     New in version 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.

     New in version 0.3: The 6th item ‘toctree_only’.  Tuples with 5
     items are still accepted.

 -- Configuration Value: 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’.

 -- Configuration Value: 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’.)

     New in version 1.4.

 -- Configuration Value: latex_appendices

     A list of document names to append as an appendix to all manuals.

 -- Configuration Value: 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 html_domain_indices.

     New in version 1.0.

 -- Configuration Value: latex_show_pagerefs

     If true, add page references after internal references.  This is
     very useful for printed copies of the manual.  Default is ‘False’.

     New in version 1.0.

 -- Configuration Value: 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

     New in version 1.0.

     Changed in version 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.

 -- Configuration Value: 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 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’.

     New in version 1.6.

 -- Configuration Value: latex_use_xindy

     If ‘True’, the PDF build from the LaTeX files created by Sphinx
     will use ‘xindy’ (doc(1)) rather than ‘makeindex’ for preparing the
     index of general terms (from index usage).  This means
     that words with UTF-8 characters will get ordered correctly for the
     language.

        - This option is ignored if latex_engine is
          ‘'platex'’ (Japanese documents; ‘mendex’ replaces ‘makeindex’
          then).

        - The default is ‘True’ for ‘'xelatex'’ or ‘'lualatex'’ as
          ‘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 ‘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.

     New in version 1.8.

 -- Configuration Value: latex_elements

     New in version 0.5.

     Its documentation has moved to LaTeX customization.

 -- Configuration Value: 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'’.

     New in version 1.0.

     Changed in version 1.5: In Japanese docs (see language is
     ‘'ja'’), by default ‘'jreport'’ is used for ‘'howto'’ and
     ‘'jsbook'’ for ‘'manual'’.

 -- Configuration Value: 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.

     New in version 0.6.

     Changed in version 1.2: This overrides the files which is provided
     from Sphinx such as ‘sphinx.sty’.

 -- Configuration Value: 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).  latex_appendices is available only for
          this theme.

     It defaults to ‘'manual'’.

     New in version 3.0.

 -- Configuration Value: latex_theme_options

     A dictionary of options that influence the look and feel of the
     selected theme.

     New in version 3.1.

 -- Configuration Value: latex_theme_path

     A list of paths that contain custom LaTeX themes as subdirectories.
     Relative paths are taken as relative to the configuration
     directory.

     New in version 3.0.

   ---------- Footnotes ----------

   (1) http://xindy.sourceforge.net/

1.5.11 Options for text output
------------------------------

These options influence text output.

 -- Configuration Value: 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'’.

     New in version 1.1.

 -- Configuration Value: 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 ‘'*=-~"+`'’.

     New in version 1.1.

 -- Configuration Value: text_add_secnumbers

     A boolean that decides whether section numbers are included in text
     output.  Default is ‘True’.

     New in version 1.7.

 -- Configuration Value: text_secnumber_suffix

     Suffix for section numbers in text output.  Default: ‘". "’.  Set
     to ‘" "’ to suppress the final dot on section numbers.

     New in version 1.7.

1.5.12 Options for manual page output
-------------------------------------

These options influence manual page output.

 -- Configuration Value: 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 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 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.

     New in version 1.0.

 -- Configuration Value: man_show_urls

     If true, add URL addresses after links.  Default is ‘False’.

     New in version 1.1.

 -- Configuration Value: man_make_section_directory

     If true, make a section directory on build man page.  Default is
     True.

     New in version 3.3.

     Changed in version 4.0: The default is changed to ‘False’ from
     ‘True’.

     Changed in version 4.0.2: The default is changed to ‘True’ from
     ‘False’ again.

1.5.13 Options for Texinfo output
---------------------------------

These options influence Texinfo output.

 -- Configuration Value: 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 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 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.

     New in version 1.1.

 -- Configuration Value: texinfo_appendices

     A list of document names to append as an appendix to all manuals.

     New in version 1.1.

 -- Configuration Value: 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 html_domain_indices.

     New in version 1.1.

 -- Configuration Value: 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

     New in version 1.1.

 -- Configuration Value: 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’.

     New in version 1.2.

 -- Configuration Value: 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'’

     New in version 1.1.

 -- Configuration Value: 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’.

     New in version 4.4.

1.5.14 Options for QtHelp output
--------------------------------

These options influence qthelp output.  As this builder derives from the
HTML builder, the HTML options also apply where appropriate.

 -- Configuration Value: qthelp_basename

     The basename for the qthelp file.  It defaults to the
     project name.

 -- Configuration Value: qthelp_namespace

     The namespace for the qthelp file.  It defaults to
     ‘org.sphinx.<project_name>.<project_version>’.

 -- Configuration Value: qthelp_theme

     The HTML theme for the qthelp output.  This defaults to ‘'nonav'’.

 -- Configuration Value: 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 this section.

1.5.15 Options for the linkcheck builder
----------------------------------------

 -- Configuration Value: 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+/']

     New in version 1.1.

 -- Configuration Value: 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:

          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 the warn-is-error mode.

     New in version 4.1.

 -- Configuration Value: 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:

          linkcheck_request_headers = {
              "https://www.sphinx-doc.org/": {
                  "Accept": "text/html",
                  "Accept-Encoding": "utf-8",
              },
              "*": {
                  "Accept": "text/html,application/xhtml+xml",
              }
          }

     New in version 3.1.

 -- Configuration Value: linkcheck_retries

     The number of times the linkcheck builder will attempt to check a
     URL before declaring it broken.  Defaults to 1 attempt.

     New in version 1.4.

 -- Configuration Value: linkcheck_timeout

     A timeout value, in seconds, for the linkcheck builder.  The
     default is to use Python’s global socket timeout.

     New in version 1.1.

 -- Configuration Value: linkcheck_workers

     The number of worker threads to use when checking links.  Default
     is 5 threads.

     New in version 1.1.

 -- Configuration Value: 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’.

     New in version 1.2.

 -- Configuration Value: 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 ‘["^!"]’.

          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
          linkcheck_ignore instead, for example as follows:

               linkcheck_ignore = [
                  'https://www.sphinx-doc.org/en/1.7/intro.html#'
               ]

     New in version 1.5.

 -- Configuration Value: 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
          requests Authentication(1) for details).

     The ‘linkcheck’ builder will use the first matching ‘auth_info’
     value it can find in the 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(...)),
          ]

     New in version 2.3.

 -- Configuration Value: 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(2)
     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.

     New in version 3.4.

 -- Configuration Value: 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/.*']

     New in version 4.4.

   ---------- Footnotes ----------

   (1)
https://docs.python-requests.org/en/master/user/authentication/#authentication

   (2) https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.3

1.5.16 Options for the XML builder
----------------------------------

 -- Configuration Value: xml_pretty

     If true, pretty-print the XML. Default is ‘True’.

     New in version 1.2.

1.5.17 Options for the C domain
-------------------------------

 -- Configuration Value: 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.

     New in version 3.0.

 -- Configuration Value: 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.

     New in version 3.0.

 -- Configuration Value: 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']’.

     New in version 4.0.3.

 -- Configuration Value: c_allow_pre_v3

     A boolean (default ‘False’) controlling whether to parse and try to
     convert pre-v3 style type directives and type roles.

     New in version 3.2.

     Deprecated since version 3.2: Use the directives and roles added in
     v3.

 -- Configuration Value: c_warn_on_allowed_pre_v3

     A boolean (default ‘True’) controlling whether to warn when a
     pre-v3 style type directive/role is parsed and converted.

     New in version 3.2.

     Deprecated since version 3.2: Use the directives and roles added in
     v3.

1.5.18 Options for the C++ domain
---------------------------------

 -- Configuration Value: cpp_index_common_prefix

     A list of prefixes that will be ignored when sorting C++ objects in
     the global index.  For example ‘['awesome_lib::']’.

     New in version 1.5.

 -- Configuration Value: 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.

     New in version 1.5.

 -- Configuration Value: 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.

     New in version 1.5.

1.5.19 Options for the Python domain
------------------------------------

 -- Configuration Value: python_use_unqualified_type_names

     If true, suppress the module name of the python reference if it can
     be resolved.  The default is ‘False’.

     New in version 4.0.

          Note: This configuration is still in experimental

1.5.19.1 Example of configuration file
......................................

     # 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 = u'test'
     copyright = u'2016, test'
     author = u'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 = u'test'
     # The full version, including alpha/beta/rc tags.
     release = u'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 = u'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', u'test Documentation',
          u'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', u'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', u'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']

1.6 Builders
============

These are the built-in Sphinx builders.  More builders can be added by
extensions.

The builder’s “name” must be given to the `-b' command-line option of
‘sphinx-build’ to select a builder.

 -- Class: sphinx.builders.html.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 Options for HTML output
     for details.

      -- Attribute: name = 'html'

          The builder’s name, for the -b command line option.

      -- Attribute: format = 'html'

          The builder’s output format, or ‘’ if no document output is
          produced.

      -- Attribute: supported_image_types: List[str(1)] =
               ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

          The list of MIME types of image formats supported by the
          builder.  Image files are searched in the order in which they
          appear here.

 -- Class: sphinx.builders.dirhtml.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/’.

      -- Attribute: name = 'dirhtml'

          The builder’s name, for the -b command line option.

      -- Attribute: format = 'html'

          The builder’s output format, or ‘’ if no document output is
          produced.

      -- Attribute: supported_image_types: List[str(2)] =
               ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

          The list of MIME types of image formats supported by the
          builder.  Image files are searched in the order in which they
          appear here.

     New in version 0.6.

 -- Class: sphinx.builders.singlehtml.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.

      -- Attribute: name = 'singlehtml'

          The builder’s name, for the -b command line option.

      -- Attribute: format = 'html'

          The builder’s output format, or ‘’ if no document output is
          produced.

      -- Attribute: supported_image_types: List[str(3)] =
               ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

          The list of MIME types of image formats supported by the
          builder.  Image files are searched in the order in which they
          appear here.

     New in version 1.0.

 -- Class: sphinxcontrib.htmlhelp.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.

      -- Attribute: name = 'htmlhelp'

          The builder’s name, for the -b command line option.

      -- Attribute: format = 'html'

          The builder’s output format, or ‘’ if no document output is
          produced.

      -- Attribute: supported_image_types: List[str(4)] = ['image/png',
               'image/gif', 'image/jpeg']

          The list of MIME types of image formats supported by the
          builder.  Image files are searched in the order in which they
          appear here.

 -- Class: sphinxcontrib.qthelp.QtHelpBuilder

     This builder produces the same output as the standalone HTML
     builder, but also generates Qt help(5) collection support files
     that allow the Qt collection generator to compile them.

     Changed in version 2.0: Moved to sphinxcontrib.qthelp from
     sphinx.builders package.

      -- Attribute: name = 'qthelp'

          The builder’s name, for the -b command line option.

      -- Attribute: format = 'html'

          The builder’s output format, or ‘’ if no document output is
          produced.

      -- Attribute: supported_image_types: List[str(6)] =
               ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

          The list of MIME types of image formats supported by the
          builder.  Image files are searched in the order in which they
          appear here.

 -- Class: sphinxcontrib.applehelp.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 ‘hiutil’, which is only available on Mac OS X
     10.6 and above.  You can disable the indexing step by setting
     applehelp_disable_external_tools to ‘True’, in which case the
     output will not be valid until ‘hiutil’ has been run on all of the
     ‘.lproj’ folders within the bundle.

      -- Attribute: name = 'applehelp'

          The builder’s name, for the -b command line option.

      -- Attribute: format = 'html'

          The builder’s output format, or ‘’ if no document output is
          produced.

      -- Attribute: supported_image_types: List[str(7)] = ['image/png',
               'image/gif', 'image/jpeg', 'image/tiff', 'image/jp2',
               'image/svg+xml']

          The list of MIME types of image formats supported by the
          builder.  Image files are searched in the order in which they
          appear here.

     New in version 1.3.

     Changed in version 2.0: Moved to sphinxcontrib.applehelp from
     sphinx.builders package.

 -- Class: sphinxcontrib.devhelp.DevhelpBuilder

     This builder produces the same output as the standalone HTML
     builder, but also generates GNOME Devhelp(8) support file that
     allows the GNOME Devhelp reader to view them.

      -- Attribute: name = 'devhelp'

          The builder’s name, for the -b command line option.

      -- Attribute: format = 'html'

          The builder’s output format, or ‘’ if no document output is
          produced.

      -- Attribute: supported_image_types: List[str(9)] = ['image/png',
               'image/gif', 'image/jpeg']

          The list of MIME types of image formats supported by the
          builder.  Image files are searched in the order in which they
          appear here.

     Changed in version 2.0: Moved to sphinxcontrib.devhelp from
     sphinx.builders package.

 -- Class: sphinx.builders.epub3.Epub3Builder

     This builder produces the same output as the standalone HTML
     builder, but also generates an `epub' file for ebook readers.  See
     Epub info 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.

      -- Attribute: name = 'epub'

          The builder’s name, for the -b command line option.

      -- Attribute: format = 'html'

          The builder’s output format, or ‘’ if no document output is
          produced.

      -- Attribute: supported_image_types: List[str(10)] =
               ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

          The list of MIME types of image formats supported by the
          builder.  Image files are searched in the order in which they
          appear here.

     New in version 1.4.

     Changed in version 1.5: Since Sphinx-1.5, the epub3 builder is used
     for the default builder of epub.

 -- Class: sphinx.builders.latex.LaTeXBuilder

     This builder produces a bunch of LaTeX files in the output
     directory.  You have to specify which documents are to be included
     in which LaTeX files via the latex_documents.
     configuration value.  There are a few configuration values that
     customize the output of this builder, see the chapter Options for LaTeX output
     for details.

     The produced LaTeX file uses several LaTeX packages that may not be
     present in a “minimal” TeX distribution installation.

     On Ubuntu xenial, the following packages need to be installed for
     successful PDF builds:

        * ‘texlive-latex-recommended’

        * ‘texlive-fonts-recommended’

        * ‘tex-gyre’ (if latex_engine is ‘'pdflatex'’)

        * ‘texlive-latex-extra’

        * ‘latexmk’ (this is a Sphinx requirement on GNU/Linux and MacOS
          X for functioning of ‘make latexpdf’)

     Additional packages are needed in some circumstances (see the
     discussion of the ‘'fontpkg'’ key of latex_elements for
     more information):

        * ‘texlive-lang-cyrillic’ for Cyrillic (even individual
          letters), and, ‘cm-super’ or ‘cm-super-minimal’ (if default
          fonts),

        * ‘texlive-lang-greek’ for Greek (even individual letters), and,
          ‘cm-super’ or ‘cm-super-minimal’ (if default fonts),

        * ‘texlive-xetex’ if latex_engine is ‘'xelatex'’,

        * ‘texlive-luatex’ if latex_engine is ‘'lualatex'’,

        * ‘fonts-freefont-otf’ if latex_engine is
          ‘'xelatex'’ or ‘'lualatex'’.

     The testing of Sphinx LaTeX is done on Ubuntu xenial whose TeX
     distribution is based on a TeXLive 2015 snapshot dated March 2016.

     Changed in version 1.6: Formerly, testing had been done on Ubuntu
     precise (TeXLive 2009).

     Changed in version 2.0: Formerly, testing had been done on Ubuntu
     trusty (TeXLive 2013).

     Changed in version 4.0.0: TeX Gyre fonts dependency for the default
     LaTeX font configuration.

          Note: Since 1.6, ‘make latexpdf’ uses ‘latexmk’ (not on
          Windows).  This makes sure the needed number of runs is
          automatically executed to get the cross-references, bookmarks,
          indices, and tables of contents right.

          One can pass to ‘latexmk’ options via the ‘LATEXMKOPTS’
          Makefile variable.  For example:

               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:

               make latexpdf LATEXOPTS="--halt-on-error"

      -- Attribute: name = 'latex'

          The builder’s name, for the -b command line option.

      -- Attribute: format = 'latex'

          The builder’s output format, or ‘’ if no document output is
          produced.

      -- Attribute: supported_image_types: List[str(11)] =
               ['application/pdf', 'image/png', 'image/jpeg']

          The list of MIME types of image formats supported by the
          builder.  Image files are searched in the order in which they
          appear here.

Note that a direct PDF builder is being provided by rinohtype(12).  The
builder’s name is ‘rinoh’.  Refer to the rinohtype manual(13) for
details.

 -- Class: sphinx.builders.text.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.

      -- Attribute: name = 'text'

          The builder’s name, for the -b command line option.

      -- Attribute: format = 'text'

          The builder’s output format, or ‘’ if no document output is
          produced.

      -- Attribute: supported_image_types: List[str(14)] = []

          The list of MIME types of image formats supported by the
          builder.  Image files are searched in the order in which they
          appear here.

     New in version 0.4.

 -- Class: sphinx.builders.manpage.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 man_pages configuration value.

      -- Attribute: name = 'man'

          The builder’s name, for the -b command line option.

      -- Attribute: format = 'man'

          The builder’s output format, or ‘’ if no document output is
          produced.

      -- Attribute: supported_image_types: List[str(15)] = []

          The list of MIME types of image formats supported by the
          builder.  Image files are searched in the order in which they
          appear here.

     New in version 1.0.

 -- Class: sphinx.builders.texinfo.TexinfoBuilder

     This builder produces Texinfo files that can be processed into Info
     files by the ‘makeinfo’ program.  You have to specify which
     documents are to be included in which Texinfo files via the
     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 ‘info’.  See Texinfo info
     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/’.

      -- Attribute: name = 'texinfo'

          The builder’s name, for the -b command line option.

      -- Attribute: format = 'texinfo'

          The builder’s output format, or ‘’ if no document output is
          produced.

      -- Attribute: supported_image_types: List[str(16)] = ['image/png',
               'image/jpeg', 'image/gif']

          The list of MIME types of image formats supported by the
          builder.  Image files are searched in the order in which they
          appear here.

     New in version 1.1.

 -- Class: sphinxcontrib.serializinghtml.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(17) 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'

      -- 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 Serialization builder details for details about the
     output format.

     New in version 0.5.

 -- Class: sphinxcontrib.serializinghtml.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 Serialization builder details for details about the
     output format.

      -- Attribute: name = 'pickle'

          The builder’s name, for the -b command line option.

          The old name ‘web’ still works as well.

      -- Attribute: format = 'html'

          The builder’s output format, or ‘’ if no document output is
          produced.

      -- Attribute: supported_image_types: List[str(18)] =
               ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

          The list of MIME types of image formats supported by the
          builder.  Image files are searched in the order in which they
          appear here.

     The file suffix is ‘.fpickle’.  The global context is called
     ‘globalcontext.pickle’, the search index ‘searchindex.pickle’.

 -- Class: sphinxcontrib.serializinghtml.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 Serialization builder details for details about the
     output format.

      -- Attribute: name = 'json'

          The builder’s name, for the -b command line option.

      -- Attribute: format = 'html'

          The builder’s output format, or ‘’ if no document output is
          produced.

      -- Attribute: supported_image_types: List[str(19)] =
               ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

          The list of MIME types of image formats supported by the
          builder.  Image files are searched in the order in which they
          appear here.

     The file suffix is ‘.fjson’.  The global context is called
     ‘globalcontext.json’, the search index ‘searchindex.json’.

     New in version 0.5.

 -- Class: sphinx.builders.gettext.MessageCatalogBuilder

     This builder produces gettext-style message catalogs.  Each
     top-level file or subdirectory grows a single ‘.pot’ catalog
     template.

     See the documentation on Internationalization for
     further reference.

      -- Attribute: name = 'gettext'

          The builder’s name, for the -b command line option.

      -- Attribute: format = ''

          The builder’s output format, or ‘’ if no document output is
          produced.

      -- Attribute: supported_image_types: List[str(20)] = []

          The list of MIME types of image formats supported by the
          builder.  Image files are searched in the order in which they
          appear here.

     New in version 1.1.

 -- Class: sphinx.builders.changes.ChangesBuilder

     This builder produces an HTML overview of all versionadded,
     see versionchanged and deprecated directives
     for the current version.  This is useful to generate a
     ChangeLog file, for example.

      -- Attribute: name = 'changes'

          The builder’s name, for the -b command line option.

      -- Attribute: format = ''

          The builder’s output format, or ‘’ if no document output is
          produced.

      -- Attribute: supported_image_types: List[str(21)] = []

          The list of MIME types of image formats supported by the
          builder.  Image files are searched in the order in which they
          appear here.

 -- Class: sphinx.builders.dummy.DummyBuilder

     This builder produces no output.  The input is only parsed and
     checked for consistency.  This is useful for linting purposes.

      -- Attribute: name = 'dummy'

          The builder’s name, for the -b command line option.

      -- Attribute: supported_image_types: List[str(22)] = []

          The list of MIME types of image formats supported by the
          builder.  Image files are searched in the order in which they
          appear here.

     New in version 1.4.

 -- Class: sphinx.builders.linkcheck.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 ‘output.txt’ in the output
     directory.

      -- Attribute: name = 'linkcheck'

          The builder’s name, for the -b command line option.

      -- Attribute: format = ''

          The builder’s output format, or ‘’ if no document output is
          produced.

      -- Attribute: supported_image_types: List[str(23)] = []

          The list of MIME types of image formats supported by the
          builder.  Image files are searched in the order in which they
          appear here.

     Changed in version 1.5: Since Sphinx-1.5, the linkcheck builder
     comes to use requests module.

     Changed in version 3.4: The linkcheck builder retries links when
     servers apply rate limits.

 -- Class: sphinx.builders.xml.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.

      -- Attribute: name = 'xml'

          The builder’s name, for the -b command line option.

      -- Attribute: format = 'xml'

          The builder’s output format, or ‘’ if no document output is
          produced.

      -- Attribute: supported_image_types: List[str(24)] = []

          The list of MIME types of image formats supported by the
          builder.  Image files are searched in the order in which they
          appear here.

     New in version 1.2.

 -- Class: sphinx.builders.xml.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.

      -- Attribute: name = 'pseudoxml'

          The builder’s name, for the -b command line option.

      -- Attribute: format = 'pseudoxml'

          The builder’s output format, or ‘’ if no document output is
          produced.

      -- Attribute: supported_image_types: List[str(25)] = []

          The list of MIME types of image formats supported by the
          builder.  Image files are searched in the order in which they
          appear here.

     New in version 1.2.

Built-in Sphinx extensions that offer more builders are:

   * doctest.

   * coverage.

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/library/stdtypes.html#str

   (2) https://docs.python.org/3/library/stdtypes.html#str

   (3) https://docs.python.org/3/library/stdtypes.html#str

   (4) https://docs.python.org/3/library/stdtypes.html#str

   (5) https://doc.qt.io/qt-4.8/qthelp-framework.html

   (6) https://docs.python.org/3/library/stdtypes.html#str

   (7) https://docs.python.org/3/library/stdtypes.html#str

   (8) https://wiki.gnome.org/Apps/Devhelp

   (9) https://docs.python.org/3/library/stdtypes.html#str

   (10) https://docs.python.org/3/library/stdtypes.html#str

   (11) https://docs.python.org/3/library/stdtypes.html#str

   (12) https://github.com/brechtm/rinohtype

   (13) https://www.mos6581.org/rinohtype/quickstart.html#sphinx-builder

   (14) https://docs.python.org/3/library/stdtypes.html#str

   (15) https://docs.python.org/3/library/stdtypes.html#str

   (16) https://docs.python.org/3/library/stdtypes.html#str

   (17) https://pypi.org/project/phpserialize/

   (18) https://docs.python.org/3/library/stdtypes.html#str

   (19) https://docs.python.org/3/library/stdtypes.html#str

   (20) https://docs.python.org/3/library/stdtypes.html#str

   (21) https://docs.python.org/3/library/stdtypes.html#str

   (22) https://docs.python.org/3/library/stdtypes.html#str

   (23) https://docs.python.org/3/library/stdtypes.html#str

   (24) https://docs.python.org/3/library/stdtypes.html#str

   (25) https://docs.python.org/3/library/stdtypes.html#str

1.6.1 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 PickleHTMLBuilder is a builtin subclass that implements
the pickle serialization interface.

The files per source file have the extensions of 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:

SerializingHTMLBuilder.globalcontext_filename.

     A pickled dict with these keys:

     ‘project’, ‘copyright’, ‘release’, ‘version’

          The same values as given in the configuration file.

     ‘style’

          See 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.

See 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.

1.7 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 Developing extensions for Sphinx.

1.7.1 Built-in extensions
-------------------------

These extensions are built in and can be activated by respective entries
in the extensions configuration value:

1.7.1.1 ‘sphinx.ext.autodoc’ – Include documentation from docstrings
....................................................................

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
     sys.path(1) – adapt your sys.path(2) in the configuration file
     accordingly.

     Warning: 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(3) or Google(4) style docstrings over
reStructuredText, you can also enable the napoleon extension.
napoleon is a preprocessor that converts your docstrings to
correct reStructuredText before ‘autodoc’ processes them.

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/library/sys.html#sys.path

   (2) https://docs.python.org/3/library/sys.html#sys.path

   (3)
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt

   (4)
https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings

1.7.1.2 Directives
..................

‘autodoc’ provides several directives that are versions of the usual
py;module, 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
py;module, py;class etc.  directive.

     Note: Just as py;class respects the current
     py;module, autoclass will also do so.  Likewise,
     see automethod will respect the current py;class.

 -- reStructuredText Directive: .. automodule::
 -- reStructuredText Directive: .. autoclass::
 -- reStructuredText Directive: .. 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.

     Options
     .......

      -- reStructuredText directive-option: :members: (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

      -- reStructuredText directive-option: :undoc-members: (no value)

          If set, autodoc will also generate document for the members
          not having docstrings:

               .. automodule:: noodle
                  :members:
                  :undoc-members:

      -- reStructuredText directive-option: :private-members: (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

          New in version 1.1.

          Changed in version 3.2: The option can now take arguments.

      -- reStructuredText directive-option: :special-members: (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__

          New in version 1.1.

          Changed in version 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
          autodoc_default_options.

               Tip: You can use a negated form, ‘'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

          Changed in version 3.5: The default options can be overridden
          or extended temporarily.

        * autodoc considers a member private if its docstring contains
          ‘:meta private:’ in its Info field lists.  For
          example:

               def my_function(my_arg, my_other_arg):
                   """blah blah blah

                   :meta private:
                   """

          New in version 3.0.

        * autodoc considers a member public if its docstring contains
          ‘:meta public:’ in its Info field lists, even if it
          starts with an underscore.  For example:

               def _my_function(my_arg, my_other_arg):
                   """blah blah blah

                   :meta public:
                   """

          New in version 3.1.

        * autodoc considers a variable member does not have any default
          value if its docstring contains ‘:meta hide-value:’ in its
          Info field lists.  Example:

               var1 = None  #: :meta hide-value:

          New in version 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’.

          Note: this will lead to markup errors if the inherited members
          come from a module whose docstrings are not reST formatted.

          New in version 0.3.

          Changed in version 3.0: It takes an ancestor class name as an
          argument.

        * 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.

          New in version 0.4.

        * The automodule, autoclass and
          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 automodule, this will be inserted for every
          class that is documented in the module).

          New in version 0.4.

        * All autodoc directives support the ‘noindex’ flag option that
          has the same effect as for standard py;function.
          etc.  directives: no index entries are generated for the
          documented object (and all autodocumented members).

          New in version 0.4.

        * automodule also recognizes the ‘synopsis’,
          ‘platform’ and ‘deprecated’ options that the standard
          py;module directive supports.

          New in version 0.5.

        * automodule and autoclass also has an
          ‘member-order’ option that can be used to override the global
          value of autodoc_member_order for one directive.

          New in version 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.

          New in version 0.6.

        * In an 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.

          New in version 1.2.

        * Add a list of modules in the autodoc_mock_imports.
          to prevent import errors to halt the building process when
          some external dependencies are not importable at build time.

          New in version 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

        * autoclass also recognizes the ‘class-doc-from’
          option that can be used to override the global value of
          autoclass_content.

          New in version 4.1.

 -- reStructuredText Directive: .. autofunction::
 -- reStructuredText Directive: .. autodecorator::
 -- reStructuredText Directive: .. autodata::
 -- reStructuredText Directive: .. automethod::
 -- reStructuredText Directive: .. autoattribute::
 -- reStructuredText Directive: .. autoproperty::

     These work exactly like autoclass etc., but do not
     offer the options used for automatic member documentation.

     autodata and 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."""

     Changed in version 0.6: autodata and
     autoattribute can now extract docstrings.

     Changed in version 1.1: Comment docs are now allowed on the same
     line after an assignment.

     Changed in version 1.2: autodata and
     autoattribute have an ‘annotation’ option.

     Changed in version 2.0: autodecorator added.

     Changed in version 2.1: autoproperty added.

     Changed in version 3.4: autodata and
     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.

1.7.1.3 Configuration
.....................

There are also config values that you can set:

 -- Configuration Value: autoclass_content

     This value selects what content will be inserted into the main body
     of an 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
          automethod or the ‘members’ option to
          autoclass.

     ‘"both"’

          Both the class’ and the ‘__init__’ method’s docstring are
          concatenated and inserted.

     ‘"init"’

          Only the ‘__init__’ method’s docstring is inserted.

     New in version 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.

     New in version 1.4.

 -- Configuration Value: autodoc_class_signature

     This value selects how the signautre will be displayed for the
     class defined by 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"’.

     New in version 4.1.

 -- Configuration Value: 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.

     New in version 0.6.

     Changed in version 1.0: Support for ‘'bysource'’.

 -- Configuration Value: 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'’.

     New in version 1.0.

     Deprecated since version 1.8: Integrated into
     autodoc_default_options.

 -- Configuration Value: 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'’ and ‘'class-doc-from'’.

     New in version 1.8.

     Changed in version 2.0: Accepts ‘True’ as a value.

     Changed in version 2.1: Added ‘'imported-members'’.

     Changed in version 4.1: Added ‘'class-doc-from'’.

 -- Configuration Value: 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.

     New in version 1.1.

     Changed in version 3.1: Support overloaded signatures

     Changed in version 4.0: Overloaded signatures do not need to be
     separated by a backslash

 -- Configuration Value: 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:

          autodoc_mock_imports = ["django"]

     Will mock all imports under the ‘django’ package.

     New in version 1.3.

     Changed in version 1.6: This config value only requires to declare
     the top-level modules that should be mocked.

 -- Configuration Value: 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.

     New in version 2.1.

     New in version 3.0: New option ‘'description'’ is added.

     New in version 4.1: New option ‘'both'’ is added.

 -- Configuration Value: 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.

     New in version 4.0.

 -- Configuration Value: autodoc_type_aliases

     A dictionary for users defined type aliases(1) 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
     Postponed Evaluation of Annotations (PEP 563)(2) 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:

             ...

     New in version 3.3.

 -- Configuration Value: 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 (default)

        * ‘'short'’ – Suppress the leading module names of the typehints
          (ex.  ‘io.StringIO’ -> ‘StringIO’)

     New in version 4.4.

 -- Configuration Value: 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.

     New in version 4.0: Added as an experimental feature.  This will be
     integrated into autodoc core in the future.

 -- Configuration Value: autodoc_warningiserror

     This value controls the behavior of sphinx-build -W.
     during importing modules.  If ‘False’ is given, autodoc forcedly
     suppresses the error if the imported module emits warnings.  By
     default, ‘True’.

 -- Configuration Value: 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’.

     New in version 1.7.

 -- Configuration Value: suppress_warnings

     ‘autodoc’ supports to suppress warning messages via
     suppress_warnings.  It allows following warnings types in
     addition:

        * autodoc

        * autodoc.import_object

   ---------- Footnotes ----------

   (1) https://www.python.org/dev/peps/pep-0563/

   (2)
https://mypy.readthedocs.io/en/latest/kinds_of_types.html#type-aliases

1.7.1.4 Docstring preprocessing
...............................

autodoc provides the following additional events:

 -- Event: autodoc-process-docstring (app, what, name, obj, options,
          lines)

     New in version 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.

     Parameters:

        * ‘app’ – the Sphinx application object

        * ‘what’ – the type of the object which the docstring belongs to
          (one of ‘"module"’, ‘"class"’, ‘"exception"’, ‘"function"’,
          ‘"method"’, ‘"attribute"’)

        * ‘name’ – the fully qualified name of the object

        * ‘obj’ – the object itself

        * ‘options’ – the options given to the directive: an object with
          attributes ‘inherited_members’, ‘undoc_members’,
          ‘show_inheritance’ and ‘noindex’ that are true if the flag
          option of same name was given to the auto directive

        * ‘lines’ – the lines of the docstring, see above

 -- Event: autodoc-before-process-signature (app, obj, bound_method)

     New in version 2.4.

     Emitted before autodoc formats a signature for an object.  The
     event handler can modify an object to change its signature.

     Parameters:

        * ‘app’ – the Sphinx application object

        * ‘obj’ – the object itself

        * ‘bound_method’ – a boolean indicates an object is bound method
          or not

 -- Event: autodoc-process-signature (app, what, name, obj, options,
          signature, return_annotation)

     New in version 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.

     Parameters:

        * ‘app’ – the Sphinx application object

        * ‘what’ – the type of the object which the docstring belongs to
          (one of ‘"module"’, ‘"class"’, ‘"exception"’, ‘"function"’,
          ‘"method"’, ‘"attribute"’)

        * ‘name’ – the fully qualified name of the object

        * ‘obj’ – the object itself

        * ‘options’ – the options given to the directive: an object with
          attributes ‘inherited_members’, ‘undoc_members’,
          ‘show_inheritance’ and ‘noindex’ that are true if the flag
          option of same name was given to the auto directive

        * ‘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.

        * ‘return_annotation’ – function return annotation as a string
          of the form ‘" -> annotation"’, or ‘None’ if there is no
          return annotation

The sphinx.ext.autodoc module provides factory functions for
commonly needed docstring processing in event
autodoc-process-docstring.:

 -- Function: sphinx.ext.autodoc.cut_lines (pre: int, post: int = 0,
          what: Optional[str] = None) -> Callable

     Return a listener that removes the first `pre' and last `post'
     lines of every docstring.  If `what' is a sequence of strings, only
     docstrings of a type in `what' will be processed.

     Use like this (e.g.  in the ‘setup()’ function of ‘conf.py’):

          from sphinx.ext.autodoc import cut_lines
          app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))

     This can (and should) be used in place of ‘automodule_skip_lines’.

 -- Function: sphinx.ext.autodoc.between (marker: str, what:
          Optional[Sequence[str]] = None, keepempty: bool = False,
          exclude: bool = False) -> Callable

     Return a listener that either keeps, or if `exclude' is True
     excludes, lines between lines that match the `marker' regular
     expression.  If no line matches, the resulting docstring would be
     empty, so no change will be made unless `keepempty' is true.

     If `what' is a sequence of strings, only docstrings of a type in
     `what' will be processed.

 -- 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.

     Parameters:

        * ‘app’ – the Sphinx application object

        * ‘name’ – the fully qualified name of the object

        * ‘obj’ – the object itself

        * ‘options’ – the options given to the class directive

        * ‘bases’ – the list of base classes signature.  see above.

     New in version 4.1.

     Changed in version 4.3: ‘bases’ can contain a string as a base
     class name.  It will be processed as reST mark-up’ed text.

1.7.1.5 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)

     New in version 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.

     Parameters:

        * ‘app’ – the Sphinx application object

        * ‘what’ – the type of the object which the docstring belongs to
          (one of ‘"module"’, ‘"class"’, ‘"exception"’, ‘"function"’,
          ‘"method"’, ‘"attribute"’)

        * ‘name’ – the fully qualified name of the object

        * ‘obj’ – the object itself

        * ‘skip’ – a boolean indicating if autodoc will skip this member
          if the user handler does not override the decision

        * ‘options’ – the options given to the directive: an object with
          attributes ‘inherited_members’, ‘undoc_members’,
          ‘show_inheritance’ and ‘noindex’ that are true if the flag
          option of same name was given to the auto directive

1.7.1.6 ‘sphinx.ext.autosectionlabel’ – Allow reference sections using its title
................................................................................

New in version 1.4.

This extension allows you to refer sections its title.  This affects to
the reference role (see 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.

1.7.1.7 Configuration
.....................

 -- Configuration Value: 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.

 -- Configuration Value: 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).

1.7.1.8 ‘sphinx.ext.autosummary’ – Generate autodoc summaries
.............................................................

New in version 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 sphinx.ext.autosummary extension does this in two parts:

  1. There is an autosummary directive for generating
     summary listings that contain links to the documented items, and
     short summary blurbs extracted from their docstrings.

  2. A autosummary directive also generates short “stub”
     files for the entries listed in its content.  These files by
     default contain only the corresponding sphinx.ext.autodoc
     directive, but can be customized with templates.

     The ‘sphinx-autogen’ script is also able to generate “stub” files
     from command line.

 -- reStructuredText 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 autosummary directive can also optionally serve as
     a toctree entry for the included items.  Optionally,
     stub ‘.rst’ files for these items can also be automatically
     generated when autosummary_generate is ‘True’.

     For example,

          .. currentmodule:: sphinx

          .. autosummary::

             environment.BuildEnvironment
             util.relative_uri

     produces a table like this:

          environment.BuildEnvironment.([app])The environment in which the ReST files are translated.

          ‘util.relative_uri’(base,Return a relative URL from ‘base’ to ‘to’.
          to)

     Autosummary preprocesses the docstrings and signatures with the
     same autodoc-process-docstring and
     autodoc-process-signature hooks as autodoc.

     `Options'

        * If you want the autosummary table to also serve as
          a 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 ‘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; ‘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.

          New in version 3.1: caption option added.

        * If you don’t want the 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 ‘mytemplate.rst’ in your
          templates_path to generate the pages for all entries
          listed.  See Customizing templates below.

          New in version 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

          New in version 3.1.

1.7.1.9 ‘sphinx-autogen’ – generate autodoc stub pages
......................................................

The ‘sphinx-autogen’ script can be used to conveniently generate stub
documentation pages for items included in autosummary.
listings.

For example, the command

     $ sphinx-autogen -o generated *.rst

will read all autosummary tables in the ‘*.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 sphinx-autogen documentation.

1.7.1.10 Generating stub pages automatically
............................................

If you do not want to create stub pages with ‘sphinx-autogen’, you can
also use these config values:

 -- Configuration Value: autosummary_context

     A dictionary of values to pass into the template engine’s context
     for autosummary stubs files.

     New in version 3.1.

 -- Configuration Value: 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.

     Changed in version 2.3: Emits autodoc-skip-member event
     as autodoc does.

     Changed in version 4.0: Enabled by default.

 -- Configuration Value: autosummary_generate_overwrite

     If true, autosummary overwrites existing files by generated stub
     pages.  Defaults to true (enabled).

     New in version 3.0.

 -- Configuration Value: autosummary_mock_imports

     This value contains a list of modules to be mocked up.  See
     autodoc_mock_imports for more details.  It defaults to
     autodoc_mock_imports.

     New in version 2.0.

 -- Configuration Value: autosummary_imported_members

     A boolean flag indicating whether to document classes and functions
     imported in modules.  Default is ‘False’

     New in version 2.1.

     Changed in version 4.4: If ‘autosummary_ignore_module_all’ is
     ‘False’, this configuration value is ignored for members listed in
     ‘__all__’.

 -- Configuration Value: 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.

     New in version 4.4.

 -- Configuration Value: 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.

     New in version 3.2.

1.7.1.11 Customizing templates
..............................

New in version 1.0.

You can customize the stub page templates, in a similar way as the HTML
Jinja templates, see Templating.  (see 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:

   - ‘autosummary/base.rst’ – fallback template

   - ‘autosummary/module.rst’ – template for modules

   - ‘autosummary/class.rst’ – template for classes

   - ‘autosummary/function.rst’ – template for functions

   - ‘autosummary/attribute.rst’ – template for class attributes

   - ‘autosummary/method.rst’ – template for class methods

The following variables available in the templates:

 -- Data: name

     Name of the documented object, excluding the module and class
     parts.

 -- Data: objname

     Name of the documented object, excluding the module parts.

 -- Data: fullname

     Full name of the documented object, including module and class
     parts.

 -- Data: module

     Name of the module the documented object belongs to.

 -- Data: class

     Name of the class the documented object belongs to.  Only available
     for methods and attributes.

 -- Data: underline

     A string containing ‘len(full_name) * '='’.  Use the ‘underline’
     filter instead.

 -- Data: members

     List containing names of all members of the module or class.  Only
     available for modules and classes.

 -- Data: inherited_members

     List containing names of all inherited members of class.  Only
     available for classes.

     New in version 1.8.0.

 -- Data: functions

     List containing names of “public” functions in the module.  Here,
     “public” here 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.

          Changed in version 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.

     New in version 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(1) that does
     html-escaping.

 -- Function: underline (s, line='=')

     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 autosummary directive in the stub
     pages.  Stub pages are generated also based on these directives.

   ---------- Footnotes ----------

   (1)
https://jinja.palletsprojects.com/en/3.0.x/templates/#jinja-filters.escape

1.7.1.12 ‘sphinx.ext.coverage’ – Collect doc coverage stats
...........................................................

This extension features one additional builder, the
CoverageBuilder.

 -- Class: sphinx.ext.coverage.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:

 -- Configuration Value: coverage_ignore_modules

 -- Configuration Value: coverage_ignore_functions

 -- Configuration Value: coverage_ignore_classes

 -- Configuration Value: coverage_ignore_pyobjects

     List of Python regular expressions(1).

     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.

     New in version 2.1.

 -- Configuration Value: coverage_c_path

 -- Configuration Value: coverage_c_regexes

 -- Configuration Value: coverage_ignore_c_items

 -- Configuration Value: coverage_write_headline

     Set to ‘False’ to not write headlines.

     New in version 1.1.

 -- Configuration Value: coverage_skip_undoc_in_source

     Skip objects that are not documented in the source with a
     docstring.  ‘False’ by default.

     New in version 1.1.

 -- Configuration Value: coverage_show_missing_items

     Print objects that are missing to standard output also.  ‘False’ by
     default.

     New in version 3.1.

   ---------- Footnotes ----------

   (1) https://docs.python.org/library/re

1.7.1.13 ‘sphinx.ext.doctest’ – Test snippets in the documentation
..................................................................

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.

1.7.1.14 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.

 -- reStructuredText 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.

 -- reStructuredText 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.

     New in version 1.1.

 -- reStructuredText Directive: .. doctest:: [group]

     A doctest-style code block.  You can use standard doctest(1) flags
     for controlling how actual output is compared with what you give as
     output.  The default set of flags is specified by the
     doctest_default_flags configuration variable.

     This directive supports five options:

        * ‘hide’, a flag option, hides the doctest block in other
          builders.  By default it is shown as a highlighted doctest
          block.

        * ‘options’, a string option, can be used to give a
          comma-separated list of doctest flags that apply to each
          example in the tests.  (You still can give explicit flags per
          example, with doctest comments, but they will show up in other
          builders too.)

        * ‘pyversion’, a string option, can be used to specify the
          required Python version for the example to be tested.  For
          instance, in the following case the example will be tested
          only for Python versions greater than 3.3:

               .. doctest::
                  :pyversion: > 3.3

          The following operands are supported:

             * ‘~=’: Compatible release clause

             * ‘==’: Version matching clause

             * ‘!=’: Version exclusion clause

             * ‘<=’, ‘>=’: Inclusive ordered comparison clause

             * ‘<’, ‘>’: Exclusive ordered comparison clause

             * ‘===’: Arbitrary equality clause.

          ‘pyversion’ option is followed PEP-440: Version Specifiers(2).

          New in version 1.6.

          Changed in version 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.

 -- reStructuredText 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.

 -- reStructuredText Directive: .. testoutput:: [group]

     The corresponding output, or the exception message, for the last
     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 doctest and the test via testcode and
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!

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/library/doctest.html#module-doctest

   (2) https://www.python.org/dev/peps/pep-0440/#version-specifiers

1.7.1.15 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:

   - testsetup and testcleanup.

        - conditionally skip test setup and/or cleanup

        - customize setup/cleanup code per environment

   - doctest.

        - conditionally skip both a test and its output verification

   - testcode.

        - conditionally skip a test

        - customize test code per environment

   - 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 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:

     extensions = ['sphinx.ext.doctest']
     doctest_global_setup = '''
     try:
         import pandas as pd
     except ImportError:
         pd = None
     '''

LiteralBlock: conf.py

     .. 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

LiteralBlock: contents.rst

1.7.1.16 Configuration
......................

The doctest extension uses the following configuration values:

 -- Configuration Value: 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.

     New in version 1.5.

 -- Configuration Value: doctest_path

     A list of directories that will be added to sys.path(1) when the
     doctest builder is used.  (Make sure it contains absolute paths.)

 -- Configuration Value: 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.

     New in version 0.6.

 -- Configuration Value: 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.

     New in version 1.1.

 -- Configuration Value: 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 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 doctest blocks, though you may set
     trim_doctest_flags to achieve that in all code blocks with
     Python console content.

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/library/sys.html#sys.path

1.7.1.17 ‘sphinx.ext.duration’ – Measure durations of Sphinx processing
.......................................................................

New in version 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.

1.7.1.18 ‘sphinx.ext.extlinks’ – Markup to shorten external links
.................................................................

`Module author: Georg Brandl'

New in version 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 ‘https://github.com/sphinx-doc/sphinx/issues/NUM’.  Typing
this URL again and again is tedious, so you can use extlinks.
to avoid repeating yourself.

The extension adds a config value:

 -- Configuration Value: 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.

     Changed in version 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.

1.7.1.19 ‘sphinx.ext.githubpages’ – Publish HTML docs in GitHub Pages
.....................................................................

New in version 1.4.

Changed in version 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
html_baseurl set.

1.7.1.20 ‘sphinx.ext.graphviz’ – Add Graphviz graphs
....................................................

New in version 0.6.

This extension allows you to embed Graphviz(1) graphs in your documents.

It adds these directives:

 -- reStructuredText 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 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 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.

     Changed in version 1.1: Added support for external files.

     options
     .......

      -- reStructuredText directive-option: :alt: alternate text (text)

          The alternate text of the graph.  By default, the graph code
          is used to the alternate text.

          New in version 1.0.

      -- reStructuredText directive-option: :align: alignment of the
               graph (left, center or right)

          The horizontal alignment of the graph.

          New in version 1.5.

      -- reStructuredText directive-option: :caption: caption of the
               graph (text)

          The caption of the graph.

          New in version 1.1.

      -- reStructuredText directive-option: :layout: layout type of the
               graph (text)

          The layout of the graph (ex.  ‘dot’, ‘neato’ and so on).  A
          path to the graphviz commands are also allowed.  By default,
          see graphviz_dot is used.

          New in version 1.4.

          Changed in version 2.2: Renamed from ‘graphviz_dot’

      -- reStructuredText directive-option: :name: label (text)

          The label of the graph.

          New in version 1.6.

      -- reStructuredText directive-option: :class: class names (a list
               of class names separated by spaces)

          The class name of the graph.

          New in version 2.4.

 -- reStructuredText 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.

     options
     .......

     Same as graphviz.

      -- reStructuredText directive-option: :alt: alternate text (text)

          New in version 1.0.

      -- reStructuredText directive-option: :align: alignment of the
               graph (left, center or right)

          New in version 1.5.

      -- reStructuredText directive-option: :caption: caption of the
               graph (text)

          New in version 1.1.

      -- reStructuredText directive-option: :layout: layout type of the
               graph (text)

          New in version 1.4.

          Changed in version 2.2: Renamed from ‘graphviz_dot’

      -- reStructuredText directive-option: :name: label (text)

          New in version 1.6.

      -- reStructuredText directive-option: :class: class names (a list
               of class names separated by spaces)

          The class name of the graph.

          New in version 2.4.

 -- reStructuredText 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";

     options
     .......

     Same as graphviz.

      -- reStructuredText directive-option: :alt: alternate text (text)

          New in version 1.0.

      -- reStructuredText directive-option: :align: alignment of the
               graph (left, center or right)

          New in version 1.5.

      -- reStructuredText directive-option: :caption: caption of the
               graph (text)

          New in version 1.1.

      -- reStructuredText directive-option: :layout: layout type of the
               graph (text)

          New in version 1.4.

          Changed in version 2.2: Renamed from ‘graphviz_dot’

      -- reStructuredText directive-option: :name: label (text)

          New in version 1.6.

      -- reStructuredText directive-option: :class: class names (a list
               of class names separated by spaces)

          The class name of the graph.

          New in version 2.4.

There are also these config values:

 -- Configuration Value: 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 ‘sphinx-build’ command line via the -D option
     should be preferable, like this:

          sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html

 -- Configuration Value: 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.

 -- Configuration Value: 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;
               }

     New in version 1.0: Previously, output always was PNG.

   ---------- Footnotes ----------

   (1) https://graphviz.org/

1.7.1.21 ‘sphinx.ext.ifconfig’ – Include content based on configuration
.......................................................................

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.

 -- reStructuredText 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
     ‘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
     add_config_value() in the setup function in ‘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).

1.7.1.22 ‘sphinx.ext.imgconverter’ – A reference image converter using Imagemagick
..................................................................................

New in version 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.

Internally, this extension uses Imagemagick(1) to convert images.

     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(2)
     (which uses Inkscape or ‘rsvg-convert’).

   ---------- Footnotes ----------

   (1) https://www.imagemagick.org/script/index.php

   (2)
https://github.com/missinglinkelectronics/sphinxcontrib-svg2pdfconverter

1.7.1.23 Configuration
......................

 -- Configuration Value: image_converter

     A path to ‘convert’ command.  By default, the imgconverter uses the
     command from search paths.

     On windows platform, ‘magick’ command is used by default.

     Changed in version 3.1: Use ‘magick’ command by default on windows

 -- Configuration Value: image_converter_args

     Additional command-line arguments to give to ‘convert’, as a list.
     The default is an empty list ‘[]’.

     On windows platform, it defaults to ‘["convert"]’.

     Changed in version 3.1: Use ‘["convert"]’ by default on windows

1.7.1.24 ‘sphinx.ext.inheritance_diagram’ – Include inheritance diagrams
........................................................................

New in version 0.6.

This extension allows you to include inheritance diagrams, rendered via
the Graphviz extension.

It adds this directive:

 -- reStructuredText 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
     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.

     Changed in version 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.

     Changed in version 1.1: Added ‘private-bases’ option; previously,
     all bases were always included.

     Changed in version 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

     Changed in version 1.7: Added ‘top-classes’ option to limit the
     scope of inheritance graphs.

1.7.1.25 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

Showing class names only:

     .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
        :parts: 1

Stopping the diagram at 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

1.7.1.26 Configuration
......................

 -- Configuration Value: 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')

 -- Configuration Value: 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')

 -- Configuration Value: inheritance_edge_attrs

     A dictionary of graphviz edge attributes for inheritance diagrams.

 -- Configuration Value: 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'}

1.7.1.27 ‘sphinx.ext.intersphinx’ – Link to other projects’ documentation
.........................................................................

New in version 0.5.

This extension can generate links to the documentation of objects in
external projects, either explicitly through the 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 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 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 ‘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 intersphinx_mapping config
     value.  The mapping will then be used to resolve both
     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.

1.7.1.28 Configuration
......................

To use Intersphinx linking, add ‘'sphinx.ext.intersphinx'’ to your
extensions config value, and use these config values to activate
linking:

 -- Configuration Value: intersphinx_mapping

     This config value contains the locations and names of other
     projects that should be linked to in this documentation.

     Relative local paths for target locations are taken as relative to
     the base of the built documentation, while relative local paths for
     inventory locations are taken as relative to the source directory.

     When fetching remote inventory files, proxy settings will be read
     from the ‘$HTTP_PROXY’ environment variable.

     `Old format for this config value'

     This is the format used before Sphinx 1.0.  It is still recognized.

     A dictionary mapping URIs to either ‘None’ or an URI. The keys are
     the base URI of the foreign Sphinx documentation sets and can be
     local paths or HTTP URIs.  The values indicate where the inventory
     file can be found: they can be ‘None’ (at the same location as the
     base URI) or another local or HTTP URI.

     `New format for this config value'

     New in version 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 ‘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 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 ‘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 ‘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'

     New in version 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)),
          }

 -- Configuration Value: 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.

 -- Configuration Value: 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.

 -- Configuration Value: intersphinx_disabled_reftypes

     New in version 4.3.

     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 an empty list.

     When a non-see 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
     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-see external.
     references will be resolved by intersphinx.

1.7.1.29 Explicitly Reference External Objects
..............................................

The Intersphinx extension provides the following role.

 -- reStructuredText Role: :external:

     New in version 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
     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`’.

1.7.1.30 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

1.7.1.31 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.

1.7.1.32 ‘sphinx.ext.linkcode’ – Add external links to source code
..................................................................

`Module author: Pauli Virtanen'

New in version 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 linkcode_resolve
function that returns an URL based on the object.

1.7.1.33 Configuration
......................

 -- Configuration Value: 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:

          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

1.7.1.34 Math support for HTML outputs in Sphinx
................................................

New in version 0.5.

Changed in version 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 directive and
role.

1.7.1.35 ‘sphinx.ext.imgmath’ – Render math as images
.....................................................

New in version 1.4.

This extension renders math via LaTeX and dvipng(1) or dvisvgm(2) 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:

 -- Configuration Value: 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(3) or dvisvgm(4).

 -- Configuration Value: 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(5) (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’.

     Changed in version 2.2: This option can be used with the ‘'svg'’
     imgmath_image_format.

 -- Configuration Value: imgmath_add_tooltips

     Default: ‘True’.  If false, do not add the LaTeX code as an “alt”
     attribute for math images.

 -- Configuration Value: imgmath_font_size

     The font size (in ‘pt’) of the displayed math.  The default value
     is ‘12’.  It must be a positive integer.

 -- Configuration Value: 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 ‘sphinx-build’ command line via the -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 imgmath_latex_args for that
     purpose.

          Hint: Some fancy LaTeX mark-up (an example was reported which
          used TikZ to add various decorations to the equation) require
          multiple runs of the LaTeX executable.  To handle this, set
          this configuration setting to ‘'latexmk'’ (or a full path to
          it) as this Perl script reliably chooses dynamically how many
          latex runs are needed.

 -- Configuration Value: imgmath_latex_args

     Additional arguments to give to latex, as a list.  The default is
     an empty list.

 -- Configuration Value: 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.

 -- Configuration Value: 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'’.

 -- Configuration Value: 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'’.

 -- Configuration Value: 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'’.

 -- Configuration Value: 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(6)). This option is
     used only when ‘imgmath_image_format’ is ‘'svg'’.

   ---------- Footnotes ----------

   (1) https://savannah.nongnu.org/projects/dvipng/

   (2) https://dvisvgm.de/

   (3) https://savannah.nongnu.org/projects/dvipng/

   (4) https://dvisvgm.de/

   (5) https://www.gnu.org/software/auctex/preview-latex.html

   (6) https://dvisvgm.de/FAQ

1.7.1.36 ‘sphinx.ext.mathjax’ – Render math via JavaScript
..........................................................

     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
     mathjax3_config).

New in version 1.1.

This extension puts math as-is into the HTML files.  The JavaScript
package MathJax(1) 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 directive and
     role, not the native MathJax ‘$$’, ‘\(’, etc.

 -- Configuration Value: 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(2) Content Delivery Network.  See the MathJax Getting
     Started page(3) 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.

     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.

 -- Configuration Value: 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 (‘{}’).

     New in version 1.8.

     Changed in version 4.4.1: Allow to change the loading method (async
     or defer) of MathJax if “async” or “defer” key is set.

 -- Configuration Value: 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(4).

     The default is empty (not configured).

     New in version 4.0.

 -- Configuration Value: mathjax2_config

     The configuration options for MathJax v2 (which can be loaded via
     mathjax_path).  The value is used as a parameter of
     ‘MathJax.Hub.Config()’.  For more information, please read Using
     in-line configuration options(5).

     For example:

          mathjax2_config = {
              'extensions': ['tex2jax.js'],
              'jax': ['input/TeX', 'output/HTML-CSS'],
          }

     The default is empty (not configured).

     New in version 4.0: mathjax_config has been renamed to
     mathjax2_config.

 -- Configuration Value: mathjax_config

     Former name of mathjax2_config.

     For help converting your old MathJax configuration to to the new
     mathjax3_config, see Converting Your v2 Configuration to
     v3(6).

     New in version 1.8.

     Changed in version 4.0: This has been renamed to
     mathjax2_config.  mathjax_config is still
     supported for backwards compatibility.

   ---------- Footnotes ----------

   (1) https://www.mathjax.org/

   (2) https://www.jsdelivr.com/

   (3) https://www.mathjax.org/#gettingstarted

   (4)
https://docs.mathjax.org/en/latest/web/configuration.html#configuration

   (5)
https://docs.mathjax.org/en/v2.7-latest/configuration.html#using-in-line-configuration-options

   (6)
https://docs.mathjax.org/en/latest/web/configuration.html#converting-your-v2-configuration-to-v3

1.7.1.37 ‘sphinx.ext.jsmath’ – Render math via JavaScript
.........................................................

This extension works just as the MathJax extension does, but uses the
older package jsMath(1).  It provides this config value:

 -- Configuration Value: 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.

   ---------- Footnotes ----------

   (1) http://www.math.union.edu/~dpvc/jsmath/

1.7.1.38 ‘sphinx.ext.napoleon’ – Support for NumPy and Google style docstrings
..............................................................................

`Module author: Rob Ruana'

New in version 1.3.

1.7.1.39 Overview
.................

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(1) is great, but it creates visually dense, hard to
read docstrings(2).  Compare the jumble above to the same thing
rewritten according to the Google Python Style Guide(3):

     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 extension that enables Sphinx to parse both
NumPy(4) and Google(5) style docstrings - the style recommended by Khan
Academy(6).

Napoleon is a pre-processor that parses NumPy(7) and Google(8) 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.

   ---------- Footnotes ----------

   (1) https://docutils.sourceforge.io/rst.html

   (2) https://www.python.org/dev/peps/pep-0287/

   (3) https://google.github.io/styleguide/pyguide.html

   (4)
https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard

   (5) https://google.github.io/styleguide/pyguide.html#Comments

   (6)
https://github.com/Khan/style-guides/blob/master/style/python.md#docstrings

   (7)
https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard

   (8) https://google.github.io/styleguide/pyguide.html#Comments

1.7.1.40 Getting Started
........................

  1. After setting up Sphinx 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

1.7.1.41 Docstrings
...................

Napoleon interprets every docstring that 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.

1.7.1.42 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’

1.7.1.43 Google vs NumPy
........................

Napoleon supports two styles of docstrings: Google(1) and NumPy(2).  The
main difference between the two styles is that Google uses indentation
to separate sections, whereas NumPy uses underlines.

Google style:

     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:

     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 Khan Academy(3) recommends using Google style.

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.

See also
........

For complete examples:

   * example_google

   * example_numpy

   ---------- Footnotes ----------

   (1) https://google.github.io/styleguide/pyguide.html#Comments

   (2)
https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard

   (3)
https://github.com/Khan/style-guides/blob/master/style/python.md#docstrings

1.7.1.44 Type Annotations
.........................

PEP 484(1) 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(2) is that type
checkers and IDEs can take advantage of them for static code analysis.
PEP 484(3) was then extended by PEP 526(4) 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(5) aren’t currently
     supported by Sphinx and won’t show up in the docs.

   ---------- Footnotes ----------

   (1) https://www.python.org/dev/peps/pep-0484/

   (2) https://www.python.org/dev/peps/pep-0484/

   (3) https://www.python.org/dev/peps/pep-0484/

   (4) https://www.python.org/dev/peps/pep-0526/

   (5)
https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code

1.7.1.45 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

 -- Configuration Value: napoleon_google_docstring

     True to parse Google style(1) docstrings.  False to disable support
     for Google style docstrings.  `Defaults to True.'

 -- Configuration Value: napoleon_numpy_docstring

     True to parse NumPy style(2) docstrings.  False to disable support
     for NumPy style docstrings.  `Defaults to True.'

 -- Configuration Value: 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

 -- Configuration Value: 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

 -- Configuration Value: 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__)

 -- Configuration Value: 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(3) 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

 -- Configuration Value: 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.

     See also
     ........

     ‘napoleon_use_admonition_for_examples’

 -- Configuration Value: napoleon_use_admonition_for_references

     True to use the ‘.. admonition::’ directive for `References'
     sections.  False to use the ‘.. rubric::’ directive instead.
     `Defaults to False.'

     See also
     ........

     ‘napoleon_use_admonition_for_examples’

 -- Configuration Value: 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(4) 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

 -- Configuration Value: 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(5) 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

 -- Configuration Value: 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 ‘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)

     See also
     ........

     ‘napoleon_use_param’

 -- Configuration Value: 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(6) 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

 -- Configuration Value: napoleon_preprocess_types

     True to convert the type definitions in the docstrings as
     references.  Defaults to `False'.

     New in version 3.2.1.

     Changed in version 3.5: Do preprocess the Google style docstrings
     also.

 -- Configuration Value: 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(7) 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>`

     New in version 3.2.

 -- Configuration Value: napoleon_attr_annotations

     True to allow using PEP 526(8) 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.

     New in version 3.4.

 -- Configuration Value: 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.

     New in version 1.8.

     Changed in version 3.5: Support ‘params_style’ and ‘returns_style’

   ---------- Footnotes ----------

   (1) https://google.github.io/styleguide/pyguide.html

   (2)
https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard

   (3)
https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard

   (4)
https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard

   (5)
https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard

   (6)
https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard

   (7)
https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard

   (8) https://www.python.org/dev/peps/pep-0526/

1.7.1.46 ‘sphinx.ext.todo’ – Support for todo items
...................................................

`Module author: Daniel Bültmann'

New in version 0.5.

There are two additional directives when using this extension:

 -- reStructuredText Directive: .. todo::

     Use this directive like, for example, see note.

     It will only show up in the output if todo_include_todos
     is ‘True’.

     New in version 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’.

 -- reStructuredText Directive: .. todolist::

     This directive is replaced by a list of all todo directives in the
     whole documentation, if todo_include_todos is ‘True’.

These can be configured as seen below.

1.7.1.47 Configuration
......................

 -- Configuration Value: todo_include_todos

     If this is ‘True’, see todo and todolist.
     produce output, else they produce nothing.  The default is ‘False’.

 -- Configuration Value: todo_emit_warnings

     If this is ‘True’, see todo emits a warning for each TODO
     entries.  The default is ‘False’.

     New in version 1.5.

 -- Configuration Value: todo_link_only

     If this is ‘True’, see todolist produce output without file
     path and line, The default is ‘False’.

     New in version 1.4.

autodoc provides the following an additional event:

 -- Event: todo-defined (app, node)

     New in version 1.5.

     Emitted when a todo is defined.  `node' is the defined
     ‘sphinx.ext.todo.todo_node’ node.

1.7.1.48 ‘sphinx.ext.viewcode’ – Add links to highlighted source code
.....................................................................

`Module author: Georg Brandl'

New in version 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 viewcode-find-source event.

     If viewcode_follow_imported_members is enabled, you
     will also need to resolve imported attributes using the
     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 viewcode_enable_epub).

1.7.1.49 Configuration
......................

 -- Configuration Value: viewcode_follow_imported_members

     If this is ‘True’, viewcode extension will emit
     viewcode-follow-imported event to resolve the name of the
     module by other extensions.  The default is ‘True’.

     New in version 1.3.

     Changed in version 1.8: Renamed from ‘viewcode_import’ to
     ‘viewcode_follow_imported_members’.

 -- Configuration Value: 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’.

     New in version 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(1)’s score becomes worse even if the reader
          supports.

 -- Event: viewcode-find-source (app, modname)

     New in version 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”.

     Parameters:

        * ‘app’ – The Sphinx application object.

        * ‘modname’ – The name of the module to find source code for.

 -- Event: viewcode-follow-imported (app, modname, attribute)

     New in version 1.8.

     Find the name of the original module for an attribute.

     Parameters:

        * ‘app’ – The Sphinx application object.

        * ‘modname’ – The name of the module that the attribute belongs
          to.

        * ‘attribute’ – The name of the member to follow.

   ---------- Footnotes ----------

   (1) https://github.com/IDPF/epubcheck

1.7.2 Third-party extensions
----------------------------

You can find several extensions contributed by users in the
sphinx-contrib(1) organization.  If you wish to include your extension
in this organization, simply follow the instructions provided in the
github-administration(2) project.  This is optional and there are
several extensions hosted elsewhere.  The awesome-sphinxdoc(3) project
contains a curated list of Sphinx packages, and many packages use the
Framework :: Sphinx :: Extension(4) and Framework :: Sphinx :: Theme(5)
trove classifiers for Sphinx extensions and themes, respectively.

   ---------- Footnotes ----------

   (1) https://github.com/sphinx-contrib/

   (2) https://github.com/sphinx-contrib/github-administration

   (3) https://github.com/yoloseem/awesome-sphinxdoc

   (4)
https://pypi.org/search/?c=Framework+%3A%3A+Sphinx+%3A%3A+Extension

   (5) https://pypi.org/search/?c=Framework+%3A%3A+Sphinx+%3A%3A+Theme

1.7.2.1 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 ‘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.

1.8 HTML Theming
================

Sphinx provides a number of builders for HTML and HTML-based formats.

1.8.1 Builders
--------------

     Todo: Populate when the ‘builders’ document is split up.

1.8.2 Themes
------------

New in version 0.6.

     Note: This section provides information about using pre-existing
     HTML themes.  If you wish to create your own theme, refer to
     HTML theme development.

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.

1.8.2.1 Using a theme
.....................

Using a theme provided with Sphinx is easy.  Since these do
not need to be installed, you only need to set the html_theme
config value.  For example, to enable the ‘classic’ theme, add the
following to ‘conf.py’:

     html_theme = "classic"

You can also set theme-specific options using the
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 ‘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 ‘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
html_theme_path.  This can be a list of directories, relative to
the directory containing ‘conf.py’, that can contain theme directories
or zip files.  For example, if you have a theme in the file ‘blue.zip’,
you can put it right in the directory containing ‘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

     # 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 HTML theme development.

1.8.2.2 Builtin themes
......................

`Theme overview'

`alabaster'              `classic'

`sphinxdoc'              `scrolls'

`agogo'                  `traditional'

`nature'                 `haiku'

`pyramid'                `bizstyle'

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.

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 to
          the previous/next page using the keyboard’s left and right
          arrows.  Defaults to ‘False’.

        - `globaltoc_collapse' (true or false): Only expand subsections
          of the current document in ‘globaltoc.html’ (see
          html_sidebars).  Defaults to ‘True’.

          New in version 3.1.

        - `globaltoc_includehidden' (true or false): Show even those
          subsections in ‘globaltoc.html’ (see html_sidebars)
          which have been included with the ‘:hidden:’ flag of the
          toctree directive.  Defaults to ‘False’.

          New in version 3.1.

        - `globaltoc_maxdepth' (int): The maximum depth of the toctree
          in ‘globaltoc.html’ (see html_sidebars).  Set it
          to -1 to allow unlimited depth.  Defaults to the max depth
          selected in the toctree directive.

          New in version 3.2.

`alabaster'

     Alabaster theme(1) 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(2) for
     information on how to configure html_sidebars for its
     use.

`classic'

     This is the classic theme, which looks like the Python 2
     documentation(3).  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(4).

`scrolls'

     A more lightweight theme, based on the Jinja documentation(5).  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(6).
     The following options are supported:

        - `full_logo' (true or false, default ‘False’): If this is true,
          the header will only show the 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’.

New in version 1.3: ‘alabaster’, ‘sphinx_rtd_theme’ and ‘bizstyle’
theme.

Changed in version 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.

   ---------- Footnotes ----------

   (1) https://pypi.org/project/alabaster/

   (2) https://alabaster.readthedocs.io/en/latest/installation.html

   (3) https://docs.python.org/2/

   (4)
https://github.com/sphinx-doc/sphinx/tree/master/doc/_themes/sphinx13

   (5) https://jinja.palletsprojects.com/

   (6) https://www.haiku-os.org/docs/userguide/en/contents.html

1.8.2.3 Third Party Themes
..........................

There are many third-party themes available for Sphinx.  Some of these
are for general use, while others are specific to an individual project.

sphinx-themes.org(1) is a gallery that showcases various themes for
Sphinx, with demo documentation rendered under each theme.  Themes can
also be found on PyPI(2) (using the classifier ‘Framework :: Sphinx ::
Theme’), GitHub(3) and GitLab(4).

   ---------- Footnotes ----------

   (1) https://sphinx-themes.org/

   (2)
https://pypi.org/search/?q=&o=&c=Framework+%3A%3A+Sphinx+%3A%3A+Theme

   (3) https://github.com/search?utf8=%E2%9C%93&q=sphinx+theme

   (4) https://gitlab.com/explore?name=sphinx+theme

1.9 Internationalization
========================

New in version 1.1.

Complementary to translations provided for Sphinx-generated messages
such as navigation bars, Sphinx provides mechanisms facilitating the
translation of `documents'.  See the Options for internationalization
for details on configuration.

Figure: Workflow visualization of translations in Sphinx.  (The figure
is created by plantuml(1).)

   ---------- Footnotes ----------

   (1) https://plantuml.com

1.9.1 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 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 ‘msgfmt’ for efficiency reasons.  If you make these files
discoverable with locale_dirs for your 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 locale_dirs to ‘["locale/"]’.

   * Set language to ‘es’ (also possible via -D).

   * Run your desired build.

   ---------- 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!

1.9.2 Translating with sphinx-intl
----------------------------------

1.9.2.1 Quick guide
...................

sphinx-intl(1) is a useful tool to work with Sphinx translation flow.
This section describe an easy way to translate with `sphinx-intl'.

  1. Install sphinx-intl(2).

          $ pip install sphinx-intl

  2. 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’, see
     locale_dirs is set to ‘locale/’ and gettext_compact
     is set to ‘False’ (the Sphinx document is already configured
     as such).

  3. Extract translatable messages into pot files.

          $ make gettext

     The generated pot files will be placed in the ‘_build/gettext’
     directory.

  4. Generate po files.

     We’ll use the pot files generated in the above step.

          $ 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/’

  5. 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.

          # a5600c3d2e3d48fc8c261ea0284db79b
          #: ../../builders.rst:4
          msgid "Available builders"
          msgstr "<FILL HERE BY TARGET LANGUAGE>"

     Another case, msgid is multi-line text and contains
     reStructuredText syntax:

          # 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.

  6. Build translated document.

     You need a language parameter in ‘conf.py’ or you may
     also specify the parameter on the command line.

     For for BSD/GNU make, run:

          $ make -e SPHINXOPTS="-D language='de'" html

     For Windows ‘cmd.exe’, run:

          > set SPHINXOPTS=-D language=de
          > .\make.bat html

     For PowerShell, run:

          > Set-Item env:SPHINXOPTS "-D language=de"
          > .\make.bat html

Congratulations!  You got the translated documentation in the
‘_build/html’ directory.

New in version 1.3: ‘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 ‘sphinx-intl build’
command before ‘make’ command.

   ---------- Footnotes ----------

   (1) https://pypi.org/project/sphinx-intl/

   (2) https://pypi.org/project/sphinx-intl/

1.9.2.2 Translating
...................

1.9.2.3 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 ‘sphinx-intl update’
command.

     $ sphinx-intl update -p _build/gettext

1.9.3 Using Transifex service for team translation
--------------------------------------------------

Transifex(1) 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.

  1. Install transifex-client(2).

     You need ‘tx’ command to upload resources (pot files).

          $ pip install transifex-client

     See also
     ........

     Transifex Client documentation(3)

  2. Create your transifex(4) 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/’

  3. Create config files for ‘tx’ command.

     This process will create ‘.tx/config’ in the current directory, as
     well as a ‘~/.transifexrc’ file that includes auth information.

          $ tx init
          Creating .tx folder...
          Transifex instance [https://www.transifex.com]:
          ...
          Please enter your transifex username: <transifex-username>
          Password: <transifex-password>
          ...
          Done.

  4. Upload pot files to transifex service.

     Register pot files to ‘.tx/config’ file:

          $ 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:

          $ 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.

  5. Forward the translation on transifex.

  6. Pull translated po files and make translated HTML.

     Get translated catalogs and build mo files.  For example, to build
     mo files for German (de):

          $ 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 ‘make html’ (for BSD/GNU make):

          $ 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 ‘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.

   ---------- Footnotes ----------

   (1) https://www.transifex.com/

   (2) https://pypi.org/project/transifex-client/

   (3) https://docs.transifex.com/client/introduction/

   (4) https://www.transifex.com/

1.9.4 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(1) for Sphinx (master) documentation.

  1. Login to transifex(2) service.

  2. Go to sphinx translation page(3).

  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’

   ---------- Footnotes ----------

   (1) https://www.transifex.com/sphinx-doc/sphinx-doc/

   (2) https://www.transifex.com/

   (3) https://www.transifex.com/sphinx-doc/sphinx-doc/

1.10 Setuptools integration
===========================

Sphinx supports integration with setuptools and distutils through a
custom command - ‘BuildDoc’.

1.10.1 Using setuptools integration
-----------------------------------

The Sphinx build can then be triggered from distutils, and some Sphinx
options can be set in ‘setup.py’ or ‘setup.cfg’ instead of Sphinx’s own
configuration file.

For instance, from ‘setup.py’:

     # this is only necessary when not using setuptools/distribute
     from sphinx.setup_command import BuildDoc
     cmdclass = {'build_sphinx': BuildDoc}

     name = 'My project'
     version = '1.2'
     release = '1.2.0'
     setup(
         name=name,
         author='Bernard Montgomery',
         version=release,
         cmdclass=cmdclass,
         # these are optional and override conf.py settings
         command_options={
             'build_sphinx': {
                 'project': ('setup.py', name),
                 'version': ('setup.py', version),
                 'release': ('setup.py', release),
                 'source_dir': ('setup.py', 'doc')}},
     )

     Note: If you set Sphinx options directly in the ‘setup()’ command,
     replace hyphens in variable names with underscores.  In the example
     above, ‘source-dir’ becomes ‘source_dir’.

Or add this section in ‘setup.cfg’:

     [build_sphinx]
     project = 'My project'
     version = 1.2
     release = 1.2.0
     source-dir = 'doc'

Once configured, call this by calling the relevant command on
‘setup.py’:

     $ python setup.py build_sphinx

1.10.2 Options for setuptools integration
-----------------------------------------

 -- Setuptools Configuration Value: fresh-env

     A boolean that determines whether the saved environment should be
     discarded on build.  Default is false.

     This can also be set by passing the ‘-E’ flag to ‘setup.py’:

          $ python setup.py build_sphinx -E

 -- Setuptools Configuration Value: all-files

     A boolean that determines whether all files should be built from
     scratch.  Default is false.

     This can also be set by passing the ‘-a’ flag to ‘setup.py’:

          $ python setup.py build_sphinx -a

 -- Setuptools Configuration Value: source-dir

     The target source directory.  This can be relative to the
     ‘setup.py’ or ‘setup.cfg’ file, or it can be absolute.  It defaults
     to ‘./doc’ or ‘./docs’ if either contains a file named ‘conf.py’
     (checking ‘./doc’ first); otherwise it defaults to the current
     directory.

     This can also be set by passing the ‘-s’ flag to ‘setup.py’:

          $ python setup.py build_sphinx -s $SOURCE_DIR

 -- Setuptools Configuration Value: build-dir

     The target build directory.  This can be relative to the ‘setup.py’
     or ‘setup.cfg’ file, or it can be absolute.  Default is
     ‘./build/sphinx’.

 -- Setuptools Configuration Value: config-dir

     Location of the configuration directory.  This can be relative to
     the ‘setup.py’ or ‘setup.cfg’ file, or it can be absolute.  Default
     is to use ‘source-dir’.

     This can also be set by passing the ‘-c’ flag to ‘setup.py’:

          $ python setup.py build_sphinx -c $CONFIG_DIR

     New in version 1.0.

 -- Setuptools Configuration Value: builder

     The builder or list of builders to use.  Default is ‘html’.

     This can also be set by passing the ‘-b’ flag to ‘setup.py’:

          $ python setup.py build_sphinx -b $BUILDER

     Changed in version 1.6: This can now be a comma- or space-separated
     list of builders

 -- Setuptools Configuration Value: warning-is-error

     A boolean that ensures Sphinx warnings will result in a failed
     build.  Default is false.

     This can also be set by passing the ‘-W’ flag to ‘setup.py’:

          $ python setup.py build_sphinx -W

     New in version 1.5.

 -- Setuptools Configuration Value: project

     The documented project’s name.  Default is ‘''’.

     New in version 1.0.

 -- Setuptools Configuration Value: version

     The short X.Y version.  Default is ‘''’.

     New in version 1.0.

 -- Setuptools Configuration Value: release

     The full version, including alpha/beta/rc tags.  Default is ‘''’.

     New in version 1.0.

 -- Setuptools Configuration Value: today

     How to format the current date, used as the replacement for
     ‘|today|’.  Default is ‘''’.

     New in version 1.0.

 -- Setuptools Configuration Value: link-index

     A boolean that ensures index.html will be linked to the root doc.
     Default is false.

     This can also be set by passing the ‘-i’ flag to ‘setup.py’:

          $ python setup.py build_sphinx -i

     New in version 1.0.

 -- Setuptools Configuration Value: copyright

     The copyright string.  Default is ‘''’.

     New in version 1.3.

 -- Setuptools Configuration Value: nitpicky

     Run in nit-picky mode.  Currently, this generates warnings for all
     missing references.  See the config value nitpick_ignore
     for a way to exclude some references as “known missing”.

     New in version 1.8.

 -- Setuptools Configuration Value: pdb

     A boolean to configure ‘pdb’ on exception.  Default is false.

     New in version 1.5.

1.11 Sphinx Web Support
=======================

New in version 1.1.

Sphinx provides a Python API to easily integrate Sphinx documentation
into your web application.  To learn more read the Web Support Quick Start.

1.11.1 Web Support Quick Start
------------------------------

1.11.1.1 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 WebSupport class and call its
‘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 WebSupport object.

1.11.1.2 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 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 ‘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(1) is:

     {%- 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 %}

   ---------- Footnotes ----------

   (1) https://jinja.palletsprojects.com/

1.11.1.3 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 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(1) 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 ‘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>')

   ---------- Footnotes ----------

   (1) https://flask.palletsprojects.com/

1.11.1.4 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 ‘get_search_results()’ method to retrieve search
results.  In Flask(1) 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 ‘get_search_results()’
returns a context dict in the same format that ‘get_document()’ does.

   ---------- Footnotes ----------

   (1) https://flask.palletsprojects.com/

1.11.1.5 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 ‘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
‘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 ‘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"

1.11.1.6 Comment Moderation
...........................

By default, all comments added through ‘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
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 ‘add_comment()’.

1.11.2 The WebSupport Class
---------------------------

 -- Class: sphinxcontrib.websupport.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
          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 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 BaseSearch.

     storage

          This may contain either a string representing a database uri,
          or an instance of a subclass of 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'’).

Changed in version 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.

1.11.2.1 Methods
................

1.11.3 Search Adapters
----------------------

To create a custom search adapter you will need to subclass the
BaseSearch class.  Then create an instance of the new class and
pass that as the ‘search’ keyword argument when you create the
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 BaseSearch class below.

 -- Class: sphinxcontrib.websupport.search.BaseSearch

     Defines an interface for search adapters.

Changed in version 1.6: BaseSearch class is moved to
sphinxcontrib.websupport.search from sphinx.websupport.search.

1.11.3.1 Methods
................

The following methods are defined in the BaseSearch class.  Some methods
do not need to be overridden, but some (‘add_document()’ and
‘handle_query()’) must be overridden in your subclass.  For a working
example, look at the built-in adapter for whoosh.

1.11.4 Storage Backends
-----------------------

To create a custom storage backend you will need to subclass the
StorageBackend class.  Then create an instance of the new class
and pass that as the ‘storage’ keyword argument when you create the
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 StorageBackend class below.

 -- Class: sphinxcontrib.websupport.storage.StorageBackend

     Defines an interface for storage backends.

Changed in version 1.6: StorageBackend class is moved to
sphinxcontrib.websupport.storage from sphinx.websupport.storage.

1.11.4.1 Methods
................

2 Sphinx tutorial
*****************

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(1).

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.

   ---------- Footnotes ----------

   (1) https://breathe.readthedocs.io/

2.1 Getting started
===================

2.1.1 Setting up your project and development environment
---------------------------------------------------------

In a new directory, create a file called ‘README.rst’ with the following
content.

     Lumache
     =======

     **Lumache** (/lu'make/) is a Python library for cooks and food lovers that
     creates recipes mixing random ingredients.

LiteralBlock: README.rst

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:

     $ 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 Installation from 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:

     (.venv) $ sphinx-build --version
     sphinx-build 4.0.2

If you see a similar output, you are on the right path!

2.1.2 Creating the documentation layout
---------------------------------------

Then from the command line, run the following command:

     (.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 ‘Enter’.

   - ‘> Project name’: Write “‘Lumache’” (without quotes) and press
     ‘Enter’.

   - ‘> Author name(s)’: Write “‘Graziella’” (without quotes) and press
     ‘Enter’.

   - ‘> Project release []’: Write “‘0.1’” (without quotes) and press
     ‘Enter’.

   - ‘> Project language [en]’: Leave it empty (the default, English)
     and press ‘Enter’.

After the last question, you will see the new ‘docs’ directory with the
following content.

     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 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:

     (.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: Freshly created documentation of Lumache

There we go!  You created your first HTML documentation using Sphinx.
Now you can start customizing it.

2.2 First steps to document your project using Sphinx
=====================================================

2.2.1 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:

     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.

LiteralBlock: docs/source/index.rst

This showcases several features of the reStructuredText syntax,
including:

   - a `section header' using ‘===’ for the underline,

   - two examples of Inline markup.: ‘**strong emphasis**’
     (typically bold) and ‘*emphasis*’ (typically italics),

   - an `inline external link',

   - and a ‘note’ `admonition' (one of the available 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:

     (.venv) $ cd docs
     (.venv) $ make html

After running this command, you will see that ‘index.html’ reflects the
new changes!

2.2.2 Building your documentation in other formats
--------------------------------------------------

Sphinx supports a variety of formats apart from HTML, including PDF,
EPUB, see and more.  For example, to build your documentation in
EPUB format, run this command from the ‘docs’ directory:

     (.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(1), 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 ‘make help’.

Each output format has some specific configuration options that you can
tune, see including EPUB.  For instance, the default value of
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’:

     # 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 other ways to customize Sphinx.

     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
     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.

   ---------- Footnotes ----------

   (1) https://calibre-ebook.com/

2.3 More Sphinx customization
=============================

There are two main ways to customize your documentation beyond what is
possible with core Sphinx: extensions and themes.

2.3.1 Enabling a built-in extension
-----------------------------------

In addition to these configuration values, you can customize Sphinx even
more by using extensions.  Sphinx ships several builtin ones,
and there are many more maintained by the community.

For example, to enable the sphinx.ext.duration extension,
locate the ‘extensions’ list in your ‘conf.py’ and add one element as
follows:

     # 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',
     ]

LiteralBlock: docs/source/conf.py

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:

     (.venv) $ make html
     ...
     The HTML pages are in build/html.

     ====================== slowest reading durations =======================
     0.042 temp/source/index

2.3.2 Using a third-party HTML theme
------------------------------------

Themes, on the other hand, are a way to customize the appearance of your
documentation.  Sphinx has several builtin themes, and there
are also third-party ones(1).

For example, to use the Furo(2) third-party theme in your HTML
documentation, first you will need to install it with ‘pip’ in your
Python virtual environment, like this:

     (.venv) $ pip install furo

And then, locate the ‘html_theme’ variable on your ‘conf.py’ and replace
its value as follows:

     # The theme to use for HTML and HTML Help pages.  See the documentation for
     # a list of builtin themes.
     #
     html_theme = 'furo'

LiteralBlock: docs/source/conf.py

With this change, you will notice that your HTML documentation has now a
new appearance:

Figure: HTML documentation of Lumache with the Furo theme

It is now time to expand the narrative documentation and split it into several documents.

   ---------- Footnotes ----------

   (1) https://sphinx-themes.org/

   (2) https://pradyunsg.me/furo/

2.4 Narrative documentation in Sphinx
=====================================

2.4.1 Structuring your documentation across multiple pages
----------------------------------------------------------

The file ‘index.rst’ created by ‘sphinx-quickstart’ is the 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:

     Usage
     =====

     Installation
     ------------

     To use Lumache, first install it using pip:

     .. code-block:: console

        (.venv) $ pip install lumache

LiteralBlock: docs/source/usage.rst

This new file contains two section headers, normal paragraph
text, and a 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’ directive at the end
of ‘index.rst’ including the document you just created, as follows:

     Contents
     --------

     .. toctree::

        usage

LiteralBlock: docs/source/index.rst

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:

     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.

2.4.2 Adding cross-references
-----------------------------

One powerful feature of Sphinx is the ability to seamlessly add
cross-references 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’:

     Check out the :doc:`usage` section for further information.

LiteralBlock: docs/source/index.rst

The doc. role 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 ref role, and
add an explicit `label' that acts as a target(1).

For example, to reference the “Installation” subsection, add a label
right before the heading, as follows:

     Usage
     =====

     .. _installation:

     Installation
     ------------

     ...

LiteralBlock: docs/source/usage.rst

And make the sentence you added in ‘index.rst’ look like this:

     Check out the :doc:`usage` section for further information, including how to
     :ref:`install <installation>` the project.

LiteralBlock: docs/source/index.rst

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 documenting code objects in Sphinx.?  Read on!

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-targets

2.5 Describing code in Sphinx
=============================

In the previous sections of the tutorial 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
domain.  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.

2.5.1 Python
------------

2.5.1.1 Documenting Python objects
..................................

Sphinx offers several roles and directives to document Python objects,
all grouped together in the Python domain.  For example, you
can use the py;function directive to document a Python
function, as follows:

     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]

LiteralBlock: docs/source/usage.rst

Which will render like this:

Figure: 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 a info field list containing the
     function parameter, its expected type, the return value, and the
     return type.

     Note: The ‘py:’ prefix specifies the domain.  You may
     configure the default domain so you can omit the prefix, either
     globally using the primary_domain configuration, or use
     the 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.

2.5.1.2 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 a corresponding role.
For the case of functions, you can use
py;func for that, as follows:

     The ``kind`` parameter should be either ``"meat"``, ``"fish"``,
     or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients`
     will raise an exception.

LiteralBlock: docs/source/usage.rst

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
py;exception directive:

     .. py:exception:: lumache.InvalidKindError

        Raised if the kind is invalid.

LiteralBlock: docs/source/usage.rst

Then, add this exception to the original description of the 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
        :raise lumache.InvalidKindError: If the kind is invalid.
        :return: The ingredients list.
        :rtype: list[str]

LiteralBlock: docs/source/usage.rst

And finally, this is how the result would look:

Figure: HTML result of documenting a Python function in Sphinx with
cross-references

Beautiful, isn’t it?

2.5.1.3 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’:

     # 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())

LiteralBlock: docs/source/conf.py

     Note: An alternative to changing the sys.path(1) 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
doctest extension in ‘conf.py’:

     extensions = [
         'sphinx.ext.duration',
         'sphinx.ext.doctest',
     ]

LiteralBlock: docs/source/conf.py

Next, write a doctest block as follows:

     >>> import lumache
     >>> lumache.get_random_ingredients()
     ['shells', 'gorgonzola', 'parsley']

LiteralBlock: docs/source/usage.rst

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:

     def get_random_ingredients(kind=None):
         return ["eggs", "bacon", "spam"]

LiteralBlock: lumache.py

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:

     (.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:

     def get_random_ingredients(kind=None):
         return ["shells", "gorgonzola", "parsley"]

LiteralBlock: lumache.py

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 how to automate the process.

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/library/sys.html#sys.path

2.5.2 Other languages (C, C++, others)
--------------------------------------

2.5.2.1 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(1),

   - Julia(2), or

   - PHP(3).

For example, to document a C++ type definition, you would use the
built-in cpp;type directive, as follows:

     .. cpp:type:: std::vector<int> CustomList

        A typedef-like declaration of a type.

Which would give the following result:

 -- C++ Type: typedef 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 cpp;type
role as follows:

     Cross reference to :cpp:type:`CustomList`.

Which would produce a hyperlink to the previous definition:
CustomList.

   ---------- Footnotes ----------

   (1) https://sphinx-fortran.readthedocs.io

   (2) http://bastikr.github.io/sphinx-julia

   (3) https://github.com/markstory/sphinxcontrib-phpdomain

2.6 Automatic documentation generation from code
================================================

In the previous section 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 Python docstrings(1) in
the documentation, rather than having to write the information in two
places.

Fortunately, see the autodoc extension provides this
functionality.

   ---------- Footnotes ----------

   (1) https://www.python.org/dev/peps/pep-0257/#what-is-a-docstring

2.6.1 Reusing signatures and docstrings with autodoc
----------------------------------------------------

To use autodoc, first add it to the list of enabled extensions:

     extensions = [
         'sphinx.ext.duration',
         'sphinx.ext.doctest',
         'sphinx.ext.autodoc',
     ]

LiteralBlock: docs/source/conf.py

Next, move the content of the ‘.. py:function’ directive to the function
docstring in the original Python file, as follows:

     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"]

LiteralBlock: lumache.py

Finally, replace the ‘.. py:function’ directive from the Sphinx
documentation with autofunction.:

     you can use the ``lumache.get_random_ingredients()`` function:

     .. autofunction:: lumache.get_random_ingredients

LiteralBlock: docs/source/usage.rst

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:

     class InvalidKindError(Exception):
         """Raised if the kind is invalid."""
         pass

LiteralBlock: lumache.py

And replace the ‘.. py:exception’ directive with autoexception
as follows:

     or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients`
     will raise an exception.

     .. autoexception:: lumache.InvalidKindError

LiteralBlock: docs/source/usage.rst

And again, after running ‘make html’, the output will be the same as
before.

2.6.2 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 autosummary.
extension.

The autosummary directive generates documents that contain
all the necessary ‘autodoc’ directives.  To use it, first enable the
autosummary extension:

     extensions = [
        'sphinx.ext.duration',
        'sphinx.ext.doctest',
        'sphinx.ext.autodoc',
        'sphinx.ext.autosummary',
     ]

LiteralBlock: docs/source/conf.py

Next, create a new ‘api.rst’ file with these contents:

     API
     ===

     .. autosummary::
        :toctree: generated

        lumache

LiteralBlock: docs/source/api.rst

Remember to include the new document in the root toctree:

     Contents
     --------

     .. toctree::

        usage
        api

LiteralBlock: docs/source/index.rst

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: 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(1) that
     can be customized, but that is out of scope for this
     tutorial.

   ---------- Footnotes ----------

   (1) https://jinja2docs.readthedocs.io/

2.7 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
Publishing your documentation sources.

2.7.1 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(1) 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(2) is a simple static web hosting tightly integrated
     with GitHub(3): 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(4)).  It is free to use and supports
     custom domains.

`GitLab Pages'

     GitLab Pages(5) is a similar concept to GitHub Pages, integrated
     with GitLab(6) and usually automated with GitLab CI(7) instead.

`Netlify'

     Netlify(8) is a sophisticated hosting for static sites enhanced by
     client-side web technologies like JavaScript (so-called
     "Jamstack"(9)).  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.

   ---------- Footnotes ----------

   (1) https://readthedocs.org/

   (2) https://pages.github.com/

   (3) https://github.com/

   (4) https://github.com/features/actions

   (5) https://about.gitlab.com/stages-devops-lifecycle/pages/

   (6) https://gitlab.com/

   (7)
https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/

   (8) https://www.netlify.com/

   (9) https://jamstack.org/

2.7.2 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(1), 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"(2).

The most popular Version Control System nowadays is Git(3), 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.

   ---------- Footnotes ----------

   (1) https://en.wikipedia.org/wiki/Version_control

   (2) https://www.writethedocs.org/guide/docs-as-code/

   (3) https://git-scm.com/

2.7.3 Publishing your documentation sources
-------------------------------------------

2.7.3.1 GitHub
..............

The quickest way to upload an existing project to GitHub is to:

  1. Sign up for a GitHub account(1).

  2. Create a new repository(2).

  3. Open the "Upload files" page(3) 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 Commit changes button.

     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(4) to learn more about how
     the GitHub interface works.

   - Read this quickstart tutorial(5) to install extra software on your
     machine and have more flexibility.  You can either use the Git
     command line, or the GitHub Desktop application.

   ---------- Footnotes ----------

   (1) https://github.com/signup

   (2) https://github.com/new

   (3)
https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository

   (4) https://lab.github.com/githubtraining/introduction-to-github

   (5) https://docs.github.com/en/get-started/quickstart

2.7.3.2 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(1).

  2. Create a new blank project(2).

  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 Upload File button (3).

Again, these steps do not require additional software on your computer.
To learn more, you can:

   - Follow this tutorial(4) to install Git on your machine.

   - Browse the GitLab User documentation(5) to understand the
     possibilities of the platform.

     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.

   ---------- Footnotes ----------

   (1) https://gitlab.com/users/sign_up

   (2) https://gitlab.com/projects/new

   (3) 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.

   (4) https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html

   (5) https://docs.gitlab.com/ee/user/index.html

2.7.4 Publishing your HTML documentation
----------------------------------------

2.7.4.1 Read the Docs
.....................

Read the Docs(1) offers integration with both GitHub and GitLab.  The
quickest way of getting started is to follow the RTD tutorial(2), which
is loosely based on this one.  You can publish your sources on GitHub as
explained in the previous section, then skip directly to Sign
up for Read the Docs(3).  If you choose GitLab instead, the process is
similar.

   ---------- Footnotes ----------

   (1) https://readthedocs.org/

   (2) https://docs.readthedocs.io/en/stable/tutorial/index.html

   (3)
https://docs.readthedocs.io/en/stable/tutorial/index.html#sign-up-for-read-the-docs

2.7.4.2 GitHub Pages
....................

GitHub Pages(1) requires you to publish your sources on
GitHub(2).  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(3).

After you have published your sources on GitHub, create a file named
‘.github/workflows/sphinx.yml’ in your repository with the following
contents:

     name: Sphinx build

     on: push

     jobs:
       build:
         runs-on: ubuntu-latest
         steps:
         - uses: actions/checkout@v2
         - name: Build HTML
           uses: ammaraskar/sphinx-action@0.4
         - name: Upload artifacts
           uses: actions/upload-artifact@v1
           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

LiteralBlock: .github/workflows/

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:

     furo==2021.11.16

LiteralBlock: docs/requirements.txt

And finally, you are ready to enable GitHub Pages on your repository(4).
For that, go to Settings, then Pages on the left sidebar, select the
‘gh-pages’ branch in the “Source” dropdown menu, and click Save.  After
a few minutes, you should be able to see your HTML at the designated
URL.

   ---------- Footnotes ----------

   (1) https://pages.github.com/

   (2) https://github.com/

   (3) https://github.com/features/actions

   (4)
https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site

2.7.4.3 GitLab Pages
....................

GitLab Pages(1), on the other hand, requires you to publish your sources
on GitLab(2).  When you are ready, you can automate the
process of running ‘make html’ using GitLab CI(3).

After you have published your sources on GitLab, create a file named
‘.gitlab-ci.yml’ in your repository with these contents:

     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

LiteralBlock: .gitlab-ci.yml

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(4) by entering a
     payment method (you will be charged a small amount that will then
     be reimbursed).

After that, if the pipeline is successful, you should be able to see
your HTML at the designated URL.

   ---------- Footnotes ----------

   (1) https://about.gitlab.com/stages-devops-lifecycle/pages/

   (2) https://gitlab.com/

   (3)
https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/

   (4)
https://about.gitlab.com/blog/2021/05/17/prevent-crypto-mining-abuse/#validating-an-account

2.8 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.

3 Extending Sphinx
******************

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 Using Sphinx.  For a more
detailed discussion of the extension interface see Developing extensions for Sphinx.

3.1 Developing extensions overview
==================================

This page contains general information about developing Sphinx
extensions.

3.1.1 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
‘conf.py’ file, but this is not available to you as an extension
developer.

To ensure that another extension is activated as a part of your own
extension, use the 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:

     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.

3.2 Extension tutorials
=======================

Refer to the following tutorials to get started with extension
development.

3.2.1 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 other tutorials that go into more
details.

     Warning: For this extension, you will need some basic understanding
     of docutils(1) and Python.

   ---------- Footnotes ----------

   (1) https://docutils.sourceforge.io/

3.2.1.1 Overview
................

We want the extension to add the following to Sphinx:

   * A ‘helloworld’ directive, that will simply output the text “hello
     world”.

3.2.1.2 Prerequisites
.....................

We will not be distributing this plugin via PyPI(1) 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 ‘sphinx-quickstart’.

We assume you are using separate source (‘source’) and build (‘build’)
folders.  Your extension file could be in any folder of your project.
In our case, let’s do the following:

  1. Create an ‘_ext’ folder in ‘source’

  2. Create a new Python file in the ‘_ext’ folder called
     ‘helloworld.py’

Here is an example of the folder structure you might obtain:

     └── source
         ├── _ext
         │   └── helloworld.py
         ├── _static
         ├── conf.py
         ├── somefolder
         ├── index.rst
         ├── somefile.rst
         └── someotherfile.rst

   ---------- Footnotes ----------

   (1) https://pypi.org/

3.2.1.3 Writing the extension
.............................

Open ‘helloworld.py’ and paste the following code in it:

     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,
         }

Some essential things are happening in this example, and you will see
them for all directives.

The directive class
...................

Our new directive is declared in the ‘HelloWorld’ class.

     class HelloWorld(Directive):

         def run(self):
             paragraph_node = nodes.paragraph(text='Hello World!')
             return [paragraph_node]

This class extends the docutils(1)’ ‘Directive’ class.  All extensions
that create directives should extend this class.

See also
........

The docutils documentation on creating directives(2)

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.

See also
........

The docutils documentation on nodes(3)

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.

The ‘setup’ function
....................

This function is a requirement.  We use it to plug our new directive
into Sphinx.

     def setup(app):
         app.add_directive("helloworld", HelloWorld)

         return {
             'version': '0.1',
             'parallel_read_safe': True,
             'parallel_write_safe': True,
         }

The simplest thing you can do it call the 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:

     Some intro text here...

     .. helloworld::

     Some more text here...

We also return the extension 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.

   ---------- Footnotes ----------

   (1) https://docutils.sourceforge.io/

   (2) https://docutils.sourceforge.io/docs/howto/rst-directives.html

   (3) https://docutils.sourceforge.io/docs/ref/doctree.html

3.2.1.4 Using the extension
...........................

The extension has to be declared in your ‘conf.py’ file to make Sphinx
aware of it.  There are two steps necessary here:

  1. Add the ‘_ext’ directory to the Python path(1) using
     ‘sys.path.append’.  This should be placed at the top of the file.

  2. Update or create the extensions list and add the
     extension file name to the list

For example:

     import os
     import sys

     sys.path.append(os.path.abspath("./_ext"))

     extensions = ['helloworld']

     Tip: We’re not distributing this extension as a Python package(2),
     we need to modify the Python path(3) 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:

     Some intro text here...

     .. helloworld::

     Some more text here...

The sample above would generate:

     Some intro text here...

     Hello World!

     Some more text here...

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH

   (2) https://packaging.python.org/

   (3) https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH

3.2.1.5 Further reading
.......................

This is the very basic principle of an extension that creates a new
directive.

For a more advanced example, refer to Developing a “TODO” extension.

3.2.2 Developing a “TODO” extension
-----------------------------------

The objective of this tutorial is to create a more comprehensive
extension than that created in Developing a “Hello world” extension.
Whereas that guide just covered writing a custom
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.

3.2.2.1 Overview
................

     Note: To understand the design of this extension, refer to
     Important objects and 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 doctree-resolved event,
     to replace the todo and todolist nodes, one for
     env-merge-info to merge intermediate results from parallel
     builds, and one for env-purge-doc. (the reason for that
     will be covered later).

3.2.2.2 Prerequisites
.....................

As with Developing a “Hello world” extension, 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 ‘sphinx-quickstart’.

We assume you are using separate source (‘source’) and build (‘build’)
folders.  Your extension file could be in any folder of your project.
In our case, let’s do the following:

  1. Create an ‘_ext’ folder in ‘source’

  2. Create a new Python file in the ‘_ext’ folder called ‘todo.py’

Here is an example of the folder structure you might obtain:

     └── source
         ├── _ext
         │   └── todo.py
         ├── _static
         ├── conf.py
         ├── somefolder
         ├── index.rst
         ├── somefile.rst
         └── someotherfile.rst

3.2.2.3 Writing the extension
.............................

Open ‘todo.py’ and paste the following code in it, all of which we will
explain in detail shortly:

     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.traverse(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.traverse(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, 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,
         }

This is far more extensive extension than the one detailed in
Developing a “Hello world” extension, however, we will will look at
each piece step-by-step to explain what’s happening.

The node classes
................

Let’s start with the node classes:

     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)

Node classes usually don’t have to do anything except inherit from the
standard docutils classes defined in ‘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(1) and Sphinx.

     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 ‘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’

The directive classes
.....................

A directive class is a class deriving usually from
docutils.parsers.rst.Directive.  The directive interface is also
covered in detail in the docutils documentation(2); 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:

     class TodolistDirective(Directive):

         def run(self):
             return [todolist('')]

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:

     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]

Several important things are covered here.  First, as you can see, we’re
now subclassing the SphinxDirective helper class instead of
the usual Directive class.  This gives us access to the
build environment instance 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          |
          +--------------------+
          | ...                |
          +--------------------+

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 the API guide,
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 env-purge-doc event:

     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]

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 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 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:

     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)

The other handler belongs to the doctree-resolved event:

     def process_todo_nodes(app, doctree, fromdocname):
         if not app.config.todo_include_todos:
             for node in doctree.traverse(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.traverse(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, 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)

The doctree-resolved event is emitted at the end of
phase 3 (resolving) 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
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.

The ‘setup’ function
....................

As noted previously, 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:

     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,
         }

The calls in this function refer to the classes and functions we added
earlier.  What the individual calls do is the following:

   * 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 phase 1 (reading)).

   * 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 phase 4 (writing).  Since the ‘todolist’ node is
     always replaced in phase 3 (resolving), it doesn’t need
     any.

   * add_directive() adds a new `directive', given by name
     and class.

   * Finally, see 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.

   ---------- Footnotes ----------

   (1) https://docutils.sourceforge.io/docs/ref/doctree.html

   (2) https://docutils.sourceforge.io/docs/ref/rst/directives.html

3.2.2.4 Using the extension
...........................

As before, we need to enable the extension by declaring it in our
‘conf.py’ file.  There are two steps necessary here:

  1. Add the ‘_ext’ directory to the Python path(1) using
     ‘sys.path.append’.  This should be placed at the top of the file.

  2. Update or create the 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:

     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:

     Hello, world
     ============

     .. toctree::
        somefile.rst
        someotherfile.rst

     Hello world. Below is the list of TODOs.

     .. todolist::

LiteralBlock: index.rst

     foo
     ===

     Some intro text here...

     .. todo:: Fix this

LiteralBlock: somefile.rst

     bar
     ===

     Some more text here...

     .. todo:: Fix that

LiteralBlock: someotherfile.rst

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.

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH

3.2.2.5 Further reading
.......................

For more information, refer to the docutils(1) documentation and
Developing extensions for Sphinx.

   ---------- Footnotes ----------

   (1) https://docutils.sourceforge.io/docs/

3.2.3 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(1) and is provided here with the original author’s
     permission.

   ---------- Footnotes ----------

   (1)
https://opensource.com/article/18/11/building-custom-workflows-sphinx

3.2.3.1 Overview
................

We want the extension to add the following to Sphinx:

   * A ‘recipe’ directive, containing some content describing
     the recipe steps, along with a ‘:contains:’ option highlighting the
     main ingredients of the recipe.

   * A ‘ref’ role, which provides a cross-reference to the
     recipe itself.

   * A ‘recipe’ 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

3.2.3.2 Prerequisites
.....................

We need the same setup as in the previous extensions.  This
time, we will be putting out extension in a file called ‘recipe.py’.

Here is an example of the folder structure you might obtain:

     └── source
         ├── _ext
         │   └── recipe.py
         ├── conf.py
         └── index.rst

3.2.3.3 Writing the extension
.............................

Open ‘recipe.py’ and paste the following code in it, all of which we
will explain in detail shortly:

     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 '{}.{}'.format('recipe', node.arguments[0])

         def get_objects(self):
             for obj in self.data['recipes']:
                 yield(obj)

         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 = '{}.{}'.format('recipe', signature)
             anchor = 'recipe-{}'.format(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,
         }

Let’s look at each piece of this extension step-by-step to explain
what’s going on.

The directive class
...................

The first thing to examine is the ‘RecipeDirective’ directive:

     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)

Unlike Developing a “Hello world” extension and
Developing a “TODO” extension, this directive doesn’t derive from
docutils.parsers.rst.Directive and doesn’t define a ‘run’
method.  Instead, it derives from
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_taget_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 previous tutorial, this directive
takes a single argument, the recipe name, and an option, ‘contains’, in
addition to the nested reStructuredText in the body.

The index classes
.................

     Todo: Add brief overview of indices

     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

Both ‘IngredientIndex’ and ‘RecipeIndex’ are derived from 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 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 domain API guide for more information on this API.

These index pages can be referred by combination of domain name and its
‘name’ using ref role.  For example, ‘RecipeIndex’ can be
referred by ‘:ref:`recipe-recipe`’.

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.

     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 '{}.{}'.format('recipe', node.arguments[0])

         def get_objects(self):
             for obj in self.data['recipes']:
                 yield(obj)

         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 = '{}.{}'.format('recipe', signature)
             anchor = 'recipe-{}'.format(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))

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 ‘sphinx.roles.XRefRole’ role and defining the
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 ‘recipe2ingredient’.
These contain 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.

The ‘setup’ function
....................

See As always, 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.

     def setup(app):
         app.add_domain(RecipeDomain)

         return {
             'version': '0.1',
             'parallel_read_safe': True,
             'parallel_write_safe': True,
         }

This looks a little different to what we’re used to seeing.  There are
no calls to add_directive() or even add_role().
Instead, we have a single call to add_domain() followed by
some initialization of the standard domain.  This is because
we had already registered our directives, roles and indexes as part of
the directive itself.

3.2.3.4 Using the extension
...........................

You can now use the extension throughout your project.  For example:

     Joe's Recipes
     =============

     Below are a collection of my favourite recipes. I highly recommend the
     :recipe:ref:`TomatoSoup` recipe in particular!

     .. toctree::

        tomato-soup

LiteralBlock: index.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.

LiteralBlock: tomato-soup.rst

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.

3.2.3.5 Further reading
.......................

For more information, refer to the docutils(1) documentation and
Developing extensions for Sphinx.

   ---------- Footnotes ----------

   (1) https://docutils.sourceforge.io/docs/

3.2.4 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’)

3.2.4.1 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.

3.2.4.2 Prerequisites
.....................

We need the same setup as in the previous extensions.  This
time, we will be putting out extension in a file called
‘autodoc_intenum.py’.  The ‘my_enums.py’ will contain the sample enums
we will document.

Here is an example of the folder structure you might obtain:

     └── source
         ├── _ext
         │   └── autodoc_intenum.py
         ├── conf.py
         ├── index.rst
         └── my_enums.py

3.2.4.3 Writing the extension
.............................

Start with ‘setup’ function for the extension.

     def setup(app: Sphinx) -> None:
         app.setup_extension('sphinx.ext.autodoc')  # Require autodoc extension
         app.add_autodocumenter(IntEnumDocumenter)

The ‘setup_extension()’ method will pull the autodoc extension because
our new extension depends on autodoc.  ‘add_autodocumenter()’ is the
method that registers our new auto documenter class.

We want to import certain objects from the autodoc extension:

     from enum import IntEnum
     from typing import Any, Optional

     from docutils.statemachine import StringList

     from sphinx.application import Sphinx
     from sphinx.ext.autodoc import ClassDocumenter, bool_option

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:

     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: Optional[StringList],
                         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)

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.

3.2.4.4 Using the extension
...........................

You can now use the new autodoc directive to document any ‘IntEnum’.

For example, you have the following ‘IntEnum’:

     class Colors(IntEnum):
         """Colors enumerator"""
         NONE = 0
         RED = 1
         GREEN = 2
         BLUE = 3

LiteralBlock: my_enums.py

This will be the documentation file with auto-documentation directive:

     .. autointenum:: my_enums.Colors

LiteralBlock: index.rst

3.3 Configuring builders
========================

3.3.1 Discover builders by entry point
--------------------------------------

New in version 1.6.

builder extensions can be discovered by means of entry
points(1) so that they do not have to be listed in the 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
name attribute, which is the name passed to the 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’

     setup(
         # ...
         entry_points={
             'sphinx.builders': [
                 'mybuilder = my.extension.module',
             ],
         }
     )

Note that it is still necessary to register the builder using
add_builder() in the extension’s ‘setup()’ function.

   ---------- Footnotes ----------

   (1)
https://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins

3.4 HTML theme development
==========================

New in version 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 HTML 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 Developing extensions for Sphinx for more
     information that may be helpful in developing themes.

3.4.1 Creating themes
---------------------

Themes take the form of either a directory or a zipfile (whose name is
the theme name), containing the following:

   * A ‘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 ‘theme.conf’ file is in INI format (1) (readable by the standard
Python ‘ConfigParser’ module) and has the following structure:

     [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 the name of a CSS file which will be
     referenced in the HTML header.  If you need more than one CSS file,
     either include one from the other via CSS’ ‘@import’, or use a
     custom HTML template that adds ‘<link rel="stylesheet">’ tags as
     necessary.  Setting the 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
     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 ‘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 html_sidebars config value.

   * The `options' section contains pairs of variable names and default
     values.  These options can be overridden by the user in
     html_theme_options and are accessible from all templates as
     ‘theme_<name>’.

New in version 1.7: sidebar settings

   ---------- Footnotes ----------

   (1) It is not an executable Python file, as opposed to ‘conf.py’,
because that would pose an unnecessary security risk if themes are
shared.

3.4.2 Distribute your theme as a Python package
-----------------------------------------------

As a way to distribute your theme, you can use Python package.  Python
package brings to users easy setting up ways.

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.

New in version 1.2: ‘sphinx_themes’ entry_points feature.

Deprecated since version 1.6: ‘sphinx_themes’ entry_points has been
deprecated.

New in version 1.6: ‘sphinx.html_themes’ entry_points feature.

3.4.3 Templating
----------------

The guide to 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.

3.4.3.1 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 is built with the classic
theme, the output directory will contain a ‘_static/classic.css’ file
where all template tags have been processed.

3.4.3.2 Use custom page metadata in HTML templates
..................................................

Any key / value pairs in field lists that are placed `before'
the page’s title will be available to the Jinja template when building
the page within the meta attribute.  For example, if a page
had the following text before its first title:

     :mykey: My value

     My first title
     --------------

Then it could be accessed within a Jinja template like so:

     {%- 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.

3.4.3.3 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 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
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 html-page-context.

     # 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:

     <div>
     {{ my_func("some string") }}
     </div>

3.4.3.4 Add your own static files to the build assets
.....................................................

If you are packaging your own build assets with an extension (e.g., a
CSS or JavaScript file), you need to ensure that they are placed in the
‘_static/’ folder of HTML outputs.  To do so, you may copy them directly
into a build’s ‘_static/’ folder at build time, generally via an event
hook.  Here is some sample code to accomplish this:

     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('builder-inited', copy_custom_files)

3.4.3.5 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:

     mymodule/
     ├── _static
     │   └── myjsfile.js_t
     └── mymodule.py

Will result in the following static file placed in your HTML’s build
output:

     _build/
     └── html
         └── _static
             └── myjsfile.js

See Static templates for more information.

Second, you may use the ‘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:

     # 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')
         # 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 ‘conf.py’ file.

4 Man Pages
***********

These are the applications provided as part of Sphinx.

4.1 Core Applications
=====================

4.1.1 sphinx-quickstart
-----------------------

4.1.1.1 Synopsis
................

`sphinx-quickstart'

4.1.1.2 Description
...................

‘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 ‘sphinx-build(1)’.

4.1.1.3 Options
...............

 -- 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.

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.

Project Basic Options
.....................

 -- Option: -p PROJECT, --project=PROJECT

     Project name will be set.  (see project).

 -- Option: -a AUTHOR, --author=AUTHOR

     Author names.  (see copyright).

 -- Option: -v VERSION

     Version of project.  (see version).

 -- Option: -r RELEASE, --release=RELEASE

     Release of project.  (see release).

 -- Option: -l LANGUAGE, --language=LANGUAGE

     Document language.  (see language).

 -- Option: --suffix=SUFFIX

     Source file suffix.  (see source_suffix).

 -- Option: --master=MASTER

     Master document name.  (see root_doc).

Extension Options
.................

 -- Option: --ext-autodoc

     Enable ‘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.

Makefile and Batchfile Creation Options
.......................................

 -- Option: --use-make-mode (-m), --no-use-make-mode (-M)

     ‘Makefile/make.bat’ uses (or doesn’t use) make-mode.
     Default is ‘use’, which generates a more concise
     ‘Makefile/make.bat’.

     Changed in version 1.5: make-mode is default.

 -- Option: --makefile, --no-makefile

     Create (or not create) makefile.

 -- Option: --batchfile, --no-batchfile

     Create (or not create) batchfile

Project templating
..................

New in version 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

4.1.1.4 See also
................

‘sphinx-build(1)’

4.1.2 sphinx-build
------------------

4.1.2.1 Synopsis
................

`sphinx-build' [`options'] <`sourcedir'> <`outputdir'> [`filenames' …]

4.1.2.2 Description
...................

‘sphinx-build’ generates documentation from the files in ‘<sourcedir>’
and places it in the ‘<outputdir>’.

‘sphinx-build’ looks for ‘<sourcedir>/conf.py’ for the configuration
settings.  ‘sphinx-quickstart(1)’ may be used to generate template
files, including ‘conf.py’.

‘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
sphinx-build -b.

By default, everything that is outdated is built.  Output only for
selected files can be built by specifying individual filenames.

4.1.2.3 Options
...............

 -- 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 ‘hiutil’ and ‘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 ‘pdflatex’.

     `man'

          Build manual pages in groff format for UNIX systems.

     `texinfo'

          Build Texinfo files that can be processed into Info files
          using ‘makeinfo’.

     `text'

          Build plain text files.

     `gettext'

          Build gettext-style message catalogs (‘.pot’ files).

     `doctest'

          Run all doctests in the documentation, if the 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 Builders for a list of all builders shipped with
     Sphinx.  Extensions can add their own builders.
 -- Option: -M buildername

     Alternative to -b.  Uses the Sphinx ‘make_mode’ module,
     which provides the same build functionality as a default
     Makefile or Make.bat.  In addition to all Sphinx
     Builders, the following build pipelines are available:

     `latexpdf'

          Build LaTeX files and run them through ‘pdflatex’, or as per
          latex_engine setting.  If language is
          set to ‘'ja'’, will use automatically the ‘platex/dvipdfmx’
          latex to PDF pipeline.

     `info'

          Build Texinfo files and run them through ‘makeinfo’.

          Important: Sphinx only recognizes the ‘-M’ option if it is
          placed first.

     New in version 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 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 only.
     directives that only include their content if this tag is set.

     New in version 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 ‘.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

     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'.

     New in version 1.2: This option should be considered
     `experimental'.

     Changed in version 1.7: Support ‘auto’ argument.

 -- Option: -c path

     Don’t look for the ‘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.

     New in version 0.3.

 -- Option: -C

     Don’t look for a configuration file; only take options via the ‘-D’
     option.

     New in version 0.5.

 -- Option: -D setting=value

     Override a configuration value set in the ‘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.

     Changed in version 0.6: The value can now be a dictionary value.

     Changed in version 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.

     New in version 0.5.

 -- Option: -n

     Run in nit-picky mode.  Currently, this generates warnings for all
     missing references.  See the config value nitpick_ignore
     for a way to exclude some references as “known missing”.

 -- Option: -N

     Do not emit colored output.

 -- Option: -v

     Increase verbosity (loglevel).  This option can be given up to
     three times to get more debug logging output.  It implies -T.

     New in version 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.

     New in version 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.

     New in version 1.2.

 -- Option: -P

     (Useful for debugging only.)  Run the Python debugger, pdb(1), if
     an unhandled exception occurs while building.

 -- Option: -h, --help, --version

     Display usage summary or Sphinx version.

     New in version 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).

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/library/pdb.html#module-pdb

4.1.2.4 Environment Variables
.............................

The ‘sphinx-build’ refers following environment variables:

 -- Describe: MAKE

     A path to make command.  A command name is also allowed.
     ‘sphinx-build’ uses it to invoke sub-build process on make-mode.

Makefile Options
................

The ‘Makefile’ and ‘make.bat’ files created by ‘sphinx-quickstart’
usually run ‘sphinx-build’ only with the -b and -d
options.  However, they support the following variables to
customize behavior:

 -- Describe: PAPER

     This sets the ‘'papersize'’ key of 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
     ‘sphinx-quickstart’.

 -- Describe: SPHINXOPTS

     Additional options for ‘sphinx-build’.  These options can also be
     set via the shortcut variable `O' (capital ‘o’).

4.1.2.5 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

4.1.2.6 See also
................

‘sphinx-quickstart(1)’

4.2 Additional Applications
===========================

4.2.1 sphinx-apidoc
-------------------

4.2.1.1 Synopsis
................

`sphinx-apidoc' [`OPTIONS'] -o <`OUTPUT_PATH'> <`MODULE_PATH'>
[`EXCLUDE_PATTERN' …]

4.2.1.2 Description
...................

‘sphinx-apidoc’ is a tool for automatic generation of Sphinx sources
that, using the ‘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(1) file and/or directory
patterns that will be excluded from generation.

     Warning: ‘sphinx-apidoc’ generates source files that use
     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.

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/library/fnmatch.html

4.2.1.3 Options
...............

 -- 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.

 -- 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.

 -- 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 –full
     is provided.

 -- Option: -F, --full

     Generate a full Sphinx project (‘conf.py’, ‘Makefile’ etc.)  using
     the same mechanism as ‘sphinx-quickstart’.

 -- Option: -e, --separate

     Put documentation for each module on its own page.

     New in version 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.

     New in version 1.2.

 -- Option: --implicit-namespaces

     By default sphinx-apidoc processes sys.path searching for modules
     only.  Python 3.3 introduced PEP 420(1) 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 –full is specified:

 -- Option: -a

     Append module_path to sys.path.

 -- Option: -H <project>

     Sets the project name to put in generated files (see project).

 -- Option: -A <author>

     Sets the author name(s) to put in generated files (see
     copyright).

 -- Option: -V <version>

     Sets the project version to put in generated files (see
     version).

 -- Option: -R <release>

     Sets the project release to put in generated files (see
     release).

Project templating
..................

New in version 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’)

   ---------- Footnotes ----------

   (1) https://www.python.org/dev/peps/pep-0420

4.2.1.4 Environment
...................

 -- Environment Variable: SPHINX_APIDOC_OPTIONS

     A comma-separated list of option to append to generated
     ‘automodule’ directives.  Defaults to
     ‘members,undoc-members,show-inheritance’.

4.2.1.5 See also
................

‘sphinx-build(1)’, ‘sphinx-autogen(1)’

4.2.2 sphinx-autogen
--------------------

4.2.2.1 Synopsis
................

`sphinx-autogen' [`options'] <sourcefile> …

4.2.2.2 Description
...................

‘sphinx-autogen’ is a tool for automatic generation of Sphinx sources
that, using the ‘autodoc’ extension, document items included in
autosummary listing(s).

`sourcefile' is the path to one or more reStructuredText documents
containing autosummary entries with the ‘:toctree::’ option
set.  `sourcefile' can be an fnmatch(1)-style pattern.

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/library/fnmatch.html#module-fnmatch

4.2.2.3 Options
...............

 -- 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.

4.2.2.4 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:

     Modules
     =======

     .. autosummary::
        :toctree: modules

        foobar.foo
        foobar.bar
        foobar.bar.baz

If you run the following:

     $ 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 ‘autodoc’ directive and some
other information.

4.2.2.5 See also
................

‘sphinx-build(1)’, ‘sphinx-apidoc(1)’

5 Templating
************

Sphinx uses the Jinja(1) 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.

   ---------- Footnotes ----------

   (1) https://jinja.palletsprojects.com/

5.1 Do I need to use Sphinx’s templates to produce HTML?
========================================================

No.  You have several other options:

   * You can write a TemplateBridge subclass that calls your
     template engine of choice, and set the template_bridge.
     configuration value accordingly.

   * You can write a custom builder that derives from
     StandaloneHTMLBuilder and calls your template engine of
     choice.

   * You can use the ‘PickleHTMLBuilder’ that produces pickle files with
     the page contents, and postprocess them using a custom tool, or use
     them in your Web application.

5.2 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
`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 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 ‘themes/basic’
subdirectory of the Sphinx installation directory, and used by all
builtin Sphinx themes.  Templates with the same name in the
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.

5.3 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:

5.3.1 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
     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 html_sidebars.
config value.  Their use is deprecated in favor of separate sidebar
templates, which can be included via html_sidebars.

‘sidebartoc’

     The table of contents within the sidebar.

     Deprecated since version 1.0.

‘sidebarrel’

     The relation links (previous, next document) within the sidebar.

     Deprecated since version 1.0.

‘sidebarsourcelink’

     The “Show source” link within the sidebar (normally only shown if
     this is enabled by html_show_sourcelink).

     Deprecated since version 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 since version 1.0.

5.3.2 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 since version 1.8.0: Please use ‘.Sphinx.add_js_file()’
     instead.

5.3.3 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)

     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.

5.3.4 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 copyright.

 -- Data: docstitle

     The title of the documentation (the value of 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

     The path to the HTML favicon in the static path, or URL to the
     favicon, or ‘''’.

     Deprecated since version 4.0: Recommend to use ‘favicon_url’
     instead.

 -- Data: favicon_url

     The relative path to the HTML favicon image from the current
     document, or URL to the favicon, or ‘''’.

     New in version 4.0.

 -- Data: file_suffix

     The value of the builder’s 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
     html_copy_source is ‘True’).

 -- Data: language

     The value of language.

 -- Data: last_updated

     The build date.

 -- Data: logo

     The path to the HTML logo image in the static path, or URL to the
     logo, or ‘''’.

     Deprecated since version 4.0: Recommend to use ‘logo_url’ instead.

 -- Data: logo_url

     The relative path to the HTML logo image from the current document,
     or URL to the logo, or ‘''’.

     New in version 4.0.

 -- Data: master_doc

     Same as root_doc.

     Changed in version 4.0: Renamed to ‘root_doc’.

 -- Data: root_doc

     The value of root_doc, for usage with pathto().

     Changed in version 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 project.

 -- Data: release

     The value of 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 html_short_title.

 -- Data: show_source

     True if 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.

     New in version 4.2.

 -- Data: style

     The name of the main stylesheet, as given by the theme or
     html_style.

 -- Data: title

     The title of the current document, as used in the ‘<title>’ tag.

 -- Data: use_opensearch

     The value of html_use_opensearch.

 -- Data: version

     The value of 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 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 File-wide metadata.

 -- Data: metatags

     A string containing the page’s HTML meta(1) 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 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
     next item.

 -- Data: prev

     Like 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 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.

   ---------- Footnotes ----------

   (1) https://docutils.sourceforge.io/docs/ref/rst/directives.html#meta

6 LaTeX customization
*********************

Unlike the HTML builders, the ‘latex’ builder does not
benefit from prepared themes.  The Options for LaTeX output,
and particularly the latex_elements variable, provides much
of the interface for customization.  For example:

     # 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.

6.1 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 separately.

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'’

     New in version 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: ‘''’

     New in version 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(1), but one should be aware that current babel(2)
     has improved its support for Unicode engines in recent years and
     for some languages it may make sense to prefer ‘babel’ over
     ‘polyglossia’.

          Hint: After modifiying 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)

     Changed in version 1.5: For latex_engine set to
     ‘'xelatex'’, the default is
     ‘'\\usepackage{polyglossia}\n\\setmainlanguage{<language>}'’.

     Changed in version 1.6: ‘'lualatex'’ uses same default setting as
     ‘'xelatex'’

     Changed in version 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.

     Changed in version 1.2: Defaults to ‘''’ when the language
     uses the Cyrillic script.

     Changed in version 2.0: Incorporates some font substitution
     commands to help support occasional Greek or Cyrillic in a document
     using ‘'pdflatex'’ engine.

     Changed in version 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 ‘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
     latex_additional_files, for example:

          latex_additional_files = ["mystyle.sty"]

     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)

     New in version 1.3.

‘'atendofbody'’

     Additional document content (right before the indices).

     Default: ‘''’

     New in version 1.5.

‘'extrapackages'’

     Additional LaTeX packages.  For example:

          latex_elements = {
              'packages': 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: ‘''’

     New in version 2.3.

‘'footer'’

     Additional footer content (before the indices).

     Default: ‘''’

     Deprecated since version 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: ‘''’

     New in version 1.2.

     Changed in version 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’

     New in version 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 image(3) and figure(4) directives are now compatible
          with such filenames for PDF via LaTeX output.  But this is
          broken if ‘utf8x’ is in use.

     Changed in version 1.4.3: Previously
     ‘'\\usepackage[utf8]{inputenc}'’ was used for all compilers.

‘'cmappkg'’

     “cmap” package inclusion.

     Default: ‘'\\usepackage{cmap}'’

     New in version 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 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
               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.

     Changed in version 1.5: Defaults to ‘'\\usepackage{fontspec}'’ when
     latex_engine is ‘'xelatex'’.

     Changed in version 1.6: ‘'lualatex'’ uses ‘fontspec’ per default
     like ‘'xelatex'’.

     Changed in version 2.0: ‘'lualatex'’ executes
     ‘\defaultfontfeatures[\rmfamily,\sffamily]{}’ to disable TeX
     ligatures transforming ‘<<’ and ‘>>’ as escaping working with
     ‘pdflatex/xelatex’ failed with ‘lualatex’.

     Changed in version 2.0: Detection of ‘LGR’, ‘T2A’, ‘X2’ to trigger
     support of occasional Greek or Cyrillic letters (‘'pdflatex'’).

     Changed in version 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
     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 latex_engine other than ‘'pdflatex'’.

     New in version 4.0.0.

‘'textgreek'’

     For the support of occasional Greek letters.

     It is ignored with ‘'platex'’, ‘'xelatex'’ or ‘'lualatex'’ as
     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 math.
     context.  For example ‘:math:`α`’ (U+03B1) will render as \alpha.

     Default: ‘'\\usepackage{textalpha}'’ or ‘''’ if ‘fontenc’ does not
     include the ‘LGR’ option.

     New in version 2.0.

‘'geometry'’

     “geometry” package inclusion, the default definition is:

          ‘'\\usepackage{geometry}'’

     with an additional ‘[dvipdfm]’ for Japanese documents.  The Sphinx
     LaTeX style file executes:

          ‘\PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry}’

     which can be customized via corresponding ‘sphinxsetup’ options.

     Default: ‘'\\usepackage{geometry}'’ (or
     ‘'\\usepackage[dvipdfm]{geometry}'’ for Japanese documents)

     New in version 1.5.

     Changed in version 1.5.2: ‘dvipdfm’ option if latex_engine
     is ‘'platex'’.

     New in version 1.5.3: The ‘sphinxsetup’ keys for the margins.

     Changed in version 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 hmargin documentation for more.

‘'hyperref'’

     “hyperref” package inclusion; also loads package “hypcap” and
     issues ‘\urlstyle{same}’.  This is done after ‘sphinx.sty’ file is
     loaded and before executing the contents of ‘'preamble'’ key.

          Attention: Loading of packages “hyperref” and “hypcap” is
          mandatory.

     New in version 1.5: Previously this was done from inside
     ‘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'’

     Changed in version 1.8.3: Original ‘\maketitle’ from document class
     is not overwritten, hence is re-usable as part of some custom
     setting for this key.

     New in version 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 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'’

     Changed in version 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'’

     New in version 1.2.

     Changed in version 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}'’

     New in version 1.8.

     Changed in version 2.0: For ‘'xelatex'’ and ‘'lualatex'’ defaults
     to ‘'\\fvset{fontsize=\\small}'’ as this is adapted to the relative
     widths of the FreeFont family.

     Changed in version 4.0.0: Changed default for ‘'pdflatex'’.
     Previously it was using ‘'\\fvset{fontsize=\\small}'’.

     Changed in version 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'’

   ---------- Footnotes ----------

   (1) https://ctan.org/pkg/polyglossia

   (2) https://ctan.org/pkg/babel

   (3)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#image

   (4)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure

6.2 The ‘sphinxsetup’ configuration setting
===========================================

New in version 1.5.

The ‘'sphinxsetup'’ key of latex_elements 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 further uses of the ‘\sphinxsetup’ LaTeX macro
directly into the body of the document, via the help of the ‘raw’
directive.  This chapter is styled in the PDF output using the following
at the start of the chapter:

     .. raw:: latex

        \begingroup
        \sphinxsetup{%
              verbatimwithframe=false,
              VerbatimColor={named}{OldLace},
              TitleColor={named}{DarkGoldenrod},
              hintBorderColor={named}{LightCoral},
              attentionborder=3pt,
              attentionBorderColor={named}{Crimson},
              attentionBgColor={named}{FloralWhite},
              noteborder=2pt,
              noteBorderColor={named}{Olive},
              cautionborder=3pt,
              cautionBorderColor={named}{Cyan},
              cautionBgColor={named}{LightCyan}}

The below is included at the end of the chapter:

     .. 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’

     New in version 4.0.0.

‘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 latex_elements) or
          so-called TeX “true” units:

               'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw',

     New in version 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’

     New in version 1.5.3.

‘verbatimwithframe’

     Boolean to specify if 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 colour.

     Default: ‘true’.

‘verbatimwrapslines’

     Boolean to specify if long lines in 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’

‘verbatimforcewraps’

     Boolean to specify if long lines in code-block.‘s
     contents should be forcefully wrapped to never overflow due to long
     strings.

          Note: It is assumed that the Pygments(1) LaTeXFormatter has
          not been used with its ‘texcomments’ or similar options which
          allow additional (arbitrary) LaTeX mark-up.

          Also, in case of latex_engine set to ‘'pdflatex'’,
          only the default LaTeX handling of Unicode code points, i.e.
          ‘utf8’ not ‘utf8x’ is allowed.

     Default: ‘false’

     New in version 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’

     New in version 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’

     New in version 3.5.0.

‘verbatimhintsturnover’

     Boolean to specify if code-blocks display “continued on next page”
     and “continued from previous page” hints in case of pagebreaks.

     Default: ‘true’

     New in version 1.6.3.

     Changed in version 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’

     New in version 1.7.

‘parsedliteralwraps’

     Boolean to specify if long lines in parsed-literal(2)‘s contents
     should wrap.

     Default: ‘true’

     New in version 1.5.2: set this option value to ‘false’ to recover
     former behaviour.

‘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’

     New in version 1.5: set this option value to ‘false’ to recover
     former behaviour.

     Changed in version 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$}}

     Changed in version 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).

‘TitleColor’

     The colour for titles (as configured via use of package
     “titlesec”.)

     Default: ‘{rgb}{0.126,0.263,0.361}’

          Warning: Colours set via ‘'sphinxsetup'’ must obey the syntax
          of the argument of the ‘color/xcolor’ packages ‘\definecolor’
          command.

‘InnerLinkColor’

     A colour passed to ‘hyperref’ as value of ‘linkcolor’ and
     ‘citecolor’.

     Default: ‘{rgb}{0.208,0.374,0.486}’.

‘OuterLinkColor’

     A colour passed to ‘hyperref’ as value of ‘filecolor’, ‘menucolor’,
     and ‘urlcolor’.

     Default: ‘{rgb}{0.216,0.439,0.388}’

‘VerbatimColor’

     The background colour for code-block.s.

     Default: ‘{rgb}{1,1,1}’ (white)

‘VerbatimBorderColor’

     The frame color.

     Default: ‘{rgb}{0,0,0}’ (black)

‘VerbatimHighlightColor’

     The color for highlighted lines.

     Default: ‘{rgb}{0.878,1,1}’

     New in version 1.6.6.

          Note: Starting with this colour, and for all others following,
          the names declared to “color” or “xcolor” are prefixed with
          “sphinx”.

‘verbatimsep’

     The separation between code lines and the frame.

     Default: ‘\fboxsep’

‘verbatimborder’

     The width of the frame around code-block.s.

     Default: ‘\fboxrule’

‘shadowsep’

     The separation between contents and frame for contents(3) and
     topic(4) boxes.

     Default: ‘5pt’

‘shadowsize’

     The width of the lateral “shadow” to the right.

     Default: ‘4pt’

‘shadowrule’

     The width of the frame around topic(5) boxes.

     Default: ‘\fboxrule’

‘noteBorderColor’, ‘hintBorderColor’,
     ‘importantBorderColor’, ‘tipBorderColor’

     The colour for the two horizontal rules used by Sphinx in LaTeX for
     styling a note(6) type admonition.

     Default: ‘{rgb}{0,0,0}’ (black)

‘noteborder’, ‘hintborder’, ‘importantborder’, ‘tipborder’

     The width of the two horizontal rules.

     Default: ‘0.5pt’

‘warningBorderColor’, ‘cautionBorderColor’,
     ‘attentionBorderColor’, ‘dangerBorderColor’, ‘errorBorderColor’

     The colour for the admonition frame.

Default: ‘{rgb}{0,0,0}’ (black)

‘warningBgColor’, ‘cautionBgColor’,
     ‘attentionBgColor’, ‘dangerBgColor’, ‘errorBgColor’

     The background colours for the respective admonitions.

     Default: ‘{rgb}{1,1,1}’ (white)

‘warningborder’, ‘cautionborder’,
     ‘attentionborder’, ‘dangerborder’, ‘errorborder’

     The width of the frame.

     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’

     New in version 1.5.

‘HeaderFamily’

     default ‘\sffamily\bfseries’.  Sets the font used by headings.

   ---------- Footnotes ----------

   (1) https://pygments.org/

   (2)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#parsed-literal

   (3)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#contents

   (4)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic

   (5)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic

   (6) https://docutils.sourceforge.io/docs/ref/rst/directives.html#note

6.3 LaTeX macros and environments
=================================

The “LaTeX package” 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
‘sphinxhowto.cls’ and ‘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.[‘'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
     latex_additional_files list.  Check the LaTeX build repertory
     for the filenames and contents.

Changed in version 4.0.0: split of ‘sphinx.sty’ into multiple smaller
units, to facilitate customization of many aspects simultaneously.

6.3.1 Macros
------------

   - Text styling commands:

        - ‘\sphinxstrong’,

        - ‘\sphinxbfcode’,

        - ‘\sphinxemail’,

        - ‘\sphinxtablecontinued’,

        - ‘\sphinxtitleref’,

        - ‘\sphinxmenuselection’,

        - ‘\sphinxaccelerator’,

        - ‘\sphinxcrossref’,

        - ‘\sphinxtermref’,

        - ‘\sphinxoptional’.

     New in version 1.4.5: Use of ‘\sphinx’ prefixed macro names to
     limit possibilities of conflict with LaTeX packages.

   - More text styling:

        - ‘\sphinxstyleindexentry’,

        - ‘\sphinxstyleindexextra’,

        - ‘\sphinxstyleindexpageref’,

        - ‘\sphinxstyletopictitle’,

        - ‘\sphinxstylesidebartitle’,

        - ‘\sphinxstyleothertitle’,

        - ‘\sphinxstylesidebarsubtitle’,

        - ‘\sphinxstyletheadfamily’,

        - ‘\sphinxstyleemphasis’,

        - ‘\sphinxstyleliteralemphasis’,

        - ‘\sphinxstylestrong’,

        - ‘\sphinxstyleliteralstrong’,

        - ‘\sphinxstyleabbreviation’,

        - ‘\sphinxstyleliteralintitle’,

        - ‘\sphinxstylecodecontinued’,

        - ‘\sphinxstylecodecontinues’.

     New in version 1.5: These macros were formerly hard-coded as non
     customizable ‘\texttt’, ‘\emph’, etc…

     New in version 1.6: ‘\sphinxstyletheadfamily’ which defaults to
     ‘\sffamily’ and allows multiple paragraphs in header cells of
     tables.

     New in version 1.6.3: ‘\sphinxstylecodecontinued’ and
     ‘\sphinxstylecodecontinues’.

     New in version 3.0: ‘\sphinxkeyboard’

   - ‘\sphinxtableofcontents’: A wrapper (defined differently in
     ‘sphinxhowto.cls’ and in ‘sphinxmanual.cls’) of standard
     ‘\tableofcontents’.  The macro ‘\sphinxtableofcontentshook’ is
     executed during its expansion right before ‘\tableofcontents’
     itself.

     Changed in version 1.5: Formerly, the meaning of ‘\tableofcontents’
     was modified by Sphinx.

     Changed in version 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.

   - ‘\sphinxmaketitle’: Used as the default setting of the
     ‘'maketitle'’ latex_elements key.  Defined in the class
     files ‘sphinxmanual.cls’ and ‘sphinxhowto.cls’.

     Changed in version 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 latex_elements to add a custom
     definition of ‘\sphinxbackoftitlepage’.

     New in version 1.8.3.

   - ‘\sphinxcite’: A wrapper of standard ‘\cite’ for citation
     references.

6.3.2 Environments
------------------

   - A figure(1) 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’.

     New in version 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 warning(2) 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 (colours, border
     thickness) specific to each type, which can be set via
     ‘'sphinxsetup'’ string.

     Changed in version 1.5: Use of public environment names, separate
     customizability of the parameters, such as ‘noteBorderColor’,
     ‘noteborder’, ‘warningBgColor’, ‘warningBorderColor’,
     ‘warningborder’, …

   - The contents(3) directive (with ‘:local:’ option) and the topic(4)
     directive are implemented by environment ‘sphinxShadowBox’.

     New in version 1.4.2: Former code refactored into an environment
     allowing page breaks.

     Changed in version 1.5: Options ‘shadowsep’, ‘shadowsize’,
     ‘shadowrule’.

   - The literal blocks (via ‘::’ or 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 pagebreaks.  Inside tables the used environment
     is ‘sphinxVerbatimintable’ (it does not draw a frame, but allows a
     caption).

     Changed in version 1.5: ‘Verbatim’ keeps exact same meaning as in
     ‘fancyvrb.sty’ (also under the name ‘OriginalVerbatim’);
     ‘sphinxVerbatimintable’ is used inside tables.

     New in version 1.5: Options ‘verbatimwithframe’,
     ‘verbatimwrapslines’, ‘verbatimsep’, ‘verbatimborder’.

     New in version 1.6.6: Support for ‘:emphasize-lines:’ option

     New in version 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).

     Changed in version 1.5: Formerly, the original environments were
     modified by Sphinx.

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure

   (2)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#warning

   (3)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#contents

   (4)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic

6.3.3 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.

     New in version 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 ‘sphinx.sty’ has custom re-definitions in case
     of `fncychap' option ‘Bjarne’.

     Changed in version 1.5: Formerly, use of `fncychap' with other
     styles than ‘Bjarne’ was dysfunctional.

   - Docutils container(1) 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:

          \newenvironment{sphinxclassred}{\color{red}}{}

     Currently the class names must contain only ascii characters and
     avoid characters special to LaTeX such as ‘\’.

     New in version 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).

     New in version 1.6: currently all template variables are unstable
     and undocumented.

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#container

7 Developing extensions for Sphinx
**********************************

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 builder.s to support new output formats or
     actions on the parsed documents.

   * Register custom reStructuredText roles and directives, extending
     the markup using the Docutils markup API.

   * 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 Sphinx core 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 extensions configuration value.

When ‘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 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 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 Extension tutorials.

7.1 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
     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 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 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 ‘conf.py’ as attributes.  It is an
     instance of Config.

     The config is available as ‘app.config’ or ‘env.config’.

To see an example of use of these objects, refer to Extension tutorials.

7.2 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(1).  Additional nodes are provided by Sphinx
     and documented here.

     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 Developing a “TODO” extension.

   ---------- Footnotes ----------

   (1) https://docutils.sourceforge.io/docs/ref/doctree.html

7.3 Extension metadata
======================

New in version 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
     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 env-merge-info and
               env-purge-doc events if it stores dataa 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.

7.4 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 Application API) while others trigger specific
behavior (such as the i18n API)

7.4.1 Application API
---------------------

Each Sphinx extension is a Python module with at least a ‘setup()’
function.  This function is called at initialization time with one
argument, the application object representing the Sphinx process.

 -- Class: sphinx.application.Sphinx

     This application object has the public API described in the
     following.

7.4.1.1 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
‘sphinx.ext’ package.

 -- Method: Sphinx.setup_extension (extname: str) -> None

     Import and setup a Sphinx extension module.

     Load the extension given by the module `name'.  Use this if your
     extension needs the features provided by another extension.  No-op
     if called twice.

 -- Method: Sphinx.require_sphinx (version: str) -> None

     Check the Sphinx version if requested.

     Compare `version' with the version of the running Sphinx, and abort
     the build when it is too old.

     Parameters: ‘version’ – The required version in the form of
     ‘major.minor’.

     New in version 1.0.

 -- Method: Sphinx.connect (event: str, callback: Callable, priority:
          int = 500) -> int

     Register `callback' to be called when `event' is emitted.

     For details on available core events and the arguments of callback
     functions, please see Sphinx core events.

     Parameters:

        * ‘event’ – The name of target event

        * ‘callback’ – Callback function for the event

        * ‘priority’ – The priority of the callback.  The callbacks will
          be invoked in order of `priority' (ascending).

     Returns: A listener ID. It can be used for disconnect().

     Changed in version 3.0: Support `priority'

 -- Method: Sphinx.disconnect (listener_id: int) -> None

     Unregister callback by `listener_id'.

     Parameters: ‘listener_id’ – A listener_id that connect()
     returns

 -- Method: Sphinx.add_builder (builder: Type[Builder], override: bool =
          False) -> None

     Register a new builder.

     Parameters:

        * ‘builder’ – A builder class

        * ‘override’ – If true, install the builder forcedly even if
          another builder is already installed as the same name

     Changed in version 1.8: Add `override' keyword.

 -- Method: Sphinx.add_config_value (name: str, default: Any, rebuild:
          Union[bool, str], types: Any = ()) -> None

     Register a configuration value.

     This is necessary for Sphinx to recognize new values and set
     default values accordingly.

     Parameters:

        * ‘name’ – The name of the configuration value.  It is
          recommended to be prefixed with the extension name (ex.
          ‘html_logo’, ‘epub_title’)

        * ‘default’ – The default value of the configuration.

        * ‘rebuild’ – The condition of rebuild.  It must be one of those
          values:

             * ‘'env'’ if a change in the setting only takes effect when
               a document is parsed – this means that the whole
               environment must be rebuilt.

             * ‘'html'’ if a change in the setting needs a full rebuild
               of HTML documents.

             * ‘''’ if a change in the setting will not need any special
               rebuild.

        * ‘types’ – The type of configuration value.  A list of types
          can be specified.  For example, ‘[str]’ is used to describe a
          configuration that takes string value.

     Changed in version 0.4: If the `default' value is a callable, it
     will be called with the config object as its argument in order to
     get the default value.  This can be used to implement config values
     whose default depends on other values.

     Changed in version 0.6: Changed `rebuild' from a simple boolean
     (equivalent to ‘''’ or ‘'env'’) to a string.  However, booleans are
     still accepted and converted internally.

 -- Method: Sphinx.add_event (name: str) -> None

     Register an event called `name'.

     This is needed to be able to emit it.

     Parameters: ‘name’ – The name of the event

 -- Method: Sphinx.set_translator (name: str, translator_class:
          Type[docutils.nodes.NodeVisitor], override: bool = False) ->
          None

     Register or override a Docutils translator class.

     This is used to register a custom output translator or to replace a
     builtin translator.  This allows extensions to use a custom
     translator and define custom nodes for the translator (see
     add_node()).

     Parameters:

        * ‘name’ – The name of the builder for the translator

        * ‘translator_class’ – A translator class

        * ‘override’ – If true, install the translator forcedly even if
          another translator is already installed as the same name

     New in version 1.3.

     Changed in version 1.8: Add `override' keyword.

 -- Method: Sphinx.add_node (node: Type[docutils.nodes.Element],
          override: bool = False, **kwargs: Tuple[Callable,
          Optional[Callable]]) -> None

     Register a Docutils node class.

     This is necessary for Docutils internals.  It may also be used in
     the future to validate nodes in the parsed documents.

     Parameters:

        * ‘node’ – A node class

        * ‘kwargs’ – Visitor functions for each builder (see below)

        * ‘override’ – If true, install the node forcedly even if
          another node is already installed as the same name

     Node visitor functions for the Sphinx HTML, LaTeX, text and manpage
     writers can be given as keyword arguments: the keyword should be
     one or more of ‘'html'’, ‘'latex'’, ‘'text'’, ‘'man'’, ‘'texinfo'’
     or any other supported translators, the value a 2-tuple of ‘(visit,
     depart)’ methods.  ‘depart’ can be ‘None’ if the ‘visit’ function
     raises ‘docutils.nodes.SkipNode’.  Example:

          class math(docutils.nodes.Element): pass

          def visit_math_html(self, node):
              self.body.append(self.starttag(node, 'math'))
          def depart_math_html(self, node):
              self.body.append('</math>')

          app.add_node(math, html=(visit_math_html, depart_math_html))

     Obviously, translators for which you don’t specify visitor methods
     will choke on the node when encountered in a document to translate.

     Changed in version 0.5: Added the support for keyword arguments
     giving visit functions.

 -- Method: Sphinx.add_enumerable_node (node:
          Type[docutils.nodes.Element], figtype: str, title_getter:
          Optional[Callable[docutils.nodes.Node, str]] = None, override:
          bool = False, **kwargs: Tuple[Callable, Callable]) -> None

     Register a Docutils node class as a numfig target.

     Sphinx numbers the node automatically.  And then the users can
     refer it using numref.

     Parameters:

        * ‘node’ – A node class

        * ‘figtype’ – The type of enumerable nodes.  Each figtype has
          individual numbering sequences.  As system figtypes, ‘figure’,
          ‘table’ and ‘code-block’ are defined.  It is possible to add
          custom nodes to these default figtypes.  It is also possible
          to define new custom figtype if a new figtype is given.

        * ‘title_getter’ – A getter function to obtain the title of
          node.  It takes an instance of the enumerable node, and it
          must return its title as string.  The title is used to the
          default title of references for ref.  By default,
          Sphinx searches ‘docutils.nodes.caption’ or
          ‘docutils.nodes.title’ from the node as a title.

        * ‘kwargs’ – Visitor functions for each builder (same as
          add_node())

        * ‘override’ – If true, install the node forcedly even if
          another node is already installed as the same name

     New in version 1.4.

 -- Method: Sphinx.add_directive (name: str, cls:
          Type[docutils.parsers.rst.Directive], override: bool = False)
          -> None

     Register a Docutils directive.

     Parameters:

        * ‘name’ – The name of the directive

        * ‘cls’ – A directive class

        * ‘override’ – If true, install the directive forcedly even if
          another directive is already installed as the same name

     For example, a custom directive named ‘my-directive’ would be added
     like this:

          from docutils.parsers.rst import Directive, directives

          class MyDirective(Directive):
              has_content = True
              required_arguments = 1
              optional_arguments = 0
              final_argument_whitespace = True
              option_spec = {
                  'class': directives.class_option,
                  'name': directives.unchanged,
              }

              def run(self):
                  ...

          def setup(app):
              app.add_directive('my-directive', MyDirective)

     For more details, see the Docutils docs(1) .

     Changed in version 0.6: Docutils 0.5-style directive classes are
     now supported.

     Deprecated since version 1.8: Docutils 0.4-style (function based)
     directives support is deprecated.

     Changed in version 1.8: Add `override' keyword.

 -- Method: Sphinx.add_role (name: str, role: Any, override: bool =
          False) -> None

     Register a Docutils role.

     Parameters:

        * ‘name’ – The name of role

        * ‘role’ – A role function

        * ‘override’ – If true, install the role forcedly even if
          another role is already installed as the same name

     For more details about role functions, see the Docutils docs(2) .

     Changed in version 1.8: Add `override' keyword.

 -- Method: Sphinx.add_generic_role (name: str, nodeclass: Any,
          override: bool = False) -> None

     Register a generic Docutils role.

     Register a Docutils role that does nothing but wrap its contents in
     the node given by `nodeclass'.

     If `override' is True, the given `nodeclass' is forcedly installed
     even if a role named as `name' is already installed.

     New in version 0.6.

     Changed in version 1.8: Add `override' keyword.

 -- Method: Sphinx.add_domain (domain: Type[sphinx.domains.Domain],
          override: bool = False) -> None

     Register a domain.

     Parameters:

        * ‘domain’ – A domain class

        * ‘override’ – If true, install the domain forcedly even if
          another domain is already installed as the same name

     New in version 1.0.

     Changed in version 1.8: Add `override' keyword.

 -- Method: Sphinx.add_directive_to_domain (domain: str, name: str, cls:
          Type[docutils.parsers.rst.Directive], override: bool = False)
          -> None

     Register a Docutils directive in a domain.

     Like add_directive(), but the directive is added to the
     domain named `domain'.

     Parameters:

        * ‘domain’ – The name of target domain

        * ‘name’ – A name of directive

        * ‘cls’ – A directive class

        * ‘override’ – If true, install the directive forcedly even if
          another directive is already installed as the same name

     New in version 1.0.

     Changed in version 1.8: Add `override' keyword.

 -- Method: Sphinx.add_role_to_domain (domain: str, name: str, role:
          Union[Callable[[str, str, str, int,
          docutils.parsers.rst.states.Inliner, Dict[str, Any],
          List[str]], Tuple[List[docutils.nodes.Node],
          List[docutils.nodes.system_message]]], sphinx.roles.XRefRole],
          override: bool = False) -> None

     Register a Docutils role in a domain.

     Like add_role(), but the role is added to the domain
     named `domain'.

     Parameters:

        * ‘domain’ – The name of the target domain

        * ‘name’ – The name of the role

        * ‘role’ – The role function

        * ‘override’ – If true, install the role forcedly even if
          another role is already installed as the same name

     New in version 1.0.

     Changed in version 1.8: Add `override' keyword.

 -- Method: Sphinx.add_index_to_domain (domain: str, index:
          Type[sphinx.domains.Index], override: bool = False) -> None

     Register a custom index for a domain.

     Add a custom `index' class to the domain named `domain'.

     Parameters:

        * ‘domain’ – The name of the target domain

        * ‘index’ – The index class

        * ‘override’ – If true, install the index forcedly even if
          another index is already installed as the same name

     New in version 1.0.

     Changed in version 1.8: Add `override' keyword.

 -- Method: Sphinx.add_object_type (directivename: str, rolename: str,
          indextemplate: str = '', parse_node: Optional[Callable] =
          None, ref_nodeclass:
          Optional[Type[docutils.nodes.TextElement]] = None, objname:
          str = '', doc_field_types: List = [], override: bool = False)
          -> None

     Register a new object type.

     This method is a very convenient way to add a new object
     type that can be cross-referenced.  It will do this:

        - Create a new directive (called `directivename') for
          documenting an object.  It will automatically add index
          entries if `indextemplate' is nonempty; if given, it must
          contain exactly one instance of ‘%s’.  See the example below
          for how the template will be interpreted.

        - Create a new role (called `rolename') to cross-reference to
          these object descriptions.

        - If you provide `parse_node', it must be a function that takes
          a string and a docutils node, and it must populate the node
          with children parsed from the string.  It must then return the
          name of the item to be used in cross-referencing and index
          entries.  See the ‘conf.py’ file in the source for this
          documentation for an example.

        - The `objname' (if not given, will default to `directivename')
          names the type of object.  It is used when listing objects,
          e.g.  in search results.

     For example, if you have this call in a custom Sphinx extension:

          app.add_object_type('directive', 'dir', 'pair: %s; directive')

     you can use this markup in your documents:

          .. rst:directive:: function

             Document a function.

          <...>

          See also the :rst:dir:`function` directive.

     For the directive, an index entry will be generated as if you had
     prepended

          .. index:: pair: function; directive

     The reference node will be of class ‘literal’ (so it will be
     rendered in a proportional font, as appropriate for code) unless
     you give the `ref_nodeclass' argument, which must be a docutils
     node class.  Most useful are ‘docutils.nodes.emphasis’ or
     ‘docutils.nodes.strong’ – you can also use
     ‘docutils.nodes.generated’ if you want no further text decoration.
     If the text should be treated as literal (e.g.  no smart quote
     replacement), but not have typewriter styling, use
     ‘sphinx.addnodes.literal_emphasis’ or
     ‘sphinx.addnodes.literal_strong’.

     For the role content, you have the same syntactical possibilities
     as for standard Sphinx roles (see Cross-referencing syntax).

     If `override' is True, the given object_type is forcedly installed
     even if an object_type having the same name is already installed.

     Changed in version 1.8: Add `override' keyword.

 -- Method: Sphinx.add_crossref_type (directivename: str, rolename: str,
          indextemplate: str = '', ref_nodeclass:
          Optional[Type[docutils.nodes.TextElement]] = None, objname:
          str = '', override: bool = False) -> None

     Register a new crossref object type.

     This method is very similar to add_object_type() except
     that the directive it generates must be empty, and will produce no
     output.

     That means that you can add semantic targets to your sources, and
     refer to them using custom roles instead of generic ones (like
     ref).  Example call:

          app.add_crossref_type('topic', 'topic', 'single: %s',
                                docutils.nodes.emphasis)

     Example usage:

          .. topic:: application API

          The application API
          -------------------

          Some random text here.

          See also :topic:`this section <application API>`.

     (Of course, the element following the ‘topic’ directive needn’t be
     a section.)

     If `override' is True, the given crossref_type is forcedly
     installed even if a crossref_type having the same name is already
     installed.

     Changed in version 1.8: Add `override' keyword.

 -- Method: Sphinx.add_transform (transform:
          Type[docutils.transforms.Transform]) -> None

     Register a Docutils transform to be applied after parsing.

     Add the standard docutils ‘Transform’ subclass `transform' to the
     list of transforms that are applied after Sphinx parses a reST
     document.

     Parameters: ‘transform’ – A transform class

     priority range categories for Sphinx transforms

     Priority                 Main purpose in Sphinx

     0-99                     Fix invalid nodes by docutils.  Translate a doctree.

     100-299                  Preparation

     300-399                  early

     400-699                  main

     700-799                  Post processing.  Deadline to modify text and referencing.

     800-899                  Collect referencing and referenced nodes.  Domain processing.

     900-999                  Finalize and clean up.

     refs: Transform Priority Range Categories(3)

 -- Method: Sphinx.add_post_transform (transform:
          Type[docutils.transforms.Transform]) -> None

     Register a Docutils transform to be applied before writing.

     Add the standard docutils ‘Transform’ subclass `transform' to the
     list of transforms that are applied before Sphinx writes a
     document.

     Parameters: ‘transform’ – A transform class

 -- Method: Sphinx.add_js_file (filename: str, priority: int = 500,
          loading_method: Optional[str] = None, **kwargs: Any) -> None

     Register a JavaScript file to include in the HTML output.

     Parameters:

        * ‘filename’ – The filename of the JavaScript file.  It must be
          relative to the HTML static path, a full URI with scheme, or
          ‘None’ value.  The ‘None’ value is used to create inline
          ‘<script>’ tag.  See the description of `kwargs' below.

        * ‘priority’ – The priority to determine the order of ‘<script>’
          tag for JavaScript files.  See list of “prority range for
          JavaScript files” below.  If the priority of the JavaScript
          files it the same as others, the JavaScript files will be
          loaded in order of registration.

        * ‘loading_method’ – The loading method of the JavaScript file.
          ‘'async'’ or ‘'defer'’ is allowed.

        * ‘kwargs’ – Extra keyword arguments are included as attributes
          of the ‘<script>’ tag.  A special keyword argument ‘body’ is
          given, its value will be added between the ‘<script>’ tag.

     Example:

          app.add_js_file('example.js')
          # => <script src="_static/example.js"></script>

          app.add_js_file('example.js', loading_method="async")
          # => <script src="_static/example.js" async="async"></script>

          app.add_js_file(None, body="var myVariable = 'foo';")
          # => <script>var myVariable = 'foo';</script>
     priority range for JavaScript files

     Priority                 Main purpose in Sphinx

     200                      default priority for built-in JavaScript files

     500                      default priority for extensions

     800                      default priority for html_js_files.

     A JavaScript file can be added to the specific HTML page when an
     extension calls this method on html-page-context event.

     New in version 0.5.

     Changed in version 1.8: Renamed from ‘app.add_javascript()’.  And
     it allows keyword arguments as attributes of script tag.

     Changed in version 3.5: Take priority argument.  Allow to add a
     JavaScript file to the specific page.

     Changed in version 4.4: Take loading_method argument.  Allow to
     change the loading method of the JavaScript file.

 -- Method: Sphinx.add_css_file (filename: str, priority: int = 500,
          **kwargs: Any) -> None

     Register a stylesheet to include in the HTML output.

     Parameters:

        * ‘filename’ – The filename of the CSS file.  It must be
          relative to the HTML static path, or a full URI with scheme.

        * ‘priority’ – The priority to determine the order of ‘<link>’
          tag for the CSS files.  See list of “prority range for CSS
          files” below.  If the priority of the CSS files it the same as
          others, the CSS files will be loaded in order of registration.

        * ‘kwargs’ – Extra keyword arguments are included as attributes
          of the ‘<link>’ tag.

     Example:

          app.add_css_file('custom.css')
          # => <link rel="stylesheet" href="_static/custom.css" type="text/css" />

          app.add_css_file('print.css', media='print')
          # => <link rel="stylesheet" href="_static/print.css"
          #          type="text/css" media="print" />

          app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
          # => <link rel="alternate stylesheet" href="_static/fancy.css"
          #          type="text/css" title="fancy" />
     priority range for CSS files

     Priority                 Main purpose in Sphinx

     200                      default priority for built-in CSS files

     500                      default priority for extensions

     800                      default priority for html_css_files.

     A CSS file can be added to the specific HTML page when an extension
     calls this method on html-page-context event.

     New in version 1.0.

     Changed in version 1.6: Optional ‘alternate’ and/or ‘title’
     attributes can be supplied with the arguments `alternate' (a
     Boolean) and `title' (a string).  The default is no title and
     `alternate' = ‘False’.  For more information, refer to the
     documentation(4).

     Changed in version 1.8: Renamed from ‘app.add_stylesheet()’.  And
     it allows keyword arguments as attributes of link tag.

     Changed in version 3.5: Take priority argument.  Allow to add a CSS
     file to the specific page.

 -- Method: Sphinx.add_latex_package (packagename: str, options:
          Optional[str] = None, after_hyperref: bool = False) -> None

     Register a package to include in the LaTeX source code.

     Add `packagename' to the list of packages that LaTeX source code
     will include.  If you provide `options', it will be taken to the
     ‘usepackage’ declaration.  If you set `after_hyperref' truthy, the
     package will be loaded after ‘hyperref’ package.

          app.add_latex_package('mypackage')
          # => \usepackage{mypackage}
          app.add_latex_package('mypackage', 'foo,bar')
          # => \usepackage[foo,bar]{mypackage}

     New in version 1.3.

     New in version 3.1: `after_hyperref' option.

 -- Method: Sphinx.add_lexer (alias: str, lexer:
          Type[pygments.lexer.Lexer]) -> None

     Register a new lexer for source code.

     Use `lexer' to highlight code blocks with the given language
     `alias'.

     New in version 0.6.

     Changed in version 2.1: Take a lexer class as an argument.  An
     instance of lexers are still supported until Sphinx-3.x.

 -- Method: Sphinx.add_autodocumenter (cls: Any, override: bool = False)
          -> None

     Register a new documenter class for the autodoc extension.

     Add `cls' as a new documenter class for the
     sphinx.ext.autodoc extension.  It must be a subclass of
     ‘sphinx.ext.autodoc.Documenter’.  This allows auto-documenting new
     types of objects.  See the source of the autodoc module for
     examples on how to subclass ‘Documenter’.

     If `override' is True, the given `cls' is forcedly installed even
     if a documenter having the same name is already installed.

     See Developing autodoc extension for IntEnum.

     New in version 0.6.

     Changed in version 2.2: Add `override' keyword.

 -- Method: Sphinx.add_autodoc_attrgetter (typ: Type, getter:
          Callable[[Any, str, Any], Any]) -> None

     Register a new ‘getattr’-like function for the autodoc extension.

     Add `getter', which must be a function with an interface compatible
     to the getattr()(5) builtin, as the autodoc attribute getter for
     objects that are instances of `typ'.  All cases where autodoc needs
     to get an attribute of a type are then handled by this function
     instead of getattr()(6).

     New in version 0.6.

 -- Method: Sphinx.add_search_language (cls: Any) -> None

     Register a new language for the HTML search index.

     Add `cls', which must be a subclass of
     ‘sphinx.search.SearchLanguage’, as a support language for building
     the HTML full-text search index.  The class must have a `lang'
     attribute that indicates the language it should be used for.  See
     html_search_language.

     New in version 1.1.

 -- Method: Sphinx.add_source_suffix (suffix: str, filetype: str,
          override: bool = False) -> None

     Register a suffix of source files.

     Same as source_suffix.  The users can override this
     using the config setting.

     If `override' is True, the given `suffix' is forcedly installed
     even if the same suffix is already installed.

     New in version 1.8.

 -- Method: Sphinx.add_source_parser (parser:
          Type[docutils.parsers.Parser], override: bool = False) -> None

     Register a parser class.

     If `override' is True, the given `parser' is forcedly installed
     even if a parser for the same suffix is already installed.

     New in version 1.4.

     Changed in version 1.8: `suffix' argument is deprecated.  It only
     accepts `parser' argument.  Use add_source_suffix(). API
     to register suffix instead.

     Changed in version 1.8: Add `override' keyword.

 -- Method: Sphinx.add_env_collector (collector:
          Type[sphinx.environment.collectors.EnvironmentCollector]) ->
          None

     Register an environment collector class.

     Refer to Environment Collector API.

     New in version 1.6.

 -- Method: Sphinx.add_html_theme (name: str, theme_path: str) -> None

     Register a HTML Theme.

     The `name' is a name of theme, and `theme_path' is a full path to
     the theme (refs: Distribute your theme as a Python package).

     New in version 1.6.

 -- Method: Sphinx.add_html_math_renderer (name: str, inline_renderers:
          Optional[Tuple[Callable, Callable]] = None, block_renderers:
          Optional[Tuple[Callable, Callable]] = None) -> None

     Register a math renderer for HTML.

     The `name' is a name of math renderer.  Both `inline_renderers' and
     `block_renderers' are used as visitor functions for the HTML
     writer: the former for inline math node (‘nodes.math’), the latter
     for block math node (‘nodes.math_block’).  Regarding visitor
     functions, see add_node() for details.

     New in version 1.8.

 -- Method: Sphinx.add_message_catalog (catalog: str, locale_dir: str)
          -> None

     Register a message catalog.

     Parameters:

        * ‘catalog’ – The name of the catalog

        * ‘locale_dir’ – The base path of the message catalog

     For more details, see sphinx.locale.get_translation().

     New in version 1.8.

 -- Method: Sphinx.is_parallel_allowed (typ: str) -> bool

     Check whether parallel processing is allowed or not.

     Parameters: ‘typ’ – A type of processing; ‘'read'’ or ‘'write'’.

 -- Exception: sphinx.application.ExtensionError

     All these methods raise this exception if something went wrong with
     the extension API.

   ---------- Footnotes ----------

   (1) https://docutils.sourceforge.io/docs/howto/rst-directives.html

   (2) https://docutils.sourceforge.io/docs/howto/rst-roles.html

   (3)
https://docutils.sourceforge.io/docs/ref/transforms.html#transform-priority-range-categories

   (4) https://mdn.io/Web/CSS/Alternative_style_sheets

   (5) https://docs.python.org/3/library/functions.html#getattr

   (6) https://docs.python.org/3/library/functions.html#getattr

7.4.1.2 Emitting events
.......................

 -- Class: sphinx.application.Sphinx

      -- Method: emit (event: str, *args: Any, allowed_exceptions:
               Tuple[Type[Exception], ...] = ()) -> List

          Emit `event' and pass `arguments' to the callback functions.

          Return the return values of all callbacks as a list.  Do not
          emit core Sphinx events in extensions!

          Parameters:

             * ‘event’ – The name of event that will be emitted

             * ‘args’ – The arguments for the event

             * ‘allowed_exceptions’ – The list of exceptions that are
               allowed in the callbacks

          Changed in version 3.1: Added `allowed_exceptions' to specify
          path-through exceptions

      -- Method: emit_firstresult (event: str, *args: Any,
               allowed_exceptions: Tuple[Type[Exception], ...] = ()) ->
               Any

          Emit `event' and pass `arguments' to the callback functions.

          Return the result of the first callback that doesn’t return
          ‘None’.

          Parameters:

             * ‘event’ – The name of event that will be emitted

             * ‘args’ – The arguments for the event

             * ‘allowed_exceptions’ – The list of exceptions that are
               allowed in the callbacks

          New in version 0.5.

          Changed in version 3.1: Added `allowed_exceptions' to specify
          path-through exceptions

7.4.1.3 Sphinx runtime information
..................................

The application object also provides runtime information as attributes.

 -- Attribute: Sphinx.project

     Target project.  See 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.

7.4.1.4 Sphinx core events
..........................

These events are known to the core.  The arguments shown are given to
the registered event handlers.  Use 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:

     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:

     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.

     New in version 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.

     New in version 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.

     New in version 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.

     New in version 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:`...`’.

     New in version 0.5.

 -- 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.

     New in version 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 ‘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 ‘NoUri’ to prevent other handlers in trying and
     suppress a warning about this cross-reference being unresolved.

     Parameters:

        * ‘env’ – The build environment (‘app.builder.env’).

        * ‘node’ – The ‘pending_xref’ node to be resolved.  Its
          attributes ‘reftype’, ‘reftarget’, ‘modname’ and ‘classname’
          attributes determine the type and target of the reference.

        * ‘contnode’ – The node that carries the text and formatting
          inside the future reference and should be a child of the
          returned reference node.

     New in version 0.5.

 -- Event: warn-missing-reference (app, domain, node)

     Emitted when a cross-reference to an object cannot be resolved even
     after missing-reference.  If the event handler can emit
     warnings for the missing reference, it should return ‘True’.

     New in version 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.

     New in version 1.3.

 -- Event: env-updated (app, env)

     Emitted when the ‘update()’ method of the build environment has
     completed, that is, 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.

     New in version 0.5.

     Changed in version 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.

     New in version 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)’.

     New in version 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
          Sphinx.add_js_file() and
          Sphinx.add_css_file() since v3.5.0.

     New in version 0.4.

     Changed in version 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.

     New in version 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.

     New in version 0.5.

7.4.1.5 Checking the Sphinx version
...................................

Use this to adapt your extension to API changes in Sphinx.

 -- Data: sphinx.version_info = (4, 4, 0, 'final', 0)

     Version info for better programmatic use.

     A tuple of five elements; for Sphinx version 1.2.1 beta 3 this
     would be ‘(1, 2, 1, 'beta', 3)’.  The fourth element can be one of:
     ‘alpha’, ‘beta’, ‘rc’, ‘final’.  ‘final’ always has 0 as the last
     element.

     New in version 1.2: Before version 1.2, check the string
     ‘sphinx.__version__’.

7.4.1.6 The Config object
.........................

 -- Class: sphinx.config.Config (config: Dict[str, Any] = {}, overrides:
          Dict[str, Any] = {})

     Configuration file abstraction.

     The config object makes the values of all config values available
     as attributes.

     It is exposed via the ‘sphinx.application.Application.config’ and
     ‘sphinx.environment.Environment.config’ attributes.  For example,
     to get the value of language, use either
     ‘app.config.language’ or ‘env.config.language’.

7.4.1.7 The template bridge
...........................

 -- Class: sphinx.application.TemplateBridge

     This class defines the interface for a “template bridge”, that is,
     a class that renders templates given a template name and a context.

      -- Method: init (builder: Builder, theme: sphinx.theming.Theme =
               None, dirs: List[str] = None) -> None

          Called by the builder to initialize the template system.

          `builder' is the builder object; you’ll probably want to look
          at the value of ‘builder.config.templates_path’.

          `theme' is a ‘sphinx.theming.Theme’ object or None; in the
          latter case, `dirs' can be list of fixed directories to look
          for templates.

      -- Method: newest_template_mtime () -> float

          Called by the builder to determine if output files are
          outdated because of template changes.  Return the mtime of the
          newest template file that was changed.  The default
          implementation returns ‘0’.

      -- Method: render (template: str, context: Dict) -> None

          Called by the builder to render a template given as a filename
          with a specified context (a Python dictionary).

      -- Method: render_string (template: str, context: Dict) -> str

          Called by the builder to render a template given as a string
          with a specified context (a Python dictionary).

7.4.1.8 Exceptions
..................

 -- Exception: sphinx.errors.SphinxError

     Base class for Sphinx errors.

     This is the base class for “nice” exceptions.  When such an
     exception is raised, Sphinx will abort the build and present the
     exception category and message to the user.

     Extensions are encouraged to derive from this exception for their
     custom errors.

     Exceptions `not' derived from SphinxError are treated
     as unexpected and shown to the user with a part of the traceback
     (and the full traceback saved in a temporary file).

      -- Attribute: category

          Description of the exception “category”, used in converting
          the exception to a string (“category: message”).  Should be
          set accordingly in subclasses.

 -- Exception: sphinx.errors.ConfigError

     Configuration error.

 -- Exception: sphinx.errors.ExtensionError (message: str, orig_exc:
          Optional[Exception] = None, modname: Optional[str] = None)

     Extension error.

 -- Exception: sphinx.errors.ThemeError

     Theme error.

 -- Exception: sphinx.errors.VersionRequirementError

     Incompatible Sphinx version error.

7.4.2 Project API
-----------------

 -- Class: sphinx.project.Project (srcdir: str, source_suffix: Dict[str,
          str])

     A project is the source code set of the Sphinx document(s).

      -- Method: discover (exclude_paths: List[str] = []) -> Set[str]

          Find all document files in the source directory and put them
          in docnames.

      -- Method: doc2path (docname: str, basedir: bool = True) -> str

          Return the filename for the document name.

          If `basedir' is True, return as an absolute path.  Else,
          return as a relative path to the source directory.

      -- Method: path2doc (filename: str) -> Optional[str]

          Return the docname for the filename if the file is a document.

          `filename' should be absolute or relative to the source
          directory.

      -- Method: restore (other: sphinx.project.Project) -> None

          Take over a result of last build.

      -- Attribute: docnames: Set[str(1)]

          The name of documents belongs to this project.

      -- Attribute: source_suffix

          source_suffix.  Same as source_suffix.

      -- Attribute: srcdir

          Source directory.

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/library/stdtypes.html#str

7.4.3 Build environment API
---------------------------

 -- Class: sphinx.environment.BuildEnvironment

     `Attributes'

      -- Attribute: app

          Reference to the Sphinx. (application) object.

      -- Attribute: config

          Reference to the Config object.

      -- Attribute: project

          Target project.  See Project.

      -- Attribute: srcdir

          Source directory.

      -- Attribute: doctreedir

          Directory for storing pickled doctrees.

      -- Attribute: events

          An EventManager object.

      -- Attribute: found_docs

          A set of all existing docnames.

      -- Attribute: metadata

          Dictionary mapping docnames to “metadata” (see File-wide metadata).

      -- Attribute: titles

          Dictionary mapping docnames to the docutils node for their
          main title.

      -- Attribute: docname

          Returns the docname of the document currently being parsed.

     `Utility methods'

      -- Method: doc2path (docname: str, base: bool = True) -> str

          Return the filename for the document name.

          If `base' is True, return absolute path under self.srcdir.  If
          `base' is False, return relative path to self.srcdir.

      -- Method: relfn2path (filename: str, docname: Optional[str] =
               None) -> Tuple[str, str]

          Return paths to a file referenced from a document, relative to
          documentation root and absolute.

          In the input “filename”, absolute filenames are taken as
          relative to the source dir, while relative filenames are
          relative to the dir of the containing document.

      -- Method: note_dependency (filename: str) -> None

          Add `filename' as a dependency of the current document.

          This means that the document will be rebuilt if this file
          changes.

          `filename' should be absolute or relative to the source
          directory.

      -- Method: new_serialno (category: str = '') -> int

          Return a serial number, e.g.  for index entry targets.

          The number is guaranteed to be unique in the current document.

      -- Method: note_reread () -> None

          Add the current document to the list of documents that will
          automatically be re-read at the next build.

7.4.4 Builder API
-----------------

     Todo: Expand this.

 -- Class: sphinx.builders.Builder

     This is the base class for all builders.

     These attributes should be set on builder classes:

      -- Attribute: name = ''

          The builder’s name, for the -b command line option.

      -- Attribute: format = ''

          The builder’s output format, or ‘’ if no document output is
          produced.

      -- Attribute: epilog = ''

          The message emitted upon successful build completion.  This
          can be a printf-style template string with the following keys:
          ‘outdir’, ‘project’

      -- Attribute: allow_parallel = False

          allow parallel write_doc() calls

      -- Attribute: supported_image_types: List[str(1)] = []

          The list of MIME types of image formats supported by the
          builder.  Image files are searched in the order in which they
          appear here.

      -- Attribute: supported_remote_images = False

          The builder supports remote images or not.

      -- Attribute: supported_data_uri_images = False

          The builder supports data URIs or not.

      -- Attribute: default_translator_class:
               Type[docutils.nodes.NodeVisitor] = None

          default translator class for the builder.  This can be
          overridden by ‘app.set_translator()’.

     These methods are predefined and will be called from the
     application:

      -- Method: get_relative_uri (from_: str, to: str, typ:
               Optional[str] = None) -> str

          Return a relative URI between two source filenames.

          May raise environment.NoUri if there’s no way to return a
          sensible URI.

      -- Method: build_all () -> None

          Build all source files.

      -- Method: build_specific (filenames: List[str]) -> None

          Only rebuild as much as needed for changes in the `filenames'.

      -- Method: build_update () -> None

          Only rebuild what was changed or added since last build.

      -- Method: build (docnames: Iterable[str], summary: Optional[str]
               = None, method: str = 'update') -> None

          Main build method.

          First updates the environment, and then calls ‘write()’.

     These methods can be overridden in concrete builder classes:

      -- Method: init () -> None

          Load necessary templates and perform initialization.  The
          default implementation does nothing.

      -- Method: get_outdated_docs () -> Union[str, Iterable[str]]

          Return an iterable of output files that are outdated, or a
          string describing what an update build will build.

          If the builder does not output individual files corresponding
          to source files, return a string here.  If it does, return an
          iterable of those files that need to be written.

      -- Method: get_target_uri (docname: str, typ: Optional[str] =
               None) -> str

          Return the target URI for a document name.

          `typ' can be used to qualify the link characteristic for
          individual builders.

      -- Method: prepare_writing (docnames: Set[str]) -> None

          A place where you can add logic before write_doc().
          is run

      -- Method: write_doc (docname: str, doctree:
               docutils.nodes.document) -> None

          Where you actually write something to the filesystem.

      -- Method: finish () -> None

          Finish the building process.

          The default implementation does nothing.

     `Attributes'

      -- Attribute: events

          An EventManager object.

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/library/stdtypes.html#str

7.4.5 Environment Collector API
-------------------------------

 -- Class: sphinx.environment.collectors.EnvironmentCollector

     An EnvironmentCollector is a specific data collector from each
     document.

     It gathers data and stores BuildEnvironment as a
     database.  Examples of specific data would be images, download
     files, section titles, metadatas, index entries and toctrees, etc.

      -- Method: clear_doc (app: Sphinx, env:
               sphinx.environment.BuildEnvironment, docname: str) ->
               None

          Remove specified data of a document.

          This method is called on the removal of the document.

      -- Method: get_outdated_docs (app: Sphinx, env:
               sphinx.environment.BuildEnvironment, added: Set[str],
               changed: Set[str], removed: Set[str]) -> List[str]

          Return a list of docnames to re-read.

          This methods is called before reading the documents.

      -- Method: get_updated_docs (app: Sphinx, env:
               sphinx.environment.BuildEnvironment) -> List[str]

          Return a list of docnames to re-read.

          This methods is called after reading the whole of documents
          (experimental).

      -- Method: merge_other (app: Sphinx, env:
               sphinx.environment.BuildEnvironment, docnames: Set[str],
               other: sphinx.environment.BuildEnvironment) -> None

          Merge in specified data regarding docnames from a different
          ‘BuildEnvironment’ object which coming from a subprocess in
          parallel builds.

      -- Method: process_doc (app: Sphinx, doctree:
               docutils.nodes.document) -> None

          Process a document and gather specific data from it.

          This method is called after the document is read.

7.4.6 Docutils markup API
-------------------------

This section describes the API for adding ReST markup elements (roles
and directives).

7.4.6.1 Roles
.............

7.4.6.2 Directives
..................

Directives are handled by classes derived from
‘docutils.parsers.rst.Directive’.  They have to be registered by an
extension using Sphinx.add_directive() or
Sphinx.add_directive_to_domain().

 -- Class: docutils.parsers.rst.Directive

     The markup syntax of the new directive is determined by the follow
     five class attributes:

      -- Attribute: required_arguments = 0

          Number of required directive arguments.

      -- Attribute: optional_arguments = 0

          Number of optional arguments after the required arguments.

      -- Attribute: final_argument_whitespace = False

          May the final argument contain whitespace?

      -- Attribute: option_spec = None

          Mapping of option names to validator functions.

          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 ValueError(1) or
          TypeError(2) to indicate failure.

          There are several predefined and possibly useful validators in
          the ‘docutils.parsers.rst.directives’ module.

      -- Attribute: has_content = False

          May the directive have content?

     New directives must implement the 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 ‘ViewList’.

      -- Attribute: lineno

          The absolute line number on which the directive appeared.
          This is not always a useful value; use ‘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
      -- Attribute: state_machine

          The state and state machine which controls the parsing.  Used
          for ‘nested_parse’.

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/library/exceptions.html#ValueError

   (2) https://docs.python.org/3/library/exceptions.html#TypeError

7.4.6.3 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 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.

7.4.6.4 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 Directive.run().
method:

   * ‘self.state.nested_parse’

   * ‘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 since version 1.7: Until Sphinx-1.6,
     ‘sphinx.ext.autodoc.AutodocReporter’ is used for this purpose.  For
     now, 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.

See also
........

Creating directives(1) HOWTO of the Docutils documentation

   ---------- Footnotes ----------

   (1) https://docutils.sourceforge.io/docs/howto/rst-directives.html

7.4.7 Domain API
----------------

 -- Class: sphinx.domains.Domain (env: BuildEnvironment)

     A Domain is meant to be a group of “object” description directives
     for objects of a similar nature, and corresponding roles to create
     references to them.  Examples would be Python modules, classes,
     functions etc., elements of a templating language, Sphinx roles and
     directives, etc.

     Each domain has a separate storage for information about existing
     objects and how to reference them in ‘self.data’, which must be a
     dictionary.  It also must implement several functions that expose
     the object information in a uniform way to parts of Sphinx that
     allow the user to reference or search for objects in a
     domain-agnostic way.

     About ‘self.data’: since all object and cross-referencing
     information is stored on a BuildEnvironment instance, the
     ‘domain.data’ object is also stored in the ‘env.domaindata’ dict
     under the key ‘domain.name’.  Before the build process starts,
     every active domain is instantiated and given the environment
     object; the ‘domaindata’ dict must then either be nonexistent or a
     dictionary whose ‘version’ key is equal to the domain class’
     data_version attribute.  Otherwise, ‘OSError’ is raised and
     the pickled environment is discarded.

      -- Method: add_object_type (name: str, objtype:
               sphinx.domains.ObjType) -> None

          Add an object type.

      -- Method: check_consistency () -> None

          Do consistency checks (`experimental').

      -- Method: clear_doc (docname: str) -> None

          Remove traces of a document in the domain-specific
          inventories.

      -- Method: directive (name: str) -> Optional[Callable]

          Return a directive adapter class that always gives the
          registered directive its full name (‘domain:name’) as
          ‘self.name’.

      -- Method: get_enumerable_node_type (node: docutils.nodes.Node) ->
               Optional[str]

          Get type of enumerable nodes (experimental).

      -- Method: get_full_qualified_name (node: docutils.nodes.Element)
               -> Optional[str]

          Return full qualified name for given node.

      -- Method: get_objects () -> Iterable[Tuple[str, str, str, str,
               str, int]]

          Return an iterable of “object descriptions”.

          Object descriptions are tuples with six items:

          ‘name’

               Fully qualified name.

          ‘dispname’

               Name to display when searching/linking.

          ‘type’

               Object type, a key in ‘self.object_types’.

          ‘docname’

               The document where it is to be found.

          ‘anchor’

               The anchor name for the object.

          ‘priority’

               How “important” the object is (determines placement in
               search results).  One of:

               ‘1’

                    Default priority (placed before full-text matches).

               ‘0’

                    Object is important (placed before default-priority
                    objects).

               ‘2’

                    Object is unimportant (placed after full-text
                    matches).

               ‘-1’

                    Object should not show up in search at all.

      -- Method: get_type_name (type: sphinx.domains.ObjType, primary:
               bool = False) -> str

          Return full name for given ObjType.

      -- Method: merge_domaindata (docnames: List[str], otherdata: Dict)
               -> None

          Merge in data regarding `docnames' from a different domaindata
          inventory (coming from a subprocess in parallel builds).

      -- Method: process_doc (env: BuildEnvironment, docname: str,
               document: docutils.nodes.document) -> None

          Process a document after it is read by the environment.

      -- Method: process_field_xref (pnode:
               sphinx.addnodes.pending_xref) -> None

          Process a pending xref created in a doc field.  For example,
          attach information about the current scope.

      -- Method: resolve_any_xref (env: BuildEnvironment, fromdocname:
               str, builder: Builder, target: str, node:
               sphinx.addnodes.pending_xref, contnode:
               docutils.nodes.Element) -> List[Tuple[str,
               docutils.nodes.Element]]

          Resolve the pending_xref `node' with the given `target'.

          The reference comes from an “any” or similar role, which means
          that we don’t know the type.  Otherwise, the arguments are the
          same as for resolve_xref().

          The method must return a list (potentially empty) of tuples
          ‘('domain:role', newnode)’, where ‘'domain:role'’ is the name
          of a role that could have created the same reference, e.g.
          ‘'py:func'’.  ‘newnode’ is what resolve_xref().
          would return.

          New in version 1.3.

      -- Method: resolve_xref (env: BuildEnvironment, fromdocname: str,
               builder: Builder, typ: str, target: str, node:
               sphinx.addnodes.pending_xref, contnode:
               docutils.nodes.Element) ->
               Optional[docutils.nodes.Element]

          Resolve the pending_xref `node' with the given `typ' and
          `target'.

          This method should return a new node, to replace the xref
          node, containing the `contnode' which is the markup content of
          the cross-reference.

          If no resolution can be found, None can be returned; the xref
          node will then given to the missing-reference.
          event, and if that yields no resolution, replaced by
          `contnode'.

          The method can also raise ‘sphinx.environment.NoUri’ to
          suppress the missing-reference event being
          emitted.

      -- Method: role (name: str) -> Optional[Callable[[str, str, str,
               int, docutils.parsers.rst.states.Inliner, Dict[str, Any],
               List[str]], Tuple[List[docutils.nodes.Node],
               List[docutils.nodes.system_message]]]]

          Return a role adapter function that always gives the
          registered role its full name (‘domain:name’) as the first
          argument.

      -- Method: setup () -> None

          Set up domain object.

      -- Attribute: dangling_warnings: Dict[str(1), str(2)] = {}

          role name -> a warning message if reference is missing

      -- Attribute: data: Dict

          data value

      -- Attribute: data_version = 0

          data version, bump this when the format of ‘self.data’ changes

      -- Attribute: directives: Dict[str(3), Any] = {}

          directive name -> directive class

      -- Attribute: enumerable_nodes: Dict[Type[docutils.nodes.Node],
               Tuple[str(4), Callable]] = {}

          node_class -> (enum_node_type, title_getter)

      -- Attribute: indices: List[Type[see sphinx.domains.Index]]
               = []

          a list of Index subclasses

      -- Attribute: initial_data: Dict = {}

          data value for a fresh environment

      -- Attribute: label = ''

          domain label: longer, more descriptive (used in messages)

      -- Attribute: name = ''

          domain name: should be short, but unique

      -- Attribute: object_types: Dict[str(5), see
               sphinx.domains.ObjType] = {}

          type (usually directive) name -> ObjType instance

      -- Attribute: roles: Dict[str(6), Union[Callable[[str(7), str(8),
               str(9), int(10), docutils.parsers.rst.states.Inliner,
               Dict[str(11), Any], List[str(12)]],
               Tuple[List[docutils.nodes.Node],
               List[docutils.nodes.system_message]]],
               sphinx.roles.XRefRole]] = {}

          role name -> role callable

 -- Class: sphinx.domains.ObjType (lname: str, *roles: Any, **attrs:
          Any)

     An ObjType is the description for a type of object that a domain
     can document.  In the object_types attribute of Domain subclasses,
     object type names are mapped to instances of this class.

     Constructor arguments:

        - `lname': localized name of the type (do not include domain
          name)

        - `roles': all the roles that can refer to an object of this
          type

        - `attrs': object attributes – currently only “searchprio” is
          known, which defines the object’s priority in the full-text
          search index, see Domain.get_objects().

 -- Class: sphinx.domains.Index (domain: sphinx.domains.Domain)

     An Index is the description for a domain-specific index.  To add an
     index to a domain, subclass Index, overriding the three name
     attributes:

        * ‘name’ is an identifier used for generating file names.  It is
          also used for a hyperlink target for the index.  Therefore,
          users can refer the index page using ‘ref’ role and a string
          which is combined domain name and ‘name’ attribute (ex.
          ‘:ref:`py-modindex`’).

        * ‘localname’ is the section title for the index.

        * ‘shortname’ is a short name for the index, for use in the
          relation bar in HTML output.  Can be empty to disable entries
          in the relation bar.

     and providing a generate() method.  Then, add the index
     class to your domain’s ‘indices’ list.  Extensions can add indices
     to existing domains using add_index_to_domain().

     Changed in version 3.0: Index pages can be referred by domain name
     and index name via ref role.

      -- Method: abstract generate (docnames: Optional[Iterable[str]] =
               None) -> Tuple[List[Tuple[str,
               List[sphinx.domains.IndexEntry]]], bool]

          Get entries for the index.

          If ‘docnames’ is given, restrict to entries referring to these
          docnames.

          The return value is a tuple of ‘(content, collapse)’:

          ‘collapse’

               A boolean that determines if sub-entries should start
               collapsed (for output formats that support collapsing
               sub-entries).

          ‘content’:

               A sequence of ‘(letter, entries)’ tuples, where ‘letter’
               is the “heading” for the given ‘entries’, usually the
               starting letter, and ‘entries’ is a sequence of single
               entries.  Each entry is a sequence ‘[name, subtype,
               docname, anchor, extra, qualifier, descr]’.  The items in
               this sequence have the following meaning:

               ‘name’

                    The name of the index entry to be displayed.

               ‘subtype’

                    The sub-entry related type.  One of:

                    ‘0’

                         A normal entry.

                    ‘1’

                         An entry with sub-entries.

                    ‘2’

                         A sub-entry.

               ‘docname’

                    `docname' where the entry is located.

               ‘anchor’

                    Anchor for the entry within ‘docname’

               ‘extra’

                    Extra info for the entry.

               ‘qualifier’

                    Qualifier for the description.

               ‘descr’

                    Description for the entry.

          Qualifier and description are not rendered for some output
          formats such as LaTeX.

 -- Class: sphinx.directives.ObjectDescription (name, arguments,
          options, content, lineno, content_offset, block_text, state,
          state_machine)

     Directive to describe a class, function or similar object.  Not
     used directly, but subclassed (in domain-specific directives) to
     add custom behavior.

      -- Method: add_target_and_index (name: T, sig: str, signode:
               sphinx.addnodes.desc_signature) -> None

          Add cross-reference IDs and entries to self.indexnode, if
          applicable.

          `name' is whatever handle_signature() returned.

      -- Method: after_content () -> None

          Called after parsing content.  Used to reset information about
          the current directive context on the build environment.

      -- Method: before_content () -> None

          Called before parsing content.  Used to set information about
          the current directive context on the build environment.

      -- Method: get_signatures () -> List[str]

          Retrieve the signatures to document from the directive
          arguments.  By default, signatures are given as arguments, one
          per line.

      -- Method: handle_signature (sig: str, signode:
               sphinx.addnodes.desc_signature) -> T

          Parse the signature `sig' into individual nodes and append
          them to `signode'.  If ValueError is raised, parsing is
          aborted and the whole `sig' is put into a single desc_name
          node.

          The return value should be a value that identifies the object.
          It is passed to add_target_and_index() unchanged,
          and otherwise only used to skip duplicates.

      -- Method: run () -> List[docutils.nodes.Node]

          Main directive entry function, called by docutils upon
          encountering the directive.

          This directive is meant to be quite easily subclassable, so it
          delegates to several additional methods.  What it does:

             * find out if called as a domain-specific directive, set
               self.domain

             * create a ‘desc’ node to fit all description inside

             * parse standard options, currently ‘noindex’

             * create an index node if needed as self.indexnode

             * parse all given signatures (as returned by
               self.get_signatures()) using self.handle_signature(),
               which should either return a name or raise ValueError

             * add index entries using self.add_target_and_index()

             * parse the content and handle doc fields in it

      -- Method: transform_content (contentnode:
               sphinx.addnodes.desc_content) -> None

          Called after creating the content through nested parsing, but
          before the ‘object-description-transform’ event is emitted,
          and before the info-fields are transformed.  Can be used to
          manipulate the content.

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/library/stdtypes.html#str

   (2) https://docs.python.org/3/library/stdtypes.html#str

   (3) https://docs.python.org/3/library/stdtypes.html#str

   (4) https://docs.python.org/3/library/stdtypes.html#str

   (5) https://docs.python.org/3/library/stdtypes.html#str

   (6) https://docs.python.org/3/library/stdtypes.html#str

   (7) https://docs.python.org/3/library/stdtypes.html#str

   (8) https://docs.python.org/3/library/stdtypes.html#str

   (9) https://docs.python.org/3/library/stdtypes.html#str

   (10) https://docs.python.org/3/library/functions.html#int

   (11) https://docs.python.org/3/library/stdtypes.html#str

   (12) https://docs.python.org/3/library/stdtypes.html#str

7.4.7.1 Python Domain
.....................

 -- Class: sphinx.domains.python.PythonDomain (env: BuildEnvironment)

     Python language domain.

      -- Attribute: objects

      -- Attribute: modules

      -- Method: note_object (name: str, objtype: str, node_id: str,
               aliased: bool = False, location: Optional[Any] = None) ->
               None

          Note a python object for cross reference.

          New in version 2.1.

      -- Method: note_module (name: str, node_id: str, synopsis: str,
               platform: str, deprecated: bool) -> None

          Note a python module for cross reference.

          New in version 2.1.

7.4.8 Parser API
----------------

The docutils documentation describes(1) parsers as follows:

     The Parser analyzes the input document and creates a node tree
     representation.

In Sphinx, the parser modules works as same as docutils.  The parsers
are registered to Sphinx by extensions using Application APIs; see
Sphinx.add_source_suffix() and 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
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.

 -- Class: sphinx.parsers.Parser

     A base class of source parsers.  The additional parsers should
     inherit this class instead of ‘docutils.parsers.Parser’.  Compared
     with ‘docutils.parsers.Parser’, this class improves accessibility
     to Sphinx APIs.

     The subclasses can access the following objects and functions:

     self.app

          The application object (see sphinx.application.Sphinx)

     self.config

          The config object (see sphinx.config.Config)

     self.env

          The environment object (see
          sphinx.environment.BuildEnvironment)

     self.warn()

          Emit a warning.  (Same as ‘sphinx.application.Sphinx.warn()’)

     self.info()

          Emit an info message.  (Same as
          ‘sphinx.application.Sphinx.info()’)

     Deprecated since version 1.6: ‘warn()’ and ‘info()’ is deprecated.
     Use ‘sphinx.util.logging’ instead.

     Deprecated since version 3.0: parser.app is deprecated.

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/dev/hacking.html#parsing-the-document

7.4.9 Doctree node classes added by Sphinx
------------------------------------------

7.4.9.1 Nodes for domain-specific object descriptions
.....................................................

7.4.9.2 Top-level nodes
.......................

These nodes form the top-most levels of object descriptions.

 -- Class: sphinx.addnodes.desc (rawsource='', *children, **attributes)

     Node for a list of object signatures and a common description of
     them.

     Contains one or more desc_signature nodes and then a
     single desc_content node.

     This node always has two classes:

        - The name of the domain it belongs to, e.g., ‘py’ or ‘cpp’.

        - The name of the object type in the domain, e.g., ‘function’.

 -- Class: sphinx.addnodes.desc_signature (*args: Any, **kwargs: Any)

     Node for a single object signature.

     As default the signature is a single-line signature.  Set
     ‘is_multiline = True’ to describe a multi-line signature.  In that
     case all child nodes must be desc_signature_line nodes.

     This node always has the classes ‘sig’, ‘sig-object’, and the
     domain it belongs to.

 -- Class: sphinx.addnodes.desc_signature_line (rawsource='', text='',
          *children, **attributes)

     Node for a line in a multi-line object signature.

     It should only be used as a child of a desc_signature.
     with ‘is_multiline’ set to ‘True’.  Set ‘add_permalink = True’ for
     the line that should get the permalink.

 -- Class: sphinx.addnodes.desc_content (rawsource='', *children,
          **attributes)

     Node for object description content.

     Must be the last child node in a desc node.

 -- Class: sphinx.addnodes.desc_inline (domain: str, *args: Any,
          **kwargs: Any)

     Node for a signature fragment in inline text.

     This is for example used for roles like cpp;expr.

     This node always has the classes ‘sig’, ‘sig-inline’, and the name
     of the domain it belongs to.

7.4.9.3 Nodes for high-level structure in signatures
....................................................

These nodes occur in in non-multiline desc_signature nodes
and in desc_signature_line nodes.

 -- Class: sphinx.addnodes.desc_name (*args: Any, **kwargs: Any)

     Node for the main object name.

     For example, in the declaration of a Python class
     ‘MyModule.MyClass’, the main name is ‘MyClass’.

     This node always has the class ‘sig-name’.

 -- Class: sphinx.addnodes.desc_addname (*args: Any, **kwargs: Any)

     Node for additional name parts for an object.

     For example, in the declaration of a Python class
     ‘MyModule.MyClass’, the additional name part is ‘MyModule.’.

     This node always has the class ‘sig-prename’.

 -- Class: sphinx.addnodes.desc_type (rawsource='', text='', *children,
          **attributes)

     Node for return types or object type names.

 -- Class: sphinx.addnodes.desc_returns (rawsource='', text='',
          *children, **attributes)

     Node for a “returns” annotation (a la -> in Python).

 -- Class: sphinx.addnodes.desc_parameterlist (rawsource='', text='',
          *children, **attributes)

     Node for a general parameter list.

 -- Class: sphinx.addnodes.desc_parameter (rawsource='', text='',
          *children, **attributes)

     Node for a single parameter.

 -- Class: sphinx.addnodes.desc_optional (rawsource='', text='',
          *children, **attributes)

     Node for marking optional parts of the parameter list.

 -- Class: sphinx.addnodes.desc_annotation (rawsource='', text='',
          *children, **attributes)

     Node for signature annotations (not Python 3-style annotations).

7.4.9.4 New admonition-like constructs
......................................

 -- Class: sphinx.addnodes.versionmodified (rawsource='', text='',
          *children, **attributes)

     Node for version change entries.

     Currently used for “versionadded”, “versionchanged” and
     “deprecated” directives.

 -- Class: sphinx.addnodes.seealso (rawsource='', *children,
          **attributes)

     Custom “see also” admonition.

7.4.9.5 Other paragraph-level nodes
...................................

 -- Class: sphinx.addnodes.compact_paragraph (rawsource='', text='',
          *children, **attributes)

     Node for a compact paragraph (which never makes a <p> node).

7.4.9.6 New inline nodes
........................

 -- Class: sphinx.addnodes.index (rawsource='', text='', *children,
          **attributes)

     Node for index entries.

     This node is created by the ‘index’ directive and has one
     attribute, ‘entries’.  Its value is a list of 5-tuples of
     ‘(entrytype, entryname, target, ignored, key)’.

     `entrytype' is one of “single”, “pair”, “double”, “triple”.

     `key' is categorization characters (usually a single character) for
     general index page.  For the details of this, please see also:
     glossary and issue #2320.

 -- Class: sphinx.addnodes.pending_xref (rawsource='', *children,
          **attributes)

     Node for cross-references that cannot be resolved without complete
     information about all documents.

     These nodes are resolved before writing output, in
     BuildEnvironment.resolve_references.

 -- Class: sphinx.addnodes.pending_xref_condition (rawsource='',
          text='', *children, **attributes)

     Node for cross-references that are used to choose appropriate
     content of the reference by conditions on the resolving phase.

     When the pending_xref node contains one or more
     `pending_xref_condition' nodes, the cross-reference resolver should
     choose the content of the reference using defined conditions in
     ‘condition’ attribute of each pending_xref_condition nodes:

          <pending_xref refdomain="py" reftarget="io.StringIO ...>
              <pending_xref_condition condition="resolved">
                  <literal>
                      StringIO
              <pending_xref_condition condition="*">
                  <literal>
                      io.StringIO

     After the processing of cross-reference resolver, one of the
     content node under pending_xref_condition node is chosen by its
     condition and to be removed all of pending_xref_condition nodes:

          # When resolved the cross-reference successfully
          <reference>
              <literal>
                  StringIO

          # When resolution is failed
          <reference>
              <literal>
                  io.StringIO

          Note: This node is only allowed to be placed under
          pending_xref node.  It is not allows to place it under other
          nodes.  In addition, pending_xref node must contain only
          pending_xref_condition nodes if it contains one or more
          pending_xref_condition nodes.

     The pending_xref_condition node should have `condition' attribute.
     Domains can be store their individual conditions into the attribute
     to filter contents on resolving phase.  As a reserved condition
     name, ‘condition="*"’ is used for the fallback of resolution
     failure.  Additionally, as a recommended condition name,
     ‘condition="resolved"’ is used for the representation of resolstion
     success in the intersphinx module.

     New in version 4.0.

 -- Class: sphinx.addnodes.literal_emphasis (rawsource='', text='',
          *children, **attributes)

     Node that behaves like ‘emphasis’, but further text processors are
     not applied (e.g.  smartypants for HTML output).

 -- Class: sphinx.addnodes.download_reference (rawsource='', text='',
          *children, **attributes)

     Node for download references, similar to pending_xref.

7.4.9.7 Special nodes
.....................

 -- Class: sphinx.addnodes.only (rawsource='', *children, **attributes)

     Node for “only” directives (conditional inclusion based on tags).

 -- Class: sphinx.addnodes.meta (rawsource='', *children, **attributes)

     Node for meta directive – same as docutils’ standard meta node, but
     pickleable.

 -- Class: sphinx.addnodes.highlightlang (rawsource='', *children,
          **attributes)

     Inserted to set the highlight language and line number options for
     subsequent code blocks.

You should not need to generate the nodes below in extensions.

 -- Class: sphinx.addnodes.glossary (rawsource='', *children,
          **attributes)

     Node to insert a glossary.

 -- Class: sphinx.addnodes.toctree (rawsource='', *children,
          **attributes)

     Node for inserting a “TOC tree”.

 -- Class: sphinx.addnodes.start_of_file (rawsource='', *children,
          **attributes)

     Node to mark start of a new file, used in the LaTeX builder only.

 -- Class: sphinx.addnodes.productionlist (rawsource='', *children,
          **attributes)

     Node for grammar production lists.

     Contains ‘production’ nodes.

 -- Class: sphinx.addnodes.production (rawsource='', text='', *children,
          **attributes)

     Node for a single grammar production rule.

7.4.10 Logging API
------------------

 -- Function: sphinx.util.logging.getLogger (name)

     Get logger wrapped by
     sphinx.util.logging.SphinxLoggerAdapter.

     Sphinx logger always uses ‘sphinx.*’ namespace to be independent
     from settings of root logger.  It ensures logging is consistent
     even if a third-party extension or imported application resets
     logger settings.

     Example usage:

          >>> from sphinx.util import logging
          >>> logger = logging.getLogger(__name__)
          >>> logger.info('Hello, this is an extension!')
          Hello, this is an extension!

 -- Class: sphinx.util.logging.SphinxLoggerAdapter
          (logging.LoggerAdapter)

     LoggerAdapter allowing ‘type’ and ‘subtype’ keywords.

      -- Method: error (msg, *args, **kwargs)

      -- Method: critical (msg, *args, **kwargs)

      -- Method: 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 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: log (level, msg, *args, **kwargs)

      -- Method: info (msg, *args, **kwargs)

      -- Method: verbose (msg, *args, **kwargs)

      -- Method: 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
               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"’.

 -- Function: sphinx.util.logging.pending_logging ()

     Context manager to postpone logging all logs temporarily.

     For example:

          >>> with pending_logging():
          >>>     logger.warning('Warning message!')  # not flushed yet
          >>>     some_long_process()
          >>>
          Warning message!  # the warning is flushed here

 -- Function: sphinx.util.logging.pending_warnings ()

     Context manager to postpone logging warnings temporarily.

     Similar to pending_logging().

 -- Function: sphinx.util.logging.prefixed_warnings ()

     Context manager to prepend prefix to all warning log records
     temporarily.

     For example:

          >>> with prefixed_warnings("prefix:"):
          >>>     logger.warning('Warning message!')  # => prefix: Warning message!

     New in version 2.0.

7.4.11 i18n API
---------------

 -- Function: sphinx.locale.init (locale_dirs: List[Optional[str]],
          language: Optional[str], catalog: str = 'sphinx', namespace:
          str = 'general') -> Tuple[gettext.NullTranslations, bool]

     Look for message catalogs in ‘locale_dirs’ and `ensure' that there
     is at least a NullTranslations catalog set in ‘translators’.  If
     called multiple times or if several ‘.mo’ files are found, their
     contents are merged together (thus making ‘init’ reentrant).

 -- Function: sphinx.locale.init_console (locale_dir: str, catalog: str)
          -> Tuple[gettext.NullTranslations, bool]

     Initialize locale for console.

     New in version 1.8.

 -- Function: sphinx.locale.get_translation (catalog: str, namespace:
          str = 'general') -> Callable

     Get a translation function based on the `catalog' and `namespace'.

     The extension can use this API to translate the messages on the
     extension:

          import os
          from sphinx.locale import get_translation

          MESSAGE_CATALOG_NAME = 'myextension'  # name of *.pot, *.po and *.mo files
          _ = get_translation(MESSAGE_CATALOG_NAME)
          text = _('Hello Sphinx!')

          def setup(app):
              package_dir = os.path.abspath(os.path.dirname(__file__))
              locale_dir = os.path.join(package_dir, 'locales')
              app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)

     With this code, sphinx searches a message catalog from
     ‘${package_dir}/locales/${language}/LC_MESSAGES/myextension.mo’.
     The language is used for the searching.

     New in version 1.8.

 -- Function: sphinx.locale._ (message: str, *args: Any) -> str

     Translation function for messages on documentation (menu, labels,
     themes and so on).  This function follows language.
     setting.

 -- Function: sphinx.locale.__ (message: str, *args: Any) -> str

     Translation function for console messages This function follows
     locale setting (‘LC_ALL’, ‘LC_MESSAGES’ and so on).

7.4.11.1 Extension internationalization (‘i18n’) and localization (‘l10n’) using i18n API
.........................................................................................

New in version 1.8.

An extension may naturally come with message translations.  This is
briefly summarized in sphinx.locale.get_translation() help.

In practice, you have to:

  1. 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.

  2. Mark in your extension sources all messages as translatable, via
     sphinx.locale.get_translation() function, usually
     renamed ‘_()’, e.g.:

          from sphinx.locale import get_translation

          MESSAGE_CATALOG_NAME = 'myextension'
          _ = get_translation(MESSAGE_CATALOG_NAME)

          translated_text = _('Hello Sphinx!')

     LiteralBlock: src/__init__.py

  3. Set up your extension to be aware of its dedicated translations:

          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)

     LiteralBlock: src/__init__.py

  4. Generate message catalog template ‘*.pot’ file, usually in
     ‘locale/’ source directory, for example via Babel(1):

          $ pybabel extract --output=src/locale/myextension.pot src/

  5. Create message catalogs (‘*.po’) for each language which your
     extension will provide localization, for example via Babel(2):

          $ pybabel init --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale --locale=fr_FR

  6. Translate message catalogs for each language manually

  7. Compile message catalogs into ‘*.mo’ files, for example via
     Babel(3):

          $ pybabel compile --directory=src/locale --domain=myextension

  8. Ensure that message catalog files are distributed when your package
     will be installed, by adding equivalent line in your extension
     ‘MANIFEST.in’:

          recursive-include src *.pot *.po *.mo

     LiteralBlock: MANIFEST.in

When the messages on your extension has been changed, you need to also
update message catalog template and message catalogs, for example via
Babel(4):

     $ pybabel extract --output=src/locale/myextension.pot src/
     $ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale

   ---------- Footnotes ----------

   (1) https://babel.pocoo.org/

   (2) https://babel.pocoo.org/

   (3) https://babel.pocoo.org/

   (4) https://babel.pocoo.org/

7.4.12 Utilities
----------------

Sphinx provides utility classes and functions to develop extensions.

7.4.12.1 Base classes for components
....................................

These base classes are useful to allow your extensions to obtain Sphinx
components (e.g.  see Config, BuildEnvironment and so
on) easily.

     Note: The subclasses of them might not work with bare docutils
     because they are strongly coupled with Sphinx.

 -- Class: sphinx.transforms.SphinxTransform (document, startnode=None)

     A base class of Transforms.

     Compared with ‘docutils.transforms.Transform’, this class improves
     accessibility to Sphinx APIs.

      -- Property: app: Sphinx.

          Reference to the Sphinx object.

      -- Property: config: sphinx.config.Config.

          Reference to the Config object.

      -- Property: env: BuildEnvironment.

          Reference to the BuildEnvironment object.

 -- Class: sphinx.transforms.post_transforms.SphinxPostTransform
          (document, startnode=None)

     A base class of post-transforms.

     Post transforms are invoked to modify the document to restructure
     it for outputting.  They resolve references, convert images, do
     special transformation for each output formats and so on.  This
     class helps to implement these post transforms.

      -- Method: apply (**kwargs: Any) -> None

          Override to apply the transform to the document tree.

      -- Method: is_supported () -> bool

          Check this transform working for current builder.

      -- Method: run (**kwargs: Any) -> None

          Main method of post transforms.

          Subclasses should override this method instead of ‘apply()’.

 -- Class: sphinx.util.docutils.SphinxDirective (name, arguments,
          options, content, lineno, content_offset, block_text, state,
          state_machine)

     A base class for Sphinx directives.

     This class provides helper methods for Sphinx directives.

          Note: The subclasses of this class might not work with
          docutils.  This class is strongly coupled with Sphinx.

      -- Method: get_location () -> str

          Get current location info for logging.

      -- Method: get_source_info () -> Tuple[str, int]

          Get source and line number.

      -- Method: set_source_info (node: docutils.nodes.Node) -> None

          Set source and line number to the node.

      -- Property: config: Config.

          Reference to the Config object.

      -- Property: env: BuildEnvironment.

          Reference to the BuildEnvironment object.

 -- Class: sphinx.util.docutils.SphinxRole

     A base class for Sphinx roles.

     This class provides helper methods for Sphinx roles.

          Note: The subclasses of this class might not work with
          docutils.  This class is strongly coupled with Sphinx.

      -- Method: get_location () -> str

          Get current location info for logging.

      -- Property: config: Config.

          Reference to the Config object.

      -- Attribute: content: List[str(1)]

          A list of strings, the directive content for customization

      -- Property: env: BuildEnvironment.

          Reference to the BuildEnvironment object.

      -- Attribute: inliner: docutils.parsers.rst.states.Inliner

          The ‘docutils.parsers.rst.states.Inliner’ object.

      -- Attribute: lineno: int(2)

          The line number where the interpreted text begins.

      -- Attribute: name: str(3)

          The role name actually used in the document.

      -- Attribute: options: Dict

          A dictionary of directive options for customization

      -- Attribute: rawtext: str(4)

          A string containing the entire interpreted text input.

      -- Attribute: text: str(5)

          The interpreted text content.

 -- Class: sphinx.util.docutils.ReferenceRole

     A base class for reference roles.

     The reference roles can accept ‘link title <target>’ style as a
     text for the role.  The parsed result; link title and target will
     be stored to ‘self.title’ and ‘self.target’.

      -- Attribute: disabled: bool(6)

          A boolean indicates the reference is disabled.

      -- Attribute: has_explicit_title: bool(7)

          A boolean indicates the role has explicit title or not.

      -- Attribute: target: str(8)

          The link target for the interpreted text.

      -- Attribute: title: str(9)

          The link title for the interpreted text.

 -- Class: sphinx.transforms.post_transforms.images.ImageConverter
          (*args: Any, **kwargs: Any)

     A base class for image converters.

     An image converter is kind of Docutils transform module.  It is
     used to convert image files which are not supported by a builder to
     the appropriate format for that builder.

     For example, see LaTeX builder supports PDF, PNG and JPEG as
     image formats.  However it does not support SVG images.  For such
     case, using image converters allows to embed these unsupported
     images into the document.  One of the image converters; see
     sphinx.ext.imgconverter can convert a SVG image to PNG format
     using Imagemagick internally.

     There are three steps to make your custom image converter:

       1. Make a subclass of ‘ImageConverter’ class

       2. Override ‘conversion_rules’, ‘is_available()’ and ‘convert()’

       3. Register your image converter to Sphinx using
          Sphinx.add_post_transform().

      -- Method: convert (_from: str, _to: str) -> bool

          Convert an image file to the expected format.

          `_from' is a path of the source image file, and `_to' is a
          path of the destination file.

      -- Method: is_available () -> bool

          Return the image converter is available or not.

      -- Attribute: available: Optional[bool(10)] = None

          The converter is available or not.  Will be filled at the
          first call of the build.  The result is shared in the same
          process.

               Todo: This should be refactored not to store the state
               without class variable.

      -- Attribute: conversion_rules: List[Tuple[str(11), str(12)]] = []

          A conversion rules the image converter supports.  It is
          represented as a list of pair of source image format
          (mimetype) and destination one:

               conversion_rules = [
                   ('image/svg+xml', 'image/png'),
                   ('image/gif', 'image/png'),
                   ('application/pdf', 'image/png'),
               ]

   ---------- Footnotes ----------

   (1) https://docs.python.org/3/library/stdtypes.html#str

   (2) https://docs.python.org/3/library/functions.html#int

   (3) https://docs.python.org/3/library/stdtypes.html#str

   (4) https://docs.python.org/3/library/stdtypes.html#str

   (5) https://docs.python.org/3/library/stdtypes.html#str

   (6) https://docs.python.org/3/library/functions.html#bool

   (7) https://docs.python.org/3/library/functions.html#bool

   (8) https://docs.python.org/3/library/stdtypes.html#str

   (9) https://docs.python.org/3/library/stdtypes.html#str

   (10) https://docs.python.org/3/library/functions.html#bool

   (11) https://docs.python.org/3/library/stdtypes.html#str

   (12) https://docs.python.org/3/library/stdtypes.html#str

7.4.12.2 Utility components
...........................

 -- Class: sphinx.events.EventManager (app: Sphinx)

     Event manager for Sphinx.

      -- Method: add (name: str) -> None

          Register a custom Sphinx event.

      -- Method: connect (name: str, callback: Callable, priority: int)
               -> int

          Connect a handler to specific event.

      -- Method: disconnect (listener_id: int) -> None

          Disconnect a handler.

      -- Method: emit (name: str, *args: Any, allowed_exceptions:
               Tuple[Type[Exception], ...] = ()) -> List

          Emit a Sphinx event.

      -- Method: emit_firstresult (name: str, *args: Any,
               allowed_exceptions: Tuple[Type[Exception], ...] = ()) ->
               Any

          Emit a Sphinx event and returns first result.

          This returns the result of the first handler that doesn’t
          return ‘None’.

7.4.13 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
Deprecation policy).

The following is a list of deprecated interfaces.  deprecated APIs

Target                                       Deprecated     (will be)      Alternatives
                                                            Removed

------------------------------------------------------------------------------------------------------------------------

‘sphinx.ext.autodoc.AttributeDocumenter._datadescriptor’4.3 6.0            N/A

‘sphinx.writers.html.HTMLTranslator._fieldlist_row_index’4.36.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.36.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              4.1            6.0            The required argument
‘sphinx.environment.BuildEnvironment’

‘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            TBD            ‘favicon_url’

‘logo’ variable in HTML templates            4.0            TBD            ‘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.06.0         ‘sphinx.ext.autodoc.directive.DocumenterBridge.record_dependencies’

‘sphinx.ext.autodoc.directive.DocumenterBridge.warn()’4.0   6.0            Logging API.

‘sphinx.registry.SphinxComponentRegistry.get_source_input()’4.06.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.55.0 N/A

‘sphinx.builders.linkcheck.CheckExternalLinksBuilder.auth’3.55.0           N/A

‘sphinx.builders.linkcheck.CheckExternalLinksBuilder.broken’3.55.0         N/A

‘sphinx.builders.linkcheck.CheckExternalLinksBuilder.good’3.55.0           N/A

‘sphinx.builders.linkcheck.CheckExternalLinksBuilder.redirected’3.55.0     N/A

‘sphinx.builders.linkcheck.CheckExternalLinksBuilder.rqueue’3.55.0         N/A

‘sphinx.builders.linkcheck.CheckExternalLinksBuilder.to_ignore’3.55.0      N/A

‘sphinx.builders.linkcheck.CheckExternalLinksBuilder.workers’3.55.0        N/A

‘sphinx.builders.linkcheck.CheckExternalLinksBuilder.wqueue’3.55.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.55.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            Logging API.

‘sphinx.ext.autosummary.generate._simple_warn()’3.5         5.0            Logging API.

‘sphinx.writers.html.HTMLTranslator.permalink_text’3.5      5.0            html_permalinks_icon.

‘sphinx.writers.html5.HTML5Translator.permalink_text’3.5    5.0            html_permalinks_icon.

The ‘follow_wrapped’ argument of             3.4            5.0            N/A
‘sphinx.util.inspect.signature()’

The ‘no_docstring’ argument of               3.4            5.0            ‘sphinx.ext.autodoc.Documenter.get_doc()’
‘sphinx.ext.autodoc.Documenter.add_content()’

‘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.35.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                       3.1            5.0            N/A
‘sphinx.ext.autosummary.generate.AutosummaryRenderer’
has been changed to Sphinx object

‘sphinx.ext.autosummary.generate.AutosummaryRenderer’3.1    5.0            N/A
takes an object type as an argument

The ‘ignore’ argument of                     3.1            5.0            N/A
‘sphinx.ext.autodoc.Documenter.get_doc()’

The ‘template_dir’ argument of               3.1            5.0            N/A
‘sphinx.ext.autosummary.generate.AutosummaryRenderer’

The ‘module’ argument of                     3.0            5.0            N/A
‘sphinx.ext.autosummary.generate.find_autosummary_in_docstring()’

The ‘builder’ argument of                    3.1            5.0            N/A
‘sphinx.ext.autosummary.generate.generate_autosummary_docs()’

The ‘template_dir’ argument of               3.1            5.0            N/A
‘sphinx.ext.autosummary.generate.generate_autosummary_docs()’

‘sphinx.ext.autosummary.generate.AutosummaryRenderer.exists()’3.15.0       N/A

The ‘ignore’ argument of                     3.1            5.0            N/A
‘sphinx.util.docstring.prepare_docstring()’

‘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                         2.4            4.0            N/A
‘sphinx.pycode.ModuleAnalyzer()’

‘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.44.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.44.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.24.0          ‘sphinx.domains.math.MathDomain.note_equation()’

The ‘info’ and ‘warn’ arguments of           2.2            4.0            ‘logging.info()’ and ‘logging.warning()’
‘sphinx.ext.autosummary.generate.generate_autosummary_docs()’

‘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.14.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.14.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                       2.0            4.0            N/A
‘autodoc.Documenter.get_doc()’,
‘autodoc.DocstringSignatureMixin.get_doc()’,
‘autodoc.DocstringSignatureMixin._find_signature()’,
and ‘autodoc.ClassDocumenter.get_doc()’

arguments of                                 2.0            4.0            N/A
‘EpubBuilder.build_mimetype()’,
‘EpubBuilder.build_container()’,
‘EpubBuilder.build_content()’,
‘EpubBuilder.build_toc()’ and
‘EpubBuilder.build_epub()’

arguments of                                 2.0            4.0            N/A
‘Epub3Builder.build_navigation_doc()’

‘nodetype’ argument of                       2.0            4.0            N/A
‘sphinx.search.WordCollector.is_meta_keywords()’

‘suffix’ argument of                         2.0            4.0            N/A
‘BuildEnvironment.doc2path()’

string style ‘base’ argument of              2.0            4.0            ‘os.path.join()’
‘BuildEnvironment.doc2path()’

‘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.04.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.04.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       2.0            4.0            ‘IndexBuilder.feed(docname, filename,
overriddent ‘IndexBuilder.feed()’ method.                                  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                   2.0            3.0            N/A
‘sphinx.ext.autodoc.importer._MockModule’

‘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.03.0         N/A

‘sphinx.writers.latex.LaTeXTranslator._make_visit_admonition()’2.03.0      N/A

‘sphinx.writers.latex.LaTeXTranslator.collect_footnotes()’2.04.0           N/A

‘sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()’2.03.0  N/A

‘sphinx.writers.text.TextTranslator._make_depart_admonition()’2.03.0       N/A

‘sphinx.writers.latex.LaTeXTranslator.generate_numfig_format()’2.04.0      N/A

‘highlightlang’                              1.8            4.0            highlight.

‘add_stylesheet()’                           1.8            6.0            add_css_file().

‘add_javascript()’                           1.8            4.0            add_js_file().

See autodoc_default_flags.            1.8            4.0            autodoc_default_options.

‘content’ arguments of                       1.8            3.0            N/A
‘sphinx.util.image.guess_mimetype()’

‘gettext_compact’ arguments of               1.8            3.0            N/A
‘sphinx.util.i18n.find_catalog_source_files()’

‘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            1.8            3.0            N/A
‘sphinx.highlighting.PygmentsBridge’

‘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            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’

‘viewcode_import’ (config value)             1.8            3.0            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.83.0    N/A

‘sphinx.writers.latex.LaTeXTranslator.next_section_ids’1.8  3.0            N/A

‘sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids’1.83.0            N/A

‘sphinx.writers.latex.LaTeXTranslator.restrict_footnote()’1.83.0           N/A

‘sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote()’1.83.0         N/A

‘sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids()’1.83.0          N/A

‘sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids()’1.83.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.83.0            N/A

‘sphinx.writers.html.HTMLTranslator.highlightlangopts()’1.8 3.0            N/A

‘sphinx.writers.html.HTMLTranslator.highlightlinenothreshold()’1.83.0      N/A

‘sphinx.writers.html5.HTMLTranslator.highlightlang()’1.8    3.0            N/A

‘sphinx.writers.html5.HTMLTranslator.highlightlang_base()’1.83.0           N/A

‘sphinx.writers.html5.HTMLTranslator.highlightlangopts()’1.83.0            N/A

‘sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold()’1.83.0     N/A

‘sphinx.writers.latex.LaTeXTranslator.check_latex_elements()’1.83.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   1.8            3.0            ‘Config.read()’
of ‘Config.__init__()’

The value of                                 1.8            3.0            see html_search_options.
See html_search_options.

‘sphinx.versioning.prepare()’                1.8            3.0            ‘sphinx.versioning.UIDTransform’

‘Sphinx.override_domain()’                   1.8            3.0            add_domain().

‘Sphinx.import_object()’                     1.8            3.0            ‘sphinx.util.import_object()’

‘suffix’ argument of                         1.8            3.0            add_source_suffix().
See add_source_parser().

‘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            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()’

See source_parsers.                   1.8            3.0            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            sphinx.locale._().

‘sphinx.locale.lazy_gettext()’               1.8            3.0            sphinx.locale._().

‘sphinx.locale.mygettext()’                  1.8            3.0            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            add_autodocumenter().

‘sphinx.ext.autodoc.AutoDirective._register’ 1.7            2.0            add_autodocumenter().

‘AutoDirective._special_attrgetters’         1.7            2.0            add_autodoc_attrgetter().

‘Sphinx.warn()’, ‘Sphinx.info()’             1.6            2.0            Logging API.

‘BuildEnvironment.set_warnfunc()’            1.6            2.0            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(1)

‘StandaloneHTMLBuilder.css_files’            1.6            2.0            ‘add_stylesheet()’

‘document.settings.gettext_compact’          1.8            1.8            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.

   ---------- Footnotes ----------

   (1) https://pypi.org/project/sphinxcontrib-websupport/

8 Sphinx internals
******************

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.

8.1 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.

8.1.1 Getting help
------------------

The Sphinx community maintains a number of mailing lists and IRC
channels.

Stack Overflow with tag python-sphinx(1)

     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.

   ---------- Footnotes ----------

   (1) https://stackoverflow.com/questions/tagged/python-sphinx

8.1.2 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(1) on GitHub or discuss
it on the sphinx-dev <sphinx-dev@googlegroups.com> 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.

   ---------- Footnotes ----------

   (1) https://github.com/sphinx-doc/sphinx/issues

8.1.3 Writing code
------------------

The Sphinx source code is managed using Git and is hosted on GitHub(1).
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.

   ---------- Footnotes ----------

   (1) https://github.com/sphinx-doc/sphinx

8.1.3.1 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.

  1. Create an account on GitHub.

  2. Fork the main Sphinx repository (sphinx-doc/sphinx(1)) using the
     GitHub interface.

  3. Clone the forked repository to your machine.

          git clone https://github.com/USERNAME/sphinx
          cd sphinx

  4. 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 Sphinx’s release process for
     detail).

  5. 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 .

  6. Create a new working branch.  Choose any name you like.

          git checkout -b feature-xyz

  7. Hack, hack, hack.

     Write your code along with tests that shows that the bug was fixed
     or that the feature works as expected.

  8. Add a bullet point to ‘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.

  9. Push changes in the branch to your forked repository on GitHub:

          git push origin feature-xyz

  10. Submit a pull request from your branch to the respective branch
     (‘master’ or ‘A.x’).

  11. Wait for a core developer to review your changes.

   ---------- Footnotes ----------

   (1) https://github.com/sphinx-doc/sphinx

8.1.3.2 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 ‘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 ‘sphinx/cmd/quickstart.py’ if it’s important enough.

   * Add appropriate unit tests.

Style and type checks can be run using ‘tox’:

     tox -e mypy
     tox -e flake8

8.1.3.3 Unit tests
..................

Sphinx is tested using pytest(1) for Python code and Karma(2) for
JavaScript.

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.6:

          tox -e py36

   * To run unit tests for a specific Python version and turn on
     deprecation warnings on so they’re shown in the test output:

          PYTHONWARNINGS=all tox -e py36

   * Arguments to ‘pytest’ can be passed via ‘tox’, e.g.  in order to
     run a particular test:

          tox -e py36 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'.

New in version 1.8: Sphinx also runs JavaScript tests.

New in version 1.6: ‘sphinx.testing’ is added as a experimental.

Changed in version 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 with 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 ‘tests’ directory.

   ---------- Footnotes ----------

   (1) https://docs.pytest.org/en/latest/

   (2) https://karma-runner.github.io

8.1.4 Writing documentation
---------------------------

     Todo: Add a more extensive documentation contribution guide.

You can build documentation using ‘tox’:

     tox -e docs

8.1.4.1 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 ‘sphinx/locale/sphinx.pot’.

Sphinx uses Babel(1) to extract messages and maintain the catalog files.
It is integrated in ‘setup.py’:

   * Use ‘python setup.py extract_messages’ to update the ‘.pot’
     template.

   * Use ‘python setup.py update_catalog’ to update all existing
     language catalogs in ‘sphinx/locale/*/LC_MESSAGES’ with the current
     messages in the template file.

   * Use ‘python setup.py compile_catalog’ to compile the ‘.po’ files to
     binary ‘.mo’ files and ‘.js’ files.

When an updated ‘.po’ file is submitted, run compile_catalog 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 language in
‘doc/usage/configuration.rst’.

The Sphinx core messages can also be translated on Transifex(2).  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 setup.py update_catalog’ afterwards to make sure
the ‘.po’ file has the canonical Babel formatting.

   ---------- Footnotes ----------

   (1) https://babel.pocoo.org/en/latest/

   (2) https://www.transifex.com/sphinx-doc/sphinx-1/

8.1.5 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 sphinx-build -E option.

   * Use the 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 keep_warnings to ‘True’
     so warnings will be displayed in the generated output.

   * Set the configuration variable nitpicky to ‘True’ so
     that Sphinx will complain about references without a known target.

   * Set the debugging options in the Docutils configuration file(1).

   * JavaScript stemming algorithms in ‘sphinx/search/*.py’ (except
     ‘en.py’) are generated by this modified snowballcode generator(2).
     Generated JSX(3) files are in this repository(4).  You can get the
     resulting JavaScript files using the following command:

          npm install
          node_modules/.bin/grunt build # -> dest/*.global.js

   ---------- Footnotes ----------

   (1) https://docutils.sourceforge.io/docs/user/config.html

   (2) https://github.com/shibukawa/snowball

   (3) https://jsx.github.io/

   (4) https://github.com/shibukawa/snowball-stemmer.jsx

8.2 Sphinx’s release process
============================

8.2.1 Branch Model
------------------

Sphinx project uses following branches for developing that conforms to
Semantic Versioning 2.0.0 (refs: ‘https://semver.org/’ ).

‘master’

     Development for MAJOR version.  All changes including incompatible
     behaviors and public API updates are allowed.

‘A.x’ (ex. ‘2.x’)

     Where ‘A.x’ is the ‘MAJOR.MINOR’ release.  Used to maintain current
     MINOR release.  All changes are allowed if the change preserves
     backwards-compatibility of API and features.

     Only the most recent ‘MAJOR.MINOR’ branch is currently retained.
     When a new MAJOR version is released, the old ‘MAJOR.MINOR’ branch
     will be deleted and replaced by an equivalent tag.

‘A.B.x’ (ex. ‘2.4.x’)

     Where ‘A.B.x’ is the ‘MAJOR.MINOR.PATCH’ release.  Only
     backwards-compatible bug fixes are allowed.  In Sphinx project,
     PATCH version is used for urgent bug fix.

     ‘MAJOR.MINOR.PATCH’ branch will be branched from the ‘v’ prefixed
     release tag (ex.  make 2.3.1 that branched from v2.3.0) when a
     urgent release is needed.  When new PATCH version is released, the
     branch will be deleted and replaced by an equivalent tag (ex.
     v2.3.1).

8.2.2 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 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.

8.2.3 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 PendingDeprecationWarning(1), 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
     DeprecationWarning(2) then, and gets displayed by default.

   * Sphinx 4.0 will remove the feature outright.

   ---------- Footnotes ----------

   (1)
https://docs.python.org/3/library/exceptions.html#PendingDeprecationWarning

   (2)
https://docs.python.org/3/library/exceptions.html#DeprecationWarning

8.2.3.1 Deprecation warnings
............................

Sphinx will enable its ‘RemovedInNextVersionWarning’ warnings by
default, if PYTHONWARNINGS(1) 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 Python docs on configuring
warnings(2)) for more details.

   ---------- Footnotes ----------

   (1)
https://docs.python.org/3/using/cmdline.html#envvar-PYTHONWARNINGS

   (2)
https://docs.python.org/3/library/warnings.html#describing-warning-filters

8.2.4 Release procedures
------------------------

The release procedures are listed in ‘utils/release-checklist’.

8.3 Organization of the Sphinx project
======================================

The guide explains how the Sphinx project is organized.

8.3.1 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.

8.3.1.1 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 ‘CHANGES’
     entry.

8.3.1.2 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 Contributing to Sphinx for more information on how
you can get started.

8.3.2 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 Contributing to Sphinx.

A list of people that have contributed to Sphinx can be found in
Sphinx authors.

8.4 Sphinx Code of Conduct
==========================

Like the technical community as a whole, the Sphinx team and community
is made up of volunteers from all over the world.  Diversity is a
strength, but it can also lead to communication issues and unhappiness.
To that end, we have a few ground rules that we ask people to adhere to.

   * `Be friendly and patient.'

   * `Be welcoming.'  We strive to be a community that welcomes and
     supports people of all backgrounds and identities.  This includes,
     but is not limited to members of any race, ethnicity, culture,
     national origin, colour, immigration status, social and economic
     class, educational level, sex, sexual orientation, gender identity
     and expression, age, size, family status, political belief,
     religion, and mental and physical ability.

   * `Be considerate.'  Your work will be used by other people, and you
     in turn will depend on the work of others.  Any decision you take
     will affect users and colleagues, and you should take those
     consequences into account when making decisions.  Remember that
     we’re a world-wide community, so you might not be communicating in
     someone else’s primary language.

   * `Be respectful.'  Not all of us will agree all the time, but
     disagreement is no excuse for poor behavior and poor manners.  We
     might all experience some frustration now and then, but we cannot
     allow that frustration to turn into a personal attack.  It’s
     important to remember that a community where people feel
     uncomfortable or threatened is not a productive one.  Members of
     the Sphinx community should be respectful when dealing with other
     members as well as with people outside the Sphinx community.

   * `Be careful in the words that you choose.'  We are a community of
     professionals, and we conduct ourselves professionally.  Be kind to
     others.  Do not insult or put down other participants.  Harassment
     and other exclusionary behavior aren’t acceptable.  This includes,
     but is not limited to:

        * Violent threats or language directed against another person.

        * Discriminatory jokes and language.

        * Posting sexually explicit or violent material.

        * Posting (or threatening to post) other people’s personally
          identifying information (“doxing”).

        * Personal insults, especially those using racist or sexist
          terms.

        * Unwelcome sexual attention.

        * Advocating for, or encouraging, any of the above behavior.

        * Repeated harassment of others.  In general, if someone asks
          you to stop, then stop.

   * `When we disagree, try to understand why.'  Disagreements, both
     social and technical, happen all the time and Sphinx is no
     exception.  It is important that we resolve disagreements and
     differing views constructively.  Remember that we’re different.
     Different people have different perspectives on issues.  Being
     unable to understand why someone holds a viewpoint doesn’t mean
     that they’re wrong.  Don’t forget that it is human to err and
     blaming each other doesn’t get us anywhere.  Instead, focus on
     helping to resolve issues and learning from mistakes.

This isn’t an exhaustive list of things that you can’t do.  Rather, take
it in the spirit in which it’s intended - a guide to make it easier to
enrich all of us and the technical communities in which we participate.
This code of conduct applies to all spaces of the Sphinx community.

Attribution
...........

Original text courtesy of the Speak Up!  project:
‘http://web.archive.org/web/20141109123859/http://speakup.io/coc.html’.

8.5 Sphinx authors
==================

Sphinx is written and maintained by Georg Brandl <<georg@python.org>>.

Substantial parts of the templates were written by Armin Ronacher
<<armin.ronacher@active-4.com>>.

Other co-maintainers:

   * Takayuki Shimizukawa <<shimizukawa@gmail.com>>

   * Daniel Neuhäuser <@DasIch>

   * Jon Waltman <@jonwaltman>

   * Rob Ruana <@RobRuana>

   * Robert Lehmann <@lehmannro>

   * Roland Meister <@rolmei>

   * Takeshi Komiya <@tk0miya>

   * Jean-François Burnol <@jfbu>

   * Yoshiki Shibukawa <@shibu_jp>

   * Timotheus Kampik - <@TimKam>

Other contributors, listed alphabetically, are:

   * Alastair Houghton – Apple Help builder

   * Alexander Todorov – inheritance_diagram tests and improvements

   * Andi Albrecht – agogo theme

   * Jakob Lykke Andersen – Rewritten C++ domain

   * Henrique Bastos – SVG support for graphviz extension

   * Daniel Bültmann – todo extension

   * Marco Buttu – doctest extension (pyversion option)

   * Nathan Damon – bugfix in validation of static paths in html
     builders

   * Etienne Desautels – apidoc module

   * Michael Droettboom – inheritance_diagram extension

   * Charles Duffy – original graphviz extension

   * Kevin Dunn – MathJax extension

   * Josip Dzolonga – coverage builder

   * Buck Evan – dummy builder

   * Matthew Fernandez – todo extension fix

   * Hernan Grecco – search improvements

   * Horst Gutmann – internationalization support

   * Martin Hans – autodoc improvements

   * Zac Hatfield-Dodds – doctest reporting improvements, intersphinx
     performance

   * Doug Hellmann – graphviz improvements

   * Tim Hoffmann – theme improvements

   * Antti Kaihola – doctest extension (skipif option)

   * Dave Kuhlman – original LaTeX writer

   * Blaise Laflamme – pyramid theme

   * Chris Lamb – reproducibility fixes

   * Thomas Lamb – linkcheck builder

   * Łukasz Langa – partial support for autodoc

   * Martin Larralde – additional napoleon admonitions

   * Ian Lee – quickstart improvements

   * Robert Lehmann – gettext builder (GSOC project)

   * Dan MacKinlay – metadata fixes

   * Martin Mahner – nature theme

   * Will Maier – directory HTML builder

   * Jacob Mason – websupport library (GSOC project)

   * Glenn Matthews – python domain signature improvements

   * Kurt McKee – documentation updates

   * Roland Meister – epub builder

   * Ezio Melotti – collapsible sidebar JavaScript

   * Bruce Mitchener – Minor epub improvement

   * Daniel Neuhäuser – JavaScript domain, Python 3 support (GSOC)

   * Julien Palard – Colspan and rowspan in text builder

   * Christopher Perkins – autosummary integration

   * Benjamin Peterson – unittests

   * T. Powers – HTML output improvements

   * Jeppe Pihl – literalinclude improvements

   * Rob Ruana – napoleon extension

   * Vince Salvino – JavaScript search improvements

   * Stefan Seefeld – toctree improvements

   * Gregory Szorc – performance improvements

   * Taku Shimizu – epub3 builder

   * Antonio Valentino – qthelp builder, docstring inheritance

   * Filip Vavera – napoleon todo directive

   * Pauli Virtanen – autodoc improvements, autosummary extension

   * Eric N. Vander Weele – autodoc improvements

   * Stefan van der Walt – autosummary extension

   * Thomas Waldmann – apidoc module fixes

   * John Waltman – Texinfo builder

   * Barry Warsaw – setup command improvements

   * Sebastian Wiesner – image handling, distutils support

   * Michael Wilson – Intersphinx HTTP basic auth support

   * Matthew Woodcraft – text output improvements

   * Joel Wurtz – cellspanning support in LaTeX

   * Hong Xu – svg support in imgmath extension and various bug fixes

   * Stephen Finucane – setup command improvements and documentation

   * Daniel Pizetta – inheritance diagram improvements

   * KINEBUCHI Tomohiko – typing Sphinx as well as docutils

   * Adrián Chaves (Gallaecio) – coverage builder improvements

   * Lars Hupfeldt Nielsen - OpenSSL FIPS mode md5 bug fix

Many thanks for all contributions!

There are also a few modules or functions incorporated from other
authors and projects:

   * sphinx.util.jsdump uses the basestring encoding from simplejson,
     written by Bob Ippolito, released under the MIT license

   * sphinx.util.stemmer was written by Vivake Gupta, placed in the
     Public Domain

9 Sphinx FAQ
************

This is a list of Frequently Asked Questions about Sphinx.  Feel free to
suggest new entries!

9.1 How do I…
=============

… create PDF files without LaTeX?

     rinohtype(1) provides a PDF builder that can be used as a drop-in
     replacement for the LaTeX builder.

… get section numbers?

     They are automatic in LaTeX output; for HTML, give a ‘:numbered:’
     option to the toctree directive where you want to start
     numbering.

… customize the look of the built HTML files?

     Use themes, see HTML Theming.

… add global substitutions or includes?

     Add them in the rst_prolog or rst_epilog.
     config value.

… display the whole TOC tree in the sidebar?

     Use the toctree callable in a custom layout template,
     probably in the ‘sidebartoc’ block.

… write my own extension?

     See the Extension tutorials.

… convert from my existing docs using MoinMoin markup?

     The easiest way is to convert to xhtml, then convert xhtml to
     reST(2). 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(3) repository.

   ---------- Footnotes ----------

   (1) https://github.com/brechtm/rinohtype

   (2) https://docutils.sourceforge.io/sandbox/xhtml2rest/xhtml2rest.py

   (3) https://bitbucket.org/birkenfeld/sphinx-contrib/

9.2 Using Sphinx with…
======================

Read the Docs

     Read the Docs(1) 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(2) guide is a good place
     to start.

Epydoc

     There’s a third-party extension providing an api role(3) which
     refers to Epydoc’s API docs for a given identifier.

Doxygen

     Michael Jones is developing a reST/Sphinx bridge to doxygen called
     breathe(4).

SCons

     Glenn Hutchings has written a SCons build script to build Sphinx
     documentation; it is hosted here:
     ‘https://bitbucket.org/zondo/sphinx-scons’

PyPI

     Jannis Leidel wrote a setuptools command(5) that automatically
     uploads Sphinx documentation to the PyPI package documentation area
     at ‘https://pythonhosted.org/’.

GitHub Pages

     Please add 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 ‘https://bitbucket.org/kevindunn/sphinx-wiki/wiki/Home’, a
     project by Kevin Dunn.

Google Analytics

     You can use a custom ‘layout.html’ template, like this:

          {% 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:

               <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 html_sidebars.
          configuration value.

   ---------- Footnotes ----------

   (1) https://readthedocs.org

   (2)
https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html

   (3)
https://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py

   (4) https://github.com/michaeljones/breathe/tree/master

   (5) https://pypi.org/project/Sphinx-PyPI-upload/

9.3 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(1) is a text processing system for converting plain text
documentation into other, richer formats.  As noted in the docutils
documentation(2), 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(3) - though other, `out-of-tree' parsers have
been implemented including Sphinx’s Markdown parser.  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(4), 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 Builders.  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.

   ---------- Footnotes ----------

   (1) https://docutils.sourceforge.io/

   (2) https://docutils.sourceforge.io/docs/dev/hacking.html

   (3) https://docutils.sourceforge.io/rst.html

   (4) https://docutils.sourceforge.io/docs/user/tools.html

9.4 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(1) 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(2), Calibre(3), FBreader(4)
     (although it does not render the CSS), and Bookworm(5).  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 ‘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
     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 html_static_path.
     directory and reference it with its full path in the
     epub_cover config option.

   * kindlegen(6) command can convert from epub3 resulting file to
     ‘.mobi’ file for Kindle.  You can get ‘yourdoc.mobi’ under
     ‘_build/epub’ after the following command:

          $ make epub
          $ kindlegen _build/epub/yourdoc.epub

     The kindlegen command doesn’t accept documents that have section
     titles surrounding ‘toctree’ directive:

          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:

          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.

   ---------- Footnotes ----------

   (1) https://fontforge.github.io/

   (2) https://github.com/IDPF/epubcheck

   (3) https://calibre-ebook.com/

   (4) https://fbreader.org/

   (5) https://www.oreilly.com/bookworm/index.html

   (6) https://www.amazon.com/gp/feature.html?docId=1000765211

9.5 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).

9.5.1 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:

     Displaying Links.

One can disable generation of the inline references in a document with
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’.

     (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)))))

9.5.2 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

   - Inline markup

     The standard formatting for ‘*strong*’ and ‘_emphasis_’ can result
     in ambiguous output when used to markup parameter names and other
     values.  Since this is a fairly common practice, the default
     formatting has been changed so that ‘emphasis’ and ‘strong’ are now
     displayed like ‘`literal'’s.

     The standard formatting can be re-enabled by adding the following
     to your ‘conf.py’:

          texinfo_elements = {'preamble': """
          @definfoenclose strong,*,*
          @definfoenclose emph,_,_
          """}

10 Glossary
***********

builder

     A class (inheriting from 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 Builders for an overview over Sphinx’s built-in
     builders.

configuration directory

     The directory containing ‘conf.py’.  By default, this is the same
     as the 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:

          .. directivename:: argument ...
             :option: value

             Content of the directive.

     See 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 source_suffix) and different OSes have different
     path separators, Sphinx abstracts them: `document names' are always
     relative to the 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
     directive.s and role.s) to describe and link to
     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 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 role, directive or other aspect of
     Sphinx that allows users to modify any aspect of the build process
     within Sphinx.

     For more information, refer to Extensions.

master document

     The document that contains the root toctree directive.

root document

     Same as master document.

object

     The basic building block of Sphinx documentation.  Every “object
     directive” (e.g.  ‘function’ or 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 Deprecation Warnings.

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 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.

11 Changelog
************

11.1 Release 4.4.0 (released Jan 17, 2022)
==========================================

11.1.1 Dependencies
-------------------

   * #10007: Use ‘importlib_metadata’ for python-3.9 or older

   * #10007: Drop ‘setuptools’

11.1.2 Features added
---------------------

   * #9075: autodoc: Add a config variable
     autodoc_typehints_format to suppress the leading module names
     of typehints of function signatures (ex.  ‘io.StringIO’ ->
     ‘StringIO’)

   * #9831: Autosummary now documents only the members specified in a
     module’s ‘__all__’ attribute if
     autosummary_ignore_module_all is set to ‘False’.  The default
     behaviour is unchanged.  Autogen also now supports this behavior
     with the ‘--respect-module-all’ switch.

   * #9555: autosummary: Improve error messages on failure to load
     target object

   * #9800: extlinks: Emit warning if a hardcoded link is replaceable by
     an extlink, suggesting a replacement.

   * #9961: html: Support nested <kbd> HTML elements in other HTML
     builders

   * #10013: html: Allow to change the loading method of JS via
     ‘loading_method’ parameter for ‘Sphinx.add_js_file()’

   * #9551: html search: “Hide Search Matches” link removes “highlight”
     parameter from URL

   * #9815: html theme: Wrap sidebar components in div to allow
     customizing their layout via CSS

   * #9827: i18n: Sort items in glossary by translated terms

   * #9899: py domain: Allows to specify cross-reference specifier (‘.’
     and ‘~’) as ‘:type:’ option

   * #9894: linkcheck: add option ‘linkcheck_exclude_documents’ to
     disable link checking in matched documents.

   * #9793: sphinx-build: Allow to use the parallel build feature in
     macOS on macOS and Python3.8+

   * #10055: sphinx-build: Create directories when ‘-w’ option given

   * #9993: std domain: Allow to refer an inline target (ex.  ‘_`target
     name`’) via ref role

   * #9981: std domain: Strip value part of the option directive from
     general index

   * #9391: texinfo: improve variable in ‘samp’ role

   * #9578: texinfo: Add texinfo_cross_references to disable
     cross references for readability with standalone readers

   * #9822 (and #9062), add new Intersphinx role external.
     for explict lookup in the external projects, without resolving to
     the local project.

11.1.3 Bugs fixed
-----------------

   * #9866: autodoc: doccomment for the imported class was ignored

   * #9883: autodoc: doccomment for the alias to mocked object was
     ignored

   * #9908: autodoc: debug message is shown on building document using
     NewTypes with Python 3.10

   * #9968: autodoc: instance variables are not shown if __init__ method
     has position-only-arguments

   * #9194: autodoc: types under the “typing” module are not hyperlinked

   * #10009: autodoc: Crashes if target object raises an error on
     getting docstring

   * #10058: autosummary: Imported members are not shown when
     ‘autodoc_class_signature = 'separated'’

   * #9947: i18n: topic directive having a bullet list can’t be
     translatable

   * #9878: mathjax: MathJax configuration is placed after loading
     MathJax itself

   * #9932: napoleon: empty “returns” section is generated even if no
     description

   * #9857: Generated RFC links use outdated base url

   * #9909: HTML, prevent line-wrapping in literal text.

   * #10061: html theme: Configuration values added by themes are not be
     able to override from conf.py

   * #10073: imgconverter: Unnecessary availablity check is called for
     “data” URIs

   * #9925: LaTeX: prohibit also with ‘'xelatex'’ line splitting at
     dashes of inline and parsed literals

   * #9944: LaTeX: extra vertical whitespace for some nested
     declarations

   * #9940: LaTeX: Multi-function declaration in Python domain has
     cramped vertical spacing in latexpdf output

   * #10015: py domain: types under the “typing” module are not
     hyperlinked defined at info-field-list

   * #9390: texinfo: Do not emit labels inside footnotes

   * #9413: xml: Invalid XML was generated when cross referencing python
     objects

   * #9979: Error level messages were displayed as warning messages

   * #10057: Failed to scan documents if the project is placed onto the
     root directory

   * #9636: code-block: ‘:dedent:’ without argument did strip newlines

11.2 Release 4.3.2 (released Dec 19, 2021)
==========================================

11.2.1 Bugs fixed
-----------------

   * #9917: C and C++, parse fundamental types no matter the order of
     simple type specifiers.

11.3 Release 4.3.1 (released Nov 28, 2021)
==========================================

11.3.1 Features added
---------------------

   * #9864: mathjax: Support chnaging the loading method of MathJax to
     “defer” via mathjax_options.

11.3.2 Bugs fixed
-----------------

   * #9838: autodoc: AttributeError is raised on building document for
     functions decorated by functools.lru_cache

   * #9879: autodoc: AttributeError is raised on building document for
     an object having invalid __doc__ attribute

   * #9844: autodoc: Failed to process a function wrapped with
     functools.partial if autodoc_preserve_defaults enabled

   * #9872: html: Class namespace collision between autodoc signatures
     and docutils-0.17

   * #9868: imgmath: Crashed if the dvisvgm command failed to convert
     equation

   * #9864: mathjax: Failed to render equations via MathJax v2.  The
     loading method of MathJax is back to “async” method again

11.4 Release 4.3.0 (released Nov 11, 2021)
==========================================

11.4.1 Dependencies
-------------------

   * Support Python 3.10

11.4.2 Incompatible changes
---------------------------

   * #9649: ‘searchindex.js’: the embedded data has changed format to
     allow objects with the same name in different domains.

   * #9672: The rendering of Python domain declarations is implemented
     with more docutils nodes to allow better CSS styling.  It may break
     existing styling.

   * #9672: the signature of
     ‘domains.py.PyObject.get_signature_prefix()’ has changed to return
     a list of nodes instead of a plain string.

   * #9695: ‘domains.js.JSObject.display_prefix’ has been changed into a
     method ‘get_display_prefix’ which now returns a list of nodes
     instead of a plain string.

   * #9695: The rendering of Javascript domain declarations is
     implemented with more docutils nodes to allow better CSS styling.
     It may break existing styling.

   * #9450: mathjax: Load MathJax via “defer” strategy

11.4.3 Deprecated
-----------------

   * ‘sphinx.ext.autodoc.AttributeDocumenter._datadescriptor’

   * ‘sphinx.writers.html.HTMLTranslator._fieldlist_row_index’

   * ‘sphinx.writers.html.HTMLTranslator._table_row_index’

   * ‘sphinx.writers.html5.HTML5Translator._fieldlist_row_index’

   * ‘sphinx.writers.html5.HTML5Translator._table_row_index’

11.4.4 Features added
---------------------

   * #9639: autodoc: Support asynchronous generator functions

   * #9664: autodoc: ‘autodoc-process-bases’ supports to inject reST
     snippet as a base class

   * #9691: C, added new info-field ‘retval’ for c;function.
     and c;macro.

   * C++, added new info-field ‘retval’ for cpp;function.

   * #9618: i18n: Add gettext_allow_fuzzy_translations to
     allow “fuzzy” messages for translation

   * #9672: More CSS classes on Python domain descriptions

   * #9695: More CSS classes on Javascript domain descriptions

   * #9683: Revert the removal of ‘add_stylesheet()’ API. It will be
     kept until the Sphinx-6.0 release

   * #2068, add intersphinx_disabled_reftypes for disabling
     interphinx resolution of cross-references that do not have an
     explicit inventory specification.  Specific types of
     cross-references can be disabled, e.g., ‘std:doc’ or all
     cross-references in a specific domain, e.g., ‘std:*’.

   * #9623: Allow to suppress “toctree contains reference to excluded
     document” warnings using suppress_warnings.

11.4.5 Bugs fixed
-----------------

   * #9630: autodoc: Failed to build cross references if
     primary_domain is not ‘py’

   * #9644: autodoc: Crashed on getting source info from problematic
     object

   * #9655: autodoc: mocked object having doc comment is warned
     unexpectedly

   * #9651: autodoc: return type field is not generated even if
     autodoc_typehints_description_target is set to “documented”
     when its info-field-list contains ‘:returns:’ field

   * #9657: autodoc: The base class for a subclass of mocked object is
     incorrect

   * #9607: autodoc: Incorrect base class detection for the subclasses
     of the generic class

   * #9755: autodoc: memory addresses are shown for aliases

   * #9752: autodoc: Failed to detect type annotation for slots
     attribute

   * #9756: autodoc: Crashed if classmethod does not have __func__
     attribute

   * #9757: autodoc: autodoc_inherit_docstrings does not
     effect to overridden classmethods

   * #9781: autodoc: autodoc_preserve_defaults does not
     support hexadecimal numeric

   * #9630: autosummary: Failed to build summary table if
     primary_domain is not ‘py’

   * #9670: html: Fix download file with special characters

   * #9710: html: Wrong styles for even/odd rows in nested tables

   * #9763: html: parameter name and its type annotation are not
     separated in HTML

   * #9649: HTML search: when objects have the same name but in
     different domains, return all of them as result instead of just
     one.

   * #7634: intersphinx: references on the file in sub directory are
     broken

   * #9737: LaTeX: hlist is rendered as a list containing “aggedright”
     text

   * #9678: linkcheck: file extension was shown twice in warnings

   * #9697: py domain: An index entry with parens was registered for
     ‘py:method’ directive with ‘:property:’ option

   * #9775: py domain: Literal typehint was converted to a cross
     reference when ‘autodoc_typehints='description'’

   * #9708: needs_extension failed to check double-digit version
     correctly

   * #9688: Fix ‘code`’ does not recognize ‘:class:’ option

   * #9733: Fix for logging handler flushing warnings in the middle of
     the docs build

   * #9656: Fix warnings without subtype being incorrectly suppressed

   * Intersphinx, for unresolved references with an explicit inventory,
     e.g., ‘proj:myFunc’, leave the inventory prefix in the unresolved
     text.

11.5 Release 4.2.0 (released Sep 12, 2021)
==========================================

11.5.1 Features added
---------------------

   * #9445: autodoc: Support class properties

   * #9479: autodoc: Emit a warning if target is a mocked object

   * #9560: autodoc: Allow to refer NewType instances with module name
     in Python 3.10 or above

   * #9447: html theme: Expose the version of Sphinx in the form of
     tuple as a template variable ‘sphinx_version_tuple’

   * #9594: manpage: Suppress the title of man page if description is
     empty

   * #9445: py domain: ‘:py:property:’ directive supports
     ‘:classmethod:’ option to describe the class property

   * #9524: test: SphinxTestApp can take ‘builddir’ as an argument

   * #9535: C and C++, support more fundamental types, including GNU
     extensions.

11.5.2 Bugs fixed
-----------------

   * #9608: apidoc: apidoc does not generate a module definition for
     implicit namespace package

   * #9504: autodoc: generate incorrect reference to the parent class if
     the target class inherites the class having ‘_name’ attribute

   * #9537, #9589: autodoc: Some objects under ‘typing’ module are not
     displayed well with the HEAD of 3.10

   * #9487: autodoc: typehint for cached_property is not shown

   * #9509: autodoc: AttributeError is raised on failed resolving
     typehints

   * #9518: autodoc: autodoc_docstring_signature does not effect to
     ‘__init__()’ and ‘__new__()’

   * #9522: autodoc: PEP 585 style typehints having arguments (ex.
     ‘list[int]’) are not displayed well

   * #9481: autosummary: some warnings contain non-existing filenames

   * #9568: autosummary: summarise overlined sectioned headings
     correctly

   * #9600: autosummary: Type annotations which contain commas in
     autosummary table are not removed completely

   * #9481: c domain: some warnings contain non-existing filenames

   * #9481: cpp domain: some warnings contain non-existing filenames

   * #9456: html search: abbreation marks are inserted to the search
     result if failed to fetch the content of the page

   * #9617: html search: The JS requirement warning is shown if browser
     is slow

   * #9267: html theme: CSS and JS files added by theme were loaded
     twice

   * #9585: py domain: ‘:type:’ option for py;property.
     directive does not create a hyperlink

   * #9576: py domain: Literal typehint was converted to a cross
     reference

   * #9535 comment: C++, fix parsing of defaulted function parameters
     that are function pointers.

   * #9564: smartquotes: don’t adjust typography for text with
     language-highlighted ‘:code:’ role.

   * #9512: sphinx-build: crashed with the HEAD of Python 3.10

11.6 Release 4.1.2 (released Jul 27, 2021)
==========================================

11.6.1 Incompatible changes
---------------------------

   * #9435: linkcheck: Disable checking automatically generated anchors
     on github.com (ex.  anchors in reST/Markdown documents)

11.6.2 Bugs fixed
-----------------

   * #9489: autodoc: Custom types using ‘typing.NewType’ are not
     displayed well with the HEAD of 3.10

   * #9490: autodoc: Some objects under ‘typing’ module are not
     displayed well with the HEAD of 3.10

   * #9436, #9471: autodoc: crashed if ‘autodoc_class_signature =
     "separated"’

   * #9456: html search: html_copy_source can’t control the search
     summaries

   * #9500: LaTeX: Failed to build Japanese document on Windows

   * #9435: linkcheck: Failed to check anchors in github.com

11.7 Release 4.1.1 (released Jul 15, 2021)
==========================================

11.7.1 Dependencies
-------------------

   * #9434: sphinxcontrib-htmlhelp-2.0.0 or above

   * #9434: sphinxcontrib-serializinghtml-1.1.5 or above

11.7.2 Bugs fixed
-----------------

   * #9438: html: HTML logo or Favicon specified as file not being found
     on output

11.8 Release 4.1.0 (released Jul 12, 2021)
==========================================

11.8.1 Dependencies
-------------------

   * Support jinja2-3.0

11.8.2 Deprecated
-----------------

   * The ‘app’ argument of ‘sphinx.environment.BuildEnvironment’ becomes
     required

   * ‘sphinx.application.Sphinx.html_theme’

   * ‘sphinx.ext.autosummary._app’

   * ‘sphinx.util.docstrings.extract_metadata()’

11.8.3 Features added
---------------------

   * #8107: autodoc: Add ‘class-doc-from’ option to autoclass
     directive to control the content of the specific class like
     autoclass_content.

   * #8588: autodoc: autodoc_type_aliases now supports
     dotted name.  It allows you to define an alias for a class with
     module name like ‘foo.bar.BazClass’

   * #9175: autodoc: Special member is not documented in the module

   * #9195: autodoc: The arguments of ‘typing.Literal’ are wrongly
     rendered

   * #9185: autodoc: autodoc_typehints allows ‘'both'’
     setting to allow typehints to be included both in the signature and
     description

   * #4257: autodoc: Add autodoc_class_signature to separate
     the class entry and the definition of ‘__init__()’ method

   * #8061, #9218: autodoc: Support variable comment for alias classes

   * #3014: autodoc: Add autodoc-process-bases to modify the
     base classes of the class definitions

   * #9272: autodoc: Render enum values for the default argument value
     better

   * #9384: autodoc: ‘autodoc_typehints='none'’ now erases typehints for
     variables, attributes and properties

   * #3257: autosummary: Support instance attributes for classes

   * #9358: html: Add “heading” role to the toctree items

   * #9225: html: Add span tag to the return typehint of method/function

   * #9129: html search: Show search summaries when html_copy_source =
     False

   * #9307: html search: Prevent corrections and completions in search
     field

   * #9120: html theme: Eliminate prompt characters of code-block from
     copyable text

   * #9176: i18n: Emit a debug message if message catalog file not found
     under locale_dirs.

   * #9414: LaTeX: Add xeCJKVerbAddon to default fvset config for
     Chinese documents

   * #9016: linkcheck: Support checking anchors on github.com

   * #9016: linkcheck: Add a new event linkcheck-process-uri.
     to modify URIs before checking hyperlinks

   * #6525: linkcheck: Add linkcheck_allowed_redirects to
     mark hyperlinks that are redirected to expected URLs as “working”

   * #1874: py domain: Support union types using ‘|’ in info-field-list

   * #9268: py domain: python_use_unqualified_type_names.
     supports type field in info-field-list

   * #9097: Optimize the parallel build

   * #9131: Add nitpick_ignore_regex to ignore nitpicky
     warnings using regular expressions

   * #9174: Add ‘Sphinx.set_html_assets_policy’ to tell extensions to
     include HTML assets in all the pages.  Extensions can check this
     via ‘Sphinx.registry.html_assets_policy’

   * C++, add support for

        - ‘inline’ variables,

        - ‘consteval’ functions,

        - ‘constinit’ variables,

        - ‘char8_t’,

        - ‘explicit(<constant expression>)’ specifier,

        - digit separators in literals, and

        - constraints in placeholder type specifiers, aka.  adjective
          syntax (e.g., ‘Sortable auto &v’).

   * C, add support for digit separators in literals.

   * #9166: LaTeX: support containers in LaTeX output

11.8.4 Bugs fixed
-----------------

   * #8872: autodoc: stacked singledispatches are wrongly rendered

   * #8597: autodoc: a docsting having metadata only should be treated
     as undocumented

   * #9185: autodoc: typehints for overloaded functions and methods are
     inaccurate

   * #9250: autodoc: The inherited method not having docstring is
     wrongly parsed

   * #9283: autodoc: autoattribute directive failed to generate document
     for an attribute not having any comment

   * #9364: autodoc: single element tuple on the default argument value
     is wrongly rendered

   * #9362: autodoc: AttributeError is raised on processing a subclass
     of Tuple[()]

   * #9404: autodoc: TypeError is raised on processing dict-like object
     (not a class) via autoclass directive

   * #9317: html: Pushing left key causes visiting the next page at the
     first page

   * #9381: html: URL for html_favicon and html_log does not work

   * #9270: html theme : pyramid theme generates incorrect logo links

   * #9217: manpage: The name of manpage directory that is generated by
     man_make_section_directory is not correct

   * #9350: manpage: Fix font isn’t reset after keyword at the top of
     samp role

   * #9306: Linkcheck reports broken link when remote server closes the
     connection on HEAD request

   * #9280: py domain: “exceptions” module is not displayed

   * #9418: py domain: a Callable annotation with no parameters (e.g.
     ‘Callable[[], None])’ will be rendered with a bracket missing
     (‘Callable[], None]’)

   * #9319: quickstart: Make sphinx-quickstart exit when conf.py already
     exists

   * #9387: xml: XML Builder ignores custom visitors

   * #9224: ‘:param:’ and ‘:type:’ fields does not support a type
     containing whitespace (ex.  ‘Dict[str, str]’)

   * #8945: when transforming typed fields, call the specified role
     instead of making an single xref.  For C and C++, use the ‘expr’
     role for typed fields.

11.9 Release 4.0.3 (released Jul 05, 2021)
==========================================

11.9.1 Features added
---------------------

   * C, add C23 keywords ‘_Decimal32’, ‘_Decimal64’, and ‘_Decimal128’.

   * #9354: C, add c_extra_keywords to allow user-defined
     keywords during parsing.

   * Revert the removal of ‘sphinx.util:force_decode()’ to become some
     3rd party extensions available again during 5.0

11.9.2 Bugs fixed
-----------------

   * #9330: changeset domain: versionchanged with contents
     being a list will cause error during pdf build

   * #9313: LaTeX: complex table with merged cells broken since 4.0

   * #9305: LaTeX: backslash may cause Improper discretionary list pdf
     build error with Japanese engines

   * #9354: C, remove special macro names from the keyword list.  See
     also c_extra_keywords.

   * #9322: KeyError is raised on PropagateDescDomain transform

11.10 Release 4.0.2 (released May 20, 2021)
===========================================

11.10.1 Dependencies
--------------------

   * #9216: Support jinja2-3.0

11.10.2 Incompatible changes
----------------------------

   * #9222: Update Underscore.js to 1.13.1

   * #9217: manpage: Stop creating a section directory on build manpage
     by default (see man_make_section_directory)

11.10.3 Bugs fixed
------------------

   * #9210: viewcode: crashed if non importable modules found on
     parallel build

   * #9240: Unknown node error for pending_xref_condition is raised if
     an extension that does not support the node installs a
     missing-reference handler

11.11 Release 4.0.1 (released May 11, 2021)
===========================================

11.11.1 Bugs fixed
------------------

   * #9189: autodoc: crashed when ValueError is raised on generating
     signature from a property of the class

   * #9188: autosummary: warning is emitted if list value is set to
     autosummary_generate

   * #8380: html search: tags for search result are broken

   * #9198: i18n: Babel emits errors when running compile_catalog

   * #9205: py domain: The :canonical: option causes “more than one
     target for cross-reference” warning

   * #9201: websupport: UndefinedError is raised: ‘css_tag’ is undefined

11.12 Release 4.0.0 (released May 09, 2021)
===========================================

11.12.1 Dependencies
--------------------

4.0.0b1

   * Drop python 3.5 support

   * Drop docutils 0.12 and 0.13 support

   * LaTeX: add ‘tex-gyre’ font dependency

4.0.0b2

   * Support docutils-0.17.  Please notice it changes the output of HTML
     builder.  Some themes do not support it, and you need to update
     your custom CSS to upgrade it.

11.12.2 Incompatible changes
----------------------------

4.0.0b1

   * #8539: autodoc: info-field-list is generated into the class
     description when ‘autodoc_typehints='description'’ and
     ‘autoclass_content='class'’ set

   * #8898: extlinks: “%s” becomes required keyword in the link caption
     string

   * domain: The ‘Index’ class becomes subclasses of ‘abc.ABC’ to
     indicate methods that must be overridden in the concrete classes

   * #4826: py domain: The structure of python objects is changed.  A
     boolean value is added to indicate that the python object is
     canonical one

   * #7425: MathJax: The MathJax was changed from 2 to 3.  Users using a
     custom MathJax configuration may have to set the old MathJax path
     or update their configuration for version 3.  See
     sphinx.ext.mathjax.

   * #7784: i18n: The msgid for alt text of image is changed

   * #5560: napoleon: napoleon_use_param also affect “other
     parameters” section

   * #7996: manpage: Make a section directory on build manpage by
     default (see man_make_section_directory)

   * #7849: html: Change the default setting of
     html_codeblock_linenos_style to ‘'inline'’

   * #8380: html search: search results are wrapped with ‘<p>’ instead
     of ‘<div>’

   * html theme: Move a script tag for documentation_options.js in
     basic/layout.html to ‘script_files’ variable

   * html theme: Move CSS tags in basic/layout.html to ‘css_files’
     variable

   * #8915: html theme: Emit a warning for sphinx_rtd_theme-0.2.4 or
     older

   * #8508: LaTeX: uplatex becomes a default setting of latex_engine for
     Japanese documents

   * #5977: py domain: ‘:var:’, ‘:cvar:’ and ‘:ivar:’ fields do not
     create cross-references

   * #4550: The ‘align’ attribute of ‘figure’ and ‘table’ nodes becomes
     ‘None’ by default instead of ‘'default'’

   * #8769: LaTeX refactoring: split sphinx.sty into multiple files and
     rename some auxiliary files created in ‘latex’ build output
     repertory

   * #8937: Use explicit title instead of <no title>

   * #8487: The :file: option for csv-table directive now recognizes an
     absolute path as a relative path from source directory

4.0.0b2

   * #9023: Change the CSS classes on cpp;expr and
     cpp;texpr.

11.12.3 Deprecated
------------------

   * html_codeblock_linenos_style.

   * ‘favicon’ and ‘logo’ variable in HTML templates

   * ‘sphinx.directives.patches.CSVTable’

   * ‘sphinx.directives.patches.ListTable’

   * ‘sphinx.directives.patches.RSTTable’

   * ‘sphinx.ext.autodoc.directive.DocumenterBridge.filename_set’

   * ‘sphinx.ext.autodoc.directive.DocumenterBridge.warn()’

   * ‘sphinx.registry.SphinxComponentRegistry.get_source_input()’

   * ‘sphinx.registry.SphinxComponentRegistry.source_inputs’

   * ‘sphinx.transforms.FigureAligner’

   * ‘sphinx.util.pycompat.convert_with_2to3()’

   * ‘sphinx.util.pycompat.execfile_()’

   * ‘sphinx.util.smartypants’

   * ‘sphinx.util.typing.DirectiveOption’

11.12.4 Features added
----------------------

4.0.0b1

   * #8924: autodoc: Support ‘bound’ argument for TypeVar

   * #7383: autodoc: Support typehints for properties

   * #5603: autodoc: Allow to refer to a python class using its
     canonical name when the class has two different names; a canonical
     name and an alias name

   * #8539: autodoc: Add autodoc_typehints_description_target
     to control the behavior of ‘autodoc_typehints=description’

   * #8841: autodoc: autodoc_docstring_signature will
     continue to look for multiple signature lines without backslash
     character

   * #7549: autosummary: Enable autosummary_generate by
     default

   * #8898: extlinks: Allow %s in link caption string

   * #4826: py domain: Add ‘:canonical:’ option to python directives to
     describe the location where the object is defined

   * #7199: py domain: Add python_use_unqualified_type_names.
     to suppress the module name of the python reference if it can be
     resolved (experimental)

   * #7068: py domain: Add py;property directive to describe
     a property

   * #7784: i18n: The alt text for image is translated by default
     (without gettext_additional_targets setting)

   * #2018: html: html_favicon and html_logo now
     accept URL for the image

   * #8070: html search: Support searching for 2characters word

   * #9036: html theme: Allow to inherite the search page

   * #8938: imgconverter: Show the error of the command availability
     check

   * #7830: Add debug logs for change detection of sources and templates

   * #8201: Emit a warning if toctree contains duplicated entries

   * #8326: ‘master_doc’ is now renamed to root_doc.

   * #8942: C++, add support for the C++20 spaceship operator, ‘<=>’.

   * #7199: A new node, ‘sphinx.addnodes.pending_xref_condition’ has
     been added.  It can be used to choose appropriate content of the
     reference by conditions.

4.0.0b2

   * #8818: autodoc: Super class having ‘Any’ arguments causes nit-picky
     warning

   * #9095: autodoc: TypeError is raised on processing broken metaclass

   * #9110: autodoc: metadata of GenericAlias is not rendered as a
     reference in py37+

   * #9098: html: copy-range protection for doctests doesn’t work in
     Safari

   * #9103: LaTeX: imgconverter: conversion runs even if not needed

   * #8127: py domain: Ellipsis in info-field-list causes nit-picky
     warning

   * #9121: py domain: duplicated warning is emitted when both canonical
     and its alias objects are defined on the document

   * #9023: More CSS classes on domain descriptions, see Doctree node classes added by Sphinx
     for details.

   * #8195: mathjax: Rename mathjax_config to
     mathjax2_config and add mathjax3_config.

11.12.5 Bugs fixed
------------------

4.0.0b1

   * #8917: autodoc: Raises a warning if function has wrong __globals__
     value

   * #8415: autodoc: a TypeVar imported from other module is not
     resolved (in Python 3.7 or above)

   * #8992: autodoc: Failed to resolve types.TracebackType type
     annotation

   * #8905: html: html_add_permalinks=None and html_add_permalinks=””
     are ignored

   * #8380: html search: Paragraphs in search results are not identified
     as ‘<p>’

   * #8915: html theme: The translation of sphinx_rtd_theme does not
     work

   * #8342: Emit a warning if a unknown domain is given for directive or
     role (ex.  ‘:unknown:doc:’)

   * #7241: LaTeX: No wrapping for ‘cpp:enumerator’

   * #8711: LaTeX: backticks in code-blocks trigger latexpdf build
     warning (and font change) with late TeXLive 2019

   * #8253: LaTeX: Figures with no size defined get overscaled (compared
     to images with size explicitly set in pixels) (fixed for
     ‘'pdflatex'/'lualatex'’ only)

   * #8881: LaTeX: The depth of bookmarks panel in PDF is not enough for
     navigation

   * #8874: LaTeX: the fix to two minor Pygments LaTeXFormatter output
     issues ignore Pygments style

   * #8925: LaTeX: 3.5.0 ‘verbatimmaxunderfull’ setting does not work as
     expected

   * #8980: LaTeX: missing line break in ‘\pysigline’

   * #8995: LaTeX: legacy ‘\pysiglinewithargsret’ does not compute
     correctly available horizontal space and should use a ragged right
     style

   * #9009: LaTeX: “release” value with underscore leads to invalid
     LaTeX

   * #8911: C++: remove the longest matching prefix in
     cpp_index_common_prefix instead of the first that matches.

   * C, properly reject function declarations when a keyword is used as
     parameter name.

   * #8933: viewcode: Failed to create back-links on parallel build

   * #8960: C and C++, fix rendering of (member) function pointer types
     in function parameter lists.

   * C++, fix linking of names in array declarators, pointer to member
     (function) declarators, and in the argument to ‘sizeof...’.

   * C, fix linking of names in array declarators.

4.0.0b2

   * C, C++, fix ‘KeyError’ when an ‘alias’ directive is the first C/C++
     directive in a file with another C/C++ directive later.

4.0.0b3

   * #9167: html: Failed to add CSS files to the specific page

11.13 Release 3.5.5 (in development)
====================================

11.14 Release 3.5.4 (released Apr 11, 2021)
===========================================

11.14.1 Dependencies
--------------------

   * #9071: Restrict docutils to 0.16

11.14.2 Bugs fixed
------------------

   * #9078: autodoc: Async staticmethods and classmethods are considered
     as non async coroutine-functions with Python3.10

   * #8870, #9001, #9051: html theme: The style are not applied with
     docutils-0.17

        - toctree captions

        - The content of ‘sidebar’ directive

        - figures

11.15 Release 3.5.3 (released Mar 20, 2021)
===========================================

11.15.1 Features added
----------------------

   * #8959: using UNIX path separator in image directive confuses Sphinx
     on Windows

11.16 Release 3.5.2 (released Mar 06, 2021)
===========================================

11.16.1 Bugs fixed
------------------

   * #8943: i18n: Crashed by broken translation messages in ES, EL and
     HR

   * #8936: LaTeX: A custom LaTeX builder fails with unknown node error

   * #8952: Exceptions raised in a Directive cause parallel builds to
     hang

11.17 Release 3.5.1 (released Feb 16, 2021)
===========================================

11.17.1 Bugs fixed
------------------

   * #8883: autodoc: AttributeError is raised on assigning
     __annotations__ on read-only class

   * #8884: html: minified js stemmers not included in the distributed
     package

   * #8885: html: AttributeError is raised if CSS/JS files are installed
     via html_context.

   * #8880: viewcode: ExtensionError is raised on incremental build
     after unparsable python module found

11.18 Release 3.5.0 (released Feb 14, 2021)
===========================================

11.18.1 Dependencies
--------------------

   * LaTeX: ‘multicol’ (it is anyhow a required part of the official
     latex2e base distribution)

11.18.2 Incompatible changes
----------------------------

   * Update Underscore.js to 1.12.0

   * #6550: html: The config variable ‘html_add_permalinks’ is replaced
     by html_permalinks and html_permalinks_icon.

11.18.3 Deprecated
------------------

   * pending_xref node for viewcode extension

   *
     ‘sphinx.builders.linkcheck.CheckExternalLinksBuilder.anchors_ignore’

   * ‘sphinx.builders.linkcheck.CheckExternalLinksBuilder.auth’

   * ‘sphinx.builders.linkcheck.CheckExternalLinksBuilder.broken’

   * ‘sphinx.builders.linkcheck.CheckExternalLinksBuilder.good’

   * ‘sphinx.builders.linkcheck.CheckExternalLinksBuilder.redirected’

   * ‘sphinx.builders.linkcheck.CheckExternalLinksBuilder.rqueue’

   * ‘sphinx.builders.linkcheck.CheckExternalLinksBuilder.to_ignore’

   * ‘sphinx.builders.linkcheck.CheckExternalLinksBuilder.workers’

   * ‘sphinx.builders.linkcheck.CheckExternalLinksBuilder.wqueue’

   * ‘sphinx.builders.linkcheck.node_line_or_0()’

   * ‘sphinx.ext.autodoc.AttributeDocumenter.isinstanceattribute()’

   * ‘sphinx.ext.autodoc.directive.DocumenterBridge.reporter’

   * ‘sphinx.ext.autodoc.importer.get_module_members()’

   * ‘sphinx.ext.autosummary.generate._simple_info()’

   * ‘sphinx.ext.autosummary.generate._simple_warn()’

   * ‘sphinx.writers.html.HTMLTranslator.permalink_text’

   * ‘sphinx.writers.html5.HTML5Translator.permalink_text’

11.18.4 Features added
----------------------

   * #8022: autodoc: autodata and autoattribute directives does not show
     right-hand value of the variable if docstring contains ‘:meta
     hide-value:’ in info-field-list

   * #8514: autodoc: Default values of overloaded functions are taken
     from actual implementation if they’re ellipsis

   * #8775: autodoc: Support type union operator (PEP-604) in Python
     3.10 or above

   * #8297: autodoc: Allow to extend autodoc_default_options.
     via directive options

   * #759: autodoc: Add a new configuration
     autodoc_preserve_defaults as an experimental feature.  It
     preserves the default argument values of functions in source code
     and keep them not evaluated for readability.

   * #8619: html: kbd role generates customizable HTML tags for compound
     keys

   * #8634: html: Allow to change the order of JS/CSS via ‘priority’
     parameter for ‘Sphinx.add_js_file()’ and ‘Sphinx.add_css_file()’

   * #6241: html: Allow to add JS/CSS files to the specific page when an
     extension calls ‘app.add_js_file()’ or ‘app.add_css_file()’ on
     html-page-context event

   * #6550: html: Allow to use HTML permalink texts via
     html_permalinks_icon.

   * #1638: html: Add permalink icons to glossary terms

   * #8868: html search: performance issue with massive lists

   * #8867: html search: Update JavaScript stemmer code to the latest
     version of Snowball (v2.1.0)

   * #8852: i18n: Allow to translate heading syntax in MyST-Parser

   * #8649: imgconverter: Skip availability check if builder supports
     the image type

   * #8573: napoleon: Allow to change the style of custom sections using
     ‘napoleon_custom_styles’

   * #8004: napoleon: Type definitions in Google style docstrings are
     rendered as references when napoleon_preprocess_types.
     enabled

   * #6241: mathjax: Include mathjax.js only on the document using
     equations

   * #8775: py domain: Support type union operator (PEP-604)

   * #8651: std domain: cross-reference for a rubric having inline item
     is broken

   * #7642: std domain: Optimize case-insensitive match of term

   * #8681: viewcode: Support incremental build

   * #8132: Add project_copyright as an alias of
     copyright.

   * #207: Now highlight_language supports multiple languages

   * #2030: code-block and literalinclude supports
     automatic dedent via no-argument ‘:dedent:’ option

   * C++, also hyperlink operator overloads in expressions and alias
     declarations.

   * #8247: Allow production lists to refer to tokens from other
     production groups

   * #8813: Show what extension (or module) caused it on errors on event
     handler

   * #8213: C++: add ‘maxdepth’ option to cpp;alias to
     insert nested declarations.

   * C, add ‘noroot’ option to c;alias to render only nested
     declarations.

   * C++, add ‘noroot’ option to cpp;alias to render only
     nested declarations.

11.18.5 Bugs fixed
------------------

   * #8727: apidoc: namespace module file is not generated if no
     submodules there

   * #741: autodoc: inherited-members doesn’t work for instance
     attributes on super class

   * #8592: autodoc: ‘:meta public:’ does not effect to variables

   * #8594: autodoc: empty __all__ attribute is ignored

   * #8315: autodoc: Failed to resolve struct.Struct type annotation

   * #8652: autodoc: All variable comments in the module are ignored if
     the module contains invalid type comments

   * #8693: autodoc: Default values for overloaded functions are
     rendered as string

   * #8134: autodoc: crashes when mocked decorator takes arguments

   * #8800: autodoc: Uninitialized attributes in superclass are
     recognized as undocumented

   * #8655: autodoc: Failed to generate document if target module
     contains an object that raises an exception on ‘hasattr()’

   * #8306: autosummary: mocked modules are documented as empty page
     when using :recursive: option

   * #8232: graphviz: Image node is not rendered if graph file is in
     subdirectory

   * #8618: html: kbd role produces incorrect HTML when compound-key
     separators (-, + or ^) are used as keystrokes

   * #8629: html: A type warning for html_use_opensearch is shown twice

   * #8714: html: kbd role with “Caps Lock” rendered incorrectly

   * #8123: html search: fix searching for terms containing + (Requires
     a custom search language that does not split on +)

   * #8665: html theme: Could not override globaltoc_maxdepth in
     theme.conf

   * #8446: html: consecutive spaces are displayed as single space

   * #8745: i18n: crashes with KeyError when translation message adds a
     new auto footnote reference

   * #4304: linkcheck: Fix race condition that could lead to checking
     the availability of the same URL twice

   * #8791: linkcheck: The docname for each hyperlink is not displayed

   * #7118: sphinx-quickstart: questionare got Mojibake if libreadline
     unavailable

   * #8094: texinfo: image files on the different directory with
     document are not copied

   * #8782: todo: Cross references in todolist get broken

   * #8720: viewcode: module pages are generated for epub on incremental
     build

   * #8704: viewcode: anchors are generated in incremental build after
     singlehtml

   * #8756: viewcode: highlighted code is generated even if not
     referenced

   * #8671: highlight_options is not working

   * #8341: C, fix intersphinx lookup types for names in declarations.

   * C, C++: in general fix intersphinx and role lookup types.

   * #8683: html_last_updated_fmt does not support UTC
     offset (%z)

   * #8683: html_last_updated_fmt generates wrong time zone
     for %Z

   * #1112: ‘download’ role creates duplicated copies when relative path
     is specified

   * #2616 (fifth item): LaTeX: footnotes from captions are not
     clickable, and for manually numbered footnotes only first one with
     same number is an hyperlink

   * #7576: LaTeX with French babel and memoir crash: “Illegal parameter
     number in definition of ‘\FNH@prefntext’”

   * #8055: LaTeX (docs): A potential display bug with the LaTeX
     generation step in Sphinx (how to generate one-column index)

   * #8072: LaTeX: Directive hlist not implemented in LaTeX

   * #8214: LaTeX: The index role and the glossary generate
     duplicate entries in the LaTeX index (if both used for same term)

   * #8735: LaTeX: wrong internal links in pdf to captioned code-blocks
     when numfig is not True

   * #8442: LaTeX: some indexed terms are ignored when using xelatex
     engine (or pdflatex and latex_use_xindy set to True)
     with memoir class

   * #8750: LaTeX: URLs as footnotes fail to show in PDF if originating
     from inside function type signatures

   * #8780: LaTeX: long words in narrow columns may not be hyphenated

   * #8788: LaTeX: ‘\titleformat’ last argument in sphinx.sty should be
     bracketed, not braced (and is anyhow not needed)

   * #8849: LaTex: code-block printed out of margin (see the opt-in
     LaTeX syntax boolean verbatimforcewraps for use via the
     ‘sphinxsetup’ key of ‘latex_elements’)

   * #8183: LaTeX: Remove substitution_reference nodes from doctree only
     on LaTeX builds

   * #8865: LaTeX: Restructure the index nodes inside title nodes only
     on LaTeX builds

   * #8796: LaTeX: potentially critical low level TeX coding mistake has
     gone unnoticed so far

   * C, see c;alias skip symbols without explicit declarations
     instead of crashing.

   * C, see c;alias give a warning when the root symbol is not
     declared.

   * C, ‘expr’ role should start symbol lookup in the current scope.

11.19 Release 3.4.3 (released Jan 08, 2021)
===========================================

11.19.1 Bugs fixed
------------------

   * #8655: autodoc: Failed to generate document if target module
     contains an object that raises an exception on ‘hasattr()’

11.20 Release 3.4.2 (released Jan 04, 2021)
===========================================

11.20.1 Bugs fixed
------------------

   * #8164: autodoc: Classes that inherit mocked class are not
     documented

   * #8602: autodoc: The ‘autodoc-process-docstring’ event is emitted to
     the non-datadescriptors unexpectedly

   * #8616: autodoc: AttributeError is raised on non-class object is
     passed to autoclass directive

11.21 Release 3.4.1 (released Dec 25, 2020)
===========================================

11.21.1 Bugs fixed
------------------

   * #8559: autodoc: AttributeError is raised when using
     forward-reference type annotations

   * #8568: autodoc: TypeError is raised on checking slots attribute

   * #8567: autodoc: Instance attributes are incorrectly added to Parent
     class

   * #8566: autodoc: The ‘autodoc-process-docstring’ event is emitted to
     the alias classes unexpectedly

   * #8583: autodoc: Unnecessary object comparison via ‘__eq__’ method

   * #8565: linkcheck: Fix PriorityQueue crash when link tuples are not
     comparable

11.22 Release 3.4.0 (released Dec 20, 2020)
===========================================

11.22.1 Incompatible changes
----------------------------

   * #8105: autodoc: the signature of class constructor will be shown
     for decorated classes, not a signature of decorator

11.22.2 Deprecated
------------------

   * The ‘follow_wrapped’ argument of ‘sphinx.util.inspect.signature()’

   * The ‘no_docstring’ argument of
     ‘sphinx.ext.autodoc.Documenter.add_content()’

   * ‘sphinx.ext.autodoc.Documenter.get_object_members()’

   * ‘sphinx.ext.autodoc.DataDeclarationDocumenter’

   * ‘sphinx.ext.autodoc.GenericAliasDocumenter’

   * ‘sphinx.ext.autodoc.InstanceAttributeDocumenter’

   * ‘sphinx.ext.autodoc.SlotsAttributeDocumenter’

   * ‘sphinx.ext.autodoc.TypeVarDocumenter’

   * ‘sphinx.ext.autodoc.importer._getannotations()’

   * ‘sphinx.ext.autodoc.importer._getmro()’

   * ‘sphinx.pycode.ModuleAnalyzer.parse()’

   * ‘sphinx.util.osutil.movefile()’

   * ‘sphinx.util.requests.is_ssl_error()’

11.22.3 Features added
----------------------

   * #8119: autodoc: Allow to determine whether a member not included in
     ‘__all__’ attribute of the module should be documented or not via
     autodoc-skip-member event

   * #8219: autodoc: Parameters for generic class are not shown when
     super class is a generic class and show-inheritance option is given
     (in Python 3.7 or above)

   * autodoc: Add ‘Documenter.config’ as a shortcut to access the config
     object

   * autodoc: Add Optional[t] to annotation of function and method if a
     default value equal to None is set.

   * #8209: autodoc: Add ‘:no-value:’ option to autoattribute
     and autodata directive to suppress the default
     value of the variable

   * #8460: autodoc: Support custom types defined by typing.NewType

   * #8285: napoleon: Add napoleon_attr_annotations to merge
     type hints on source code automatically if any type is specified in
     docstring

   * #8236: napoleon: Support numpydoc’s “Receives” section

   * #6914: Add a new event warn-missing-reference to custom
     warning messages when failed to resolve a cross-reference

   * #6914: Emit a detailed warning when failed to resolve a ‘:ref:’
     reference

   * #6629: linkcheck: The builder now handles rate limits.  See
     ‘linkcheck_retry_on_rate_limit’ for details.

11.22.4 Bugs fixed
------------------

   * #7613: autodoc: autodoc does not respect __signature__ of the class

   * #4606: autodoc: the location of the warning is incorrect for
     inherited method

   * #8105: autodoc: the signature of class constructor is incorrect if
     the class is decorated

   * #8434: autodoc: autodoc_type_aliases does not effect to
     variables and attributes

   * #8443: autodoc: autodata directive can’t create document for
     PEP-526 based type annotated variables

   * #8443: autodoc: autoattribute directive can’t create document for
     PEP-526 based uninitialized variables

   * #8480: autodoc: autoattribute could not create document for
     __slots__ attributes

   * #8503: autodoc: autoattribute could not create document for a
     GenericAlias as class attributes correctly

   * #8534: autodoc: autoattribute could not create document for a
     commented attribute in alias class

   * #8452: autodoc: autodoc_type_aliases doesn’t work when
     autodoc_typehints is set to “description”

   * #8541: autodoc: autodoc_type_aliases doesn’t work for the type
     annotation to instance attributes

   * #8460: autodoc: autodata and autoattribute directives do not
     display type information of TypeVars

   * #8493: autodoc: references to builtins not working in class aliases

   * #8522: autodoc: ‘__bool__’ method could be called

   * #8067: autodoc: A typehint for the instance variable having
     type_comment on super class is not displayed

   * #8545: autodoc: a __slots__ attribute is not documented even having
     docstring

   * #741: autodoc: inherited-members doesn’t work for instance
     attributes on super class

   * #8477: autosummary: non utf-8 reST files are generated when
     template contains multibyte characters

   * #8501: autosummary: summary extraction splits text after “el at.”
     unexpectedly

   * #8524: html: Wrong url_root has been generated on a document named
     “index”

   * #8419: html search: Do not load ‘language_data.js’ in non-search
     pages

   * #8549: i18n: ‘-D gettext_compact=0’ is no longer working

   * #8454: graphviz: The layout option for graph and digraph directives
     don’t work

   * #8131: linkcheck: Use GET when HEAD requests cause Too Many
     Redirects, to accommodate infinite redirect loops on HEAD

   * #8437: Makefile: ‘make clean’ with empty BUILDDIR is dangerous

   * #8365: py domain: ‘:type:’ and ‘:rtype:’ gives false ambiguous
     class lookup warnings

   * #8352: std domain: Failed to parse an option that starts with
     bracket

   * #8519: LaTeX: Prevent page brake in the middle of a seealso

   * #8520: C, fix copying of AliasNode.

11.23 Release 3.3.1 (released Nov 12, 2020)
===========================================

11.23.1 Bugs fixed
------------------

   * #8372: autodoc: autoclass directive became slower than Sphinx-3.2

   * #7727: autosummary: raise PycodeError when documenting python
     package without __init__.py

   * #8350: autosummary: autosummary_mock_imports causes slow down
     builds

   * #8364: C, properly initialize attributes in empty symbols.

   * #8399: i18n: Put system locale path after the paths specified by
     configuration

11.24 Release 3.3.0 (released Nov 02, 2020)
===========================================

11.24.1 Deprecated
------------------

   * ‘sphinx.builders.latex.LaTeXBuilder.usepackages’

   * ‘sphinx.builders.latex.LaTeXBuilder.usepackages_afger_hyperref’

   * ‘sphinx.ext.autodoc.SingledispatchFunctionDocumenter’

   * ‘sphinx.ext.autodoc.SingledispatchMethodDocumenter’

11.24.2 Features added
----------------------

   * #8100: html: Show a better error message for failures on copying
     html_static_files

   * #8141: C: added a ‘maxdepth’ option to c;alias to
     insert nested declarations.

   * #8081: LaTeX: Allow to add LaTeX package via
     ‘app.add_latex_package()’ until just before writing .tex file

   * #7996: manpage: Add man_make_section_directory to make
     a section directory on build man page

   * #8289: epub: Allow to suppress “duplicated ToC entry found”
     warnings from epub builder using suppress_warnings.

   * #8298: sphinx-quickstart: Add sphinx-quickstart –no-sep.
     option

   * #8304: sphinx.testing: Register public markers in
     sphinx.testing.fixtures

   * #8051: napoleon: use the obj role for all See Also items

   * #8050: napoleon: Apply napoleon_preprocess_types to
     every field

   * C and C++, show line numbers for previous declarations when
     duplicates are detected.

   * #8183: Remove substitution_reference nodes from doctree only on
     LaTeX builds

11.24.3 Bugs fixed
------------------

   * #8085: i18n: Add support for having single text domain

   * #6640: i18n: Failed to override system message translation

   * #8143: autodoc: AttributeError is raised when False value is passed
     to autodoc_default_options

   * #8103: autodoc: functools.cached_property is not considered as a
     property

   * #8190: autodoc: parsing error is raised if some extension replaces
     docstring by string not ending with blank lines

   * #8142: autodoc: Wrong constructor signature for the class derived
     from typing.Generic

   * #8157: autodoc: TypeError is raised when annotation has invalid
     __args__

   * #7964: autodoc: Tuple in default value is wrongly rendered

   * #8200: autodoc: type aliases break type formatting of autoattribute

   * #7786: autodoc: can’t detect overloaded methods defined in other
     file

   * #8294: autodoc: single-string __slots__ is not handled correctly

   * #7785: autodoc: autodoc_typehints=’none’ does not effect to
     overloaded functions

   * #8192: napoleon: description is disappeared when it contains inline
     literals

   * #8142: napoleon: Potential of regex denial of service in google
     style docs

   * #8169: LaTeX: pxjahyper loaded even when latex_engine is not platex

   * #8215: LaTeX: ‘oneside’ classoption causes build warning

   * #8175: intersphinx: Potential of regex denial of service by broken
     inventory

   * #8277: sphinx-build: missing and redundant spacing (and etc) for
     console output on building

   * #7973: imgconverter: Check availability of imagemagick many times

   * #8255: py domain: number in default argument value is changed from
     hexadecimal to decimal

   * #8316: html: Prevent arrow keys changing page when button elements
     are focused

   * #8343: html search: Fix unnecessary load of images when parsing the
     document

   * #8254: html theme: Line numbers misalign with code lines

   * #8093: The highlight warning has wrong location in some builders
     (LaTeX, singlehtml and so on)

   * #8215: Eliminate Fancyhdr build warnings for oneside documents

   * #8239: Failed to refer a token in productionlist if it is indented

   * #8268: linkcheck: Report HTTP errors when ‘linkcheck_anchors’ is
     ‘True’

   * #8245: linkcheck: take source directory into account for local
     files

   * #8321: linkcheck: ‘tel:’ schema hyperlinks are detected as errors

   * #8323: linkcheck: An exit status is incorrect when links having
     unsupported schema found

   * #8188: C, add missing items to internal object types dictionary,
     e.g., preventing intersphinx from resolving them.

   * C, fix anon objects in intersphinx.

   * #8270, C++, properly reject functions as duplicate declarations if
     a non-function declaration of the same name already exists.

   * C, fix references to function parameters.  Link to the function
     instead of a non-existing anchor.

   * #6914: figure numbers are unexpectedly assigned to uncaptioned
     items

   * #8320: make “inline” line numbers un-selectable

11.24.4 Testing
---------------

   * #8257: Support parallel build in sphinx.testing

11.25 Release 3.2.1 (released Aug 14, 2020)
===========================================

11.25.1 Features added
----------------------

   * #8095: napoleon: Add napoleon_preprocess_types to
     enable the type preprocessor for numpy style docstrings

   * #8114: C and C++, parse function attributes after parameters and
     qualifiers.

11.25.2 Bugs fixed
------------------

   * #8074: napoleon: Crashes during processing C-ext module

   * #8088: napoleon: “Inline literal start-string without end-string”
     warning in Numpy style Parameters section

   * #8084: autodoc: KeyError is raised on documenting an attribute of
     the broken class

   * #8091: autodoc: AttributeError is raised on documenting an
     attribute on Python 3.5.2

   * #8099: autodoc: NameError is raised when target code uses
     ‘TYPE_CHECKING’

   * C++, fix parsing of template template parameters, broken by the fix
     of #7944

11.26 Release 3.2.0 (released Aug 08, 2020)
===========================================

11.26.1 Deprecated
------------------

   * ‘sphinx.ext.autodoc.members_set_option()’

   * ‘sphinx.ext.autodoc.merge_special_members_option()’

   * ‘sphinx.writers.texinfo.TexinfoWriter.desc’

   * C, parsing of pre-v3 style type directives and roles, along with
     the options c_allow_pre_v3 and
     c_warn_on_allowed_pre_v3.

11.26.2 Features added
----------------------

   * #2076: autodoc: Allow overriding of exclude-members in skip-member
     function

   * #8034: autodoc: ‘:private-member:’ can take an explicit list of
     member names to be documented

   * #2024: autosummary: Add autosummary_filename_map to
     avoid conflict of filenames between two object with different case

   * #8011: autosummary: Support instance attributes as a target of
     autosummary directive

   * #7849: html: Add html_codeblock_linenos_style to change
     the style of line numbers for code-blocks

   * #7853: C and C++, support parameterized GNU style attributes.

   * #7888: napoleon: Add aliases Warn and Raise.

   * #7690: napoleon: parse type strings and make them hyperlinks as
     possible.  The conversion rule can be updated via
     napoleon_type_aliases.

   * #8049: napoleon: Create a hyperlink for each the type of parameter
     when ‘napoleon_use_params’ is False

   * C, added c;alias directive for inserting copies of
     existing declarations.

   * #7745: html: inventory is broken if the docname contains a space

   * #7991: html search: Allow searching for numbers

   * #7902: html theme: Add a new option ‘globaltoc_maxdepth’ to control
     the behavior of globaltoc in sidebar

   * #7840: i18n: Optimize the dependencies check on bootstrap

   * #7768: i18n: figure_language_filename supports
     ‘docpath’ token

   * #5208: linkcheck: Support checks for local links

   * #5090: setuptools: Link verbosity to distutils’ -v and -q option

   * #6698: doctest: Add ‘:trim-doctest-flags:’ and
     ‘:no-trim-doctest-flags:’ options to doctest, testcode and
     testoutput directives

   * #7052: add ‘:noindexentry:’ to the Python, C, C++, and Javascript
     domains.  Update the documentation to better reflect the
     relationship between this option and the ‘:noindex:’ option.

   * #7899: C, add possibility of parsing of some pre-v3 style type
     directives and roles and try to convert them to equivalent v3
     directives/roles.  Set the new option c_allow_pre_v3 to
     ‘True’ to enable this.  The warnings printed from this
     functionality can be suppressed by setting
     ‘c_warn_on_allowed_pre_v3`’ to ‘True’.  The functionality is
     immediately deprecated.

   * #7999: C, add support for named variadic macro arguments.

   * #8071: Allow to suppress “self referenced toctrees” warning

11.26.3 Bugs fixed
------------------

   * #7886: autodoc: TypeError is raised on mocking generic-typed
     classes

   * #7935: autodoc: function signature is not shown when the function
     has a parameter having ‘inspect._empty’ as its default value

   * #7901: autodoc: type annotations for overloaded functions are not
     resolved

   * #904: autodoc: An instance attribute cause a crash of autofunction
     directive

   * #1362: autodoc: ‘private-members’ option does not work for class
     attributes

   * #7983: autodoc: Generator type annotation is wrongly rendered in
     py36

   * #8030: autodoc: An uninitialized annotated instance variable is not
     documented when ‘:inherited-members:’ option given

   * #8032: autodoc: A type hint for the instance variable defined at
     parent class is not shown in the document of the derived class

   * #8041: autodoc: An annotated instance variable on super class is
     not documented when derived class has other annotated instance
     variables

   * #7839: autosummary: cannot handle umlauts in function names

   * #7865: autosummary: Failed to extract summary line when
     abbreviations found

   * #7866: autosummary: Failed to extract correct summary line when
     docstring contains a hyperlink target

   * #7469: autosummary: “Module attributes” header is not translatable

   * #7940: apidoc: An extra newline is generated at the end of the rst
     file if a module has submodules

   * #4258: napoleon: decorated special methods are not shown

   * #7799: napoleon: parameters are not escaped for combined params in
     numpydoc

   * #7780: napoleon: multiple parameters declaration in numpydoc was
     wrongly recognized when napoleon_use_params=True

   * #7715: LaTeX: ‘numfig_secnum_depth > 1’ leads to wrong figure links

   * #7846: html theme: XML-invalid files were generated

   * #7894: gettext: Wrong source info is shown when using rst_epilog

   * #7691: linkcheck: HEAD requests are not used for checking

   * #4888: i18n: Failed to add an explicit title to ‘:ref:’ role on
     translation

   * #7928: py domain: failed to resolve a type annotation for the
     attribute

   * #8008: py domain: failed to parse a type annotation containing
     ellipsis

   * #7994: std domain: option directive does not generate old node_id
     compatible with 2.x or older

   * #7968: i18n: The content of ‘math’ directive is interpreted as reST
     on translation

   * #7768: i18n: The ‘root’ element for figure_language_filename
     is not a path that user specifies in the document

   * #7993: texinfo: TypeError is raised for nested object descriptions

   * #7993: texinfo: a warning not supporting desc_signature_line node
     is shown

   * #7869: abbr role without an explanation will show the
     explanation from the previous abbr role

   * #8048: graphviz: graphviz.css was copied on building non-HTML
     document

   * C and C++, removed ‘noindex’ directive option as it did nothing.

   * #7619: Duplicated node IDs are generated if node has multiple IDs

   * #2050: Symbols sections are appeared twice in the index page

   * #8017: Fix circular import in sphinx.addnodes

   * #7986: CSS: make “highlight” selector more robust

   * #7944: C++, parse non-type template parameters starting with a
     dependent qualified name.

   * C, don’t deepcopy the entire symbol table and make a mess every
     time an enumerator is handled.

11.27 Release 3.1.2 (released Jul 05, 2020)
===========================================

11.27.1 Incompatible changes
----------------------------

   * #7650: autodoc: the signature of base function will be shown for
     decorated functions, not a signature of decorator

11.27.2 Bugs fixed
------------------

   * #7844: autodoc: Failed to detect module when relative module name
     given

   * #7856: autodoc: AttributeError is raised when non-class object is
     given to the autoclass directive

   * #7850: autodoc: KeyError is raised for invalid mark up when
     autodoc_typehints is ‘description’

   * #7812: autodoc: crashed if the target name matches to both an
     attribute and module that are same name

   * #7650: autodoc: function signature becomes ‘(*args, **kwargs)’ if
     the function is decorated by generic decorator

   * #7812: autosummary: generates broken stub files if the target code
     contains an attribute and module that are same name

   * #7806: viewcode: Failed to resolve viewcode references on 3rd party
     builders

   * #7838: html theme: List items have extra vertical space

   * #7878: html theme: Undesired interaction between “overflow” and
     “float”

11.28 Release 3.1.1 (released Jun 14, 2020)
===========================================

11.28.1 Incompatible changes
----------------------------

   * #7808: napoleon: a type for attribute are represented as typed
     field

11.28.2 Features added
----------------------

   * #7807: autodoc: Show detailed warning when type_comment is
     mismatched with its signature

11.28.3 Bugs fixed
------------------

   * #7808: autodoc: Warnings raised on variable and attribute type
     annotations

   * #7802: autodoc: EOFError is raised on parallel build

   * #7821: autodoc: TypeError is raised for overloaded C-ext function

   * #7805: autodoc: an object which descriptors returns is unexpectedly
     documented

   * #7807: autodoc: wrong signature is shown for the function using
     contextmanager

   * #7812: autosummary: generates broken stub files if the target code
     contains an attribute and module that are same name

   * #7808: napoleon: Warnings raised on variable and attribute type
     annotations

   * #7811: sphinx.util.inspect causes circular import problem

11.29 Release 3.1.0 (released Jun 08, 2020)
===========================================

11.29.1 Dependencies
--------------------

   * #7746: mathjax: Update to 2.7.5

11.29.2 Incompatible changes
----------------------------

   * #7477: imgconverter: Invoke “magick convert” command by default on
     Windows

11.29.3 Deprecated
------------------

   * The first argument for
     sphinx.ext.autosummary.generate.AutosummaryRenderer has been
     changed to Sphinx object

   * ‘sphinx.ext.autosummary.generate.AutosummaryRenderer’ takes an
     object type as an argument

   * The ‘ignore’ argument of ‘sphinx.ext.autodoc.Documenter.get_doc()’

   * The ‘template_dir’ argument of ‘sphinx.ext.autosummary.generate.
     AutosummaryRenderer’

   * The ‘module’ argument of ‘sphinx.ext.autosummary.generate.
     find_autosummary_in_docstring()’

   * The ‘builder’ argument of ‘sphinx.ext.autosummary.generate.
     generate_autosummary_docs()’

   * The ‘template_dir’ argument of ‘sphinx.ext.autosummary.generate.
     generate_autosummary_docs()’

   * The ‘ignore’ argument of
     ‘sphinx.util.docstring.prepare_docstring()’

   * ‘sphinx.ext.autosummary.generate.AutosummaryRenderer.exists()’

   * ‘sphinx.util.rpartition()’

11.29.4 Features added
----------------------

   * LaTeX: Make the ‘toplevel_sectioning’ setting optional in LaTeX
     theme

   * LaTeX: Allow to override papersize and pointsize from LaTeX themes

   * LaTeX: Add latex_theme_options to override theme
     options

   * #7410: Allow to suppress “circular toctree references detected”
     warnings using suppress_warnings.

   * C, added scope control directives, see c;namespace,
     c;namespace-push, and c;namespace-pop.

   * #2044: autodoc: Suppress default value for instance attributes

   * #7473: autodoc: consider a member public if docstring contains
     ‘:meta public:’ in info-field-list

   * #7487: autodoc: Allow to generate docs for singledispatch functions
     by py:autofunction

   * #7143: autodoc: Support final classes and methods

   * #7384: autodoc: Support signatures defined by ‘__new__()’,
     metaclasses and builtin base classes

   * #2106: autodoc: Support multiple signatures on docstring

   * #4422: autodoc: Support GenericAlias in Python 3.7 or above

   * #3610: autodoc: Support overloaded functions

   * #7722: autodoc: Support TypeVar

   * #7466: autosummary: headings in generated documents are not
     translated

   * #7490: autosummary: Add ‘:caption:’ option to autosummary directive
     to set a caption to the toctree

   * #7469: autosummary: Support module attributes

   * #248, #6040: autosummary: Add ‘:recursive:’ option to autosummary
     directive to generate stub files recursively

   * #4030: autosummary: Add autosummary_context to add
     template variables for custom templates

   * #7530: html: Support nested <kbd> elements

   * #7481: html theme: Add right margin to footnote/citation labels

   * #7482, #7717: html theme: CSS spacing for code blocks with captions
     and line numbers

   * #7443: html theme: Add new options ‘globaltoc_collapse’ and
     ‘globaltoc_includehidden’ to control the behavior of globaltoc in
     sidebar

   * #7484: html theme: Avoid clashes between sidebar and other blocks

   * #7476: html theme: Relbar breadcrumb should contain current page

   * #7506: html theme: A canonical URL is not escaped

   * #7533: html theme: Avoid whitespace at the beginning of
     genindex.html

   * #7541: html theme: Add a “clearer” at the end of the “body”

   * #7542: html theme: Make admonition/topic/sidebar scrollable

   * #7543: html theme: Add top and bottom margins to tables

   * #7695: html theme: Add viewport meta tag for basic theme

   * #7721: html theme: classic: default codetextcolor/codebgcolor
     doesn’t override Pygments

   * C and C++: allow semicolon in the end of declarations.

   * C++, parse parameterized noexcept specifiers.

   * #7294: C++, parse expressions with user-defined literals.

   * C++, parse trailing return types.

   * #7143: py domain: Add ‘:final:’ option to ‘py:class:’,
     ‘py:exception:’ and ‘py:method:’ directives

   * #7596: py domain: Change a type annotation for variables to a
     hyperlink

   * #7770: std domain: option directive support arguments in
     the form of ‘foo[=bar]’

   * #7582: napoleon: a type for attribute are represented like type
     annotation

   * #7734: napoleon: overescaped trailing underscore on attribute

   * #7247: linkcheck: Add linkcheck_request_headers to send
     custom HTTP headers for specific host

   * #7792: setuptools: Support ‘--verbosity’ option

   * #7683: Add ‘allowed_exceptions’ parameter to ‘Sphinx.emit()’ to
     allow handlers to raise specified exceptions

   * #7295: C++, parse (trailing) requires clauses.

11.29.5 Bugs fixed
------------------

   * #6703: autodoc: incremental build does not work for imported
     objects

   * #7564: autodoc: annotations not to be shown for descriptors

   * #6588: autodoc: Decorated inherited method has no documentation

   * #7469: autodoc: The change of autodoc-process-docstring for
     variables is cached unexpectedly

   * #7559: autodoc: misdetects a sync function is async

   * #6857: autodoc: failed to detect a classmethod on Enum class

   * #7562: autodoc: a typehint contains spaces is wrongly rendered
     under autodoc_typehints=’description’ mode

   * #7551: autodoc: failed to import nested class

   * #7362: autodoc: does not render correct signatures for built-in
     functions

   * #7654: autodoc: ‘Optional[Union[foo, bar]]’ is presented as
     ‘Union[foo, bar, None]’

   * #7629: autodoc: autofunction emits an unfriendly warning if an
     invalid object specified

   * #7650: autodoc: undecorated signature is shown for decorated
     functions

   * #7676: autodoc: typo in the default value of autodoc_member_order

   * #7676: autodoc: wrong value for :member-order: option is ignored
     silently

   * #7676: autodoc: member-order=”bysource” does not work for C module

   * #3673: autodoc: member-order=”bysource” does not work for a module
     having __all__

   * #7668: autodoc: wrong retann value is passed to a handler of
     autodoc-process-signature

   * #7711: autodoc: fails with ValueError when processing numpy objects

   * #7791: autodoc: TypeError is raised on documenting singledispatch
     function

   * #7551: autosummary: a nested class is indexed as non-nested class

   * #7661: autosummary: autosummary directive emits warnings twices if
     failed to import the target module

   * #7685: autosummary: The template variable “members” contains
     imported members even if ‘autossummary_imported_members’ is False

   * #7671: autosummary: The location of import failure warning is
     missing

   * #7535: sphinx-autogen: crashes when custom template uses
     inheritance

   * #7536: sphinx-autogen: crashes when template uses i18n feature

   * #7781: sphinx-build: Wrong error message when outdir is not
     directory

   * #7653: sphinx-quickstart: Fix multiple directory creation for
     nested relpath

   * #2785: html: Bad alignment of equation links

   * #7718: html theme: some themes does not respect background color of
     Pygments style (agogo, haiku, nature, pyramid, scrolls, sphinxdoc
     and traditional)

   * #7544: html theme: inconsistent padding in admonitions

   * #7581: napoleon: bad parsing of inline code in attribute docstrings

   * #7628: imgconverter: runs imagemagick once unnecessary for builders
     not supporting images

   * #7610: incorrectly renders consecutive backslashes for
     docutils-0.16

   * #7646: handle errors on event handlers

   * #4187: LaTeX: EN DASH disappears from PDF bookmarks in Japanese
     documents

   * #7701: LaTeX: Anonymous indirect hyperlink target causes duplicated
     labels

   * #7723: LaTeX: pdflatex crashed when URL contains a single quote

   * #7756: py domain: The default value for positional only argument is
     not shown

   * #7760: coverage: Add coverage_show_missing_items to
     show coverage result to console

   * C++, fix rendering and xrefs in nested names explicitly starting in
     global scope, e.g., ‘::A::B’.

   * C, fix rendering and xrefs in nested names explicitly starting in
     global scope, e.g., ‘.A.B’.

   * #7763: C and C++, don’t crash during display stringification of
     unary expressions and fold expressions.

11.30 Release 3.0.4 (released May 27, 2020)
===========================================

11.30.1 Bugs fixed
------------------

   * #7567: autodoc: parametrized types are shown twice for generic
     types

   * #7637: autodoc: system defined TypeVars are shown in Python 3.9

   * #7696: html: Updated jQuery version from 3.4.1 to 3.5.1 for
     security reasons

   * #7611: md5 fails when OpenSSL FIPS is enabled

   * #7626: release package does not contain ‘CODE_OF_CONDUCT’

11.31 Release 3.0.3 (released Apr 26, 2020)
===========================================

11.31.1 Features added
----------------------

   * C, parse array declarators with static, qualifiers, and VLA
     specification.

11.31.2 Bugs fixed
------------------

   * #7516: autodoc: crashes if target object raises an error on
     accessing its attributes

11.32 Release 3.0.2 (released Apr 19, 2020)
===========================================

11.32.1 Features added
----------------------

   * C, parse attributes and add c_id_attributes and
     c_paren_attributes to support user-defined attributes.

11.32.2 Bugs fixed
------------------

   * #7461: py domain: fails with IndexError for empty tuple in type
     annotation

   * #7510: py domain: keyword-only arguments are documented as having a
     default of None

   * #7418: std domain: term role could not match
     case-insensitively

   * #7461: autodoc: empty tuple in type annotation is not shown
     correctly

   * #7479: autodoc: Sphinx builds has been slower since 3.0.0 on
     mocking

   * C++, fix spacing issue in east-const declarations.

   * #7414: LaTeX: Xindy language options were incorrect

   * sphinx crashes with ImportError on python3.5.1

11.33 Release 3.0.1 (released Apr 11, 2020)
===========================================

11.33.1 Incompatible changes
----------------------------

   * #7418: std domain: ‘term’ role becomes case sensitive

11.33.2 Bugs fixed
------------------

   * #7428: py domain: a reference to class ‘None’ emits a nitpicky
     warning

   * #7445: py domain: a return annotation ‘None’ in the function
     signature is not converted to a hyperlink when using intersphinx

   * #7418: std domain: duplication warning for glossary terms is case
     insensitive

   * #7438: C++, fix merging overloaded functions in parallel builds.

   * #7422: autodoc: fails with ValueError when using
     autodoc_mock_imports

   * #7435: autodoc: ‘autodoc_typehints='description'’ doesn’t suppress
     typehints in signature for classes/methods

   * #7451: autodoc: fails with AttributeError when an object returns
     non-string object as a ‘__doc__’ member

   * #7423: crashed when giving a non-string object to logger

   * #7479: html theme: Do not include xmlns attribute with HTML 5
     doctype

   * #7426: html theme: Escape some links in HTML templates

11.34 Release 3.0.0 (released Apr 06, 2020)
===========================================

11.34.1 Dependencies
--------------------

3.0.0b1

   * LaTeX: drop dependency on ‘extractbb’ for image inclusion in
     Japanese documents as ‘.xbb’ files are unneeded by ‘dvipdfmx’ since
     TeXLive2015 (refs: #6189)

   * babel-2.0 or above is available (Unpinned)

11.34.2 Incompatible changes
----------------------------

3.0.0b1

   * Drop features and APIs deprecated in 1.8.x

   * #247: autosummary: stub files are overwritten automatically by
     default.  see autosummary_generate_overwrite to change
     the behavior

   * #5923: autodoc: the members of ‘object’ class are not documented by
     default when ‘:inherited-members:’ and ‘:special-members:’ are
     given.

   * #6830: py domain: ‘meta’ fields in info-field-list becomes
     reserved.  They are not displayed on output document now

   * #6417: py domain: doctree of desc_parameterlist has been changed.
     The argument names, annotations and default values are wrapped with
     inline node

   * The structure of ‘sphinx.events.EventManager.listeners’ has changed

   * Due to the scoping changes for productionlist some uses
     of token must be modified to include the scope which was
     previously ignored.

   * #6903: Internal data structure of Python, reST and standard domains
     have changed.  The node_id is added to the index of objects and
     modules.  Now they contains a pair of docname and node_id for cross
     reference.

   * #7276: C++ domain: Non intended behavior is removed such as
     ‘say_hello_’ links to ‘.. cpp:function:: say_hello()’

   * #7210: js domain: Non intended behavior is removed such as
     ‘parseInt_’ links to ‘.. js:function:: parseInt’

   * #7229: rst domain: Non intended behavior is removed such as
     ‘numref_’ links to ‘.. rst:role:: numref’

   * #6903: py domain: Non intended behavior is removed such as
     ‘say_hello_’ links to ‘.. py:function:: say_hello()’

   * #7246: py domain: Drop special cross reference helper for
     exceptions, functions and methods

   * The C domain has been rewritten, with additional directives and
     roles.  The existing ones are now more strict, resulting in new
     warnings.

   * The attribute ‘sphinx_cpp_tagname’ in the ‘desc_signature_line’
     node has been renamed to ‘sphinx_line_type’.

   * #6462: double backslashes in domain directives are no longer
     replaced by single backslashes as default.  A new configuration
     value strip_signature_backslash can be used by users to
     re-enable it.

3.0.0 final

   * #7222: ‘sphinx.util.inspect.unwrap()’ is renamed to ‘unwrap_all()’

11.34.3 Deprecated
------------------

3.0.0b1

   * ‘desc_signature['first']’

   * ‘sphinx.directives.DescDirective’

   * ‘sphinx.domains.std.StandardDomain.add_object()’

   * ‘sphinx.domains.python.PyDecoratorMixin’

   * ‘sphinx.ext.autodoc.get_documenters()’

   * ‘sphinx.ext.autosummary.process_autosummary_toc()’

   * ‘sphinx.parsers.Parser.app’

   * ‘sphinx.testing.path.Path.text()’

   * ‘sphinx.testing.path.Path.bytes()’

   * ‘sphinx.util.inspect.getargspec()’

   * ‘sphinx.writers.latex.LaTeXWriter.format_docclass()’

11.34.4 Features added
----------------------

3.0.0b1

   * #247: autosummary: Add autosummary_generate_overwrite.
     to overwrite old stub file

   * #5923: autodoc: ‘:inherited-members:’ option takes a name of
     anchestor class not to document inherited members of the class and
     uppers

   * #6830: autodoc: consider a member private if docstring contains
     ‘:meta private:’ in info-field-list

   * #7165: autodoc: Support Annotated type (PEP-593)

   * #2815: autodoc: Support singledispatch functions and methods

   * #7079: autodoc: autodoc_typehints accepts
     ‘"description"’ configuration.  It shows typehints as object
     description

   * #7314: apidoc: Propagate ‘--maxdepth’ option through package
     documents

   * #6558: glossary: emit a warning for duplicated glossary entry

   * #3106: domain: Register hyperlink target for index page
     automatically

   * #6558: std domain: emit a warning for duplicated generic objects

   * #6830: py domain: Add new event:
     object-description-transform.

   * #6895: py domain: Do not emit nitpicky warnings for built-in types

   * py domain: Support lambda functions in function signature

   * #6417: py domain: Allow to make a style for arguments of functions
     and methods

   * #7238, #7239: py domain: Emit a warning on describing a python
     object if the entry is already added as the same name

   * #7341: py domain: type annotations in signature are converted to
     cross refs

   * Support priority of event handlers.  For more detail, see
     Sphinx.connect().

   * #3077: Implement the scoping for productionlist as
     indicated in the documentation.

   * #1027: Support backslash line continuation in productionlist.

   * #7108: config: Allow to show an error message from conf.py via
     ‘ConfigError’

   * #7032: html: html_scaled_image_link will be disabled
     for images having ‘no-scaled-link’ class

   * #7144: Add CSS class indicating its domain for each desc node

   * #7211: latex: Use babel for Chinese document when using XeLaTeX

   * #6672: LaTeX: Support LaTeX Theming (experimental)

   * #7005: LaTeX: Add LaTeX styling macro for kbd role

   * #7220: genindex: Show “main” index entries at first

   * #7103: linkcheck: writes all links to ‘output.json’

   * #7025: html search: full text search can be disabled for individual
     document using ‘:nosearch:’ file-wide metadata

   * #7293: html search: Allow to override JavaScript splitter via
     ‘SearchLanguage.js_splitter_code’

   * #7142: html theme: Add a theme option: ‘pygments_dark_style’ to
     switch the style of code-blocks in dark mode

   * The C domain has been rewritten adding for example:

        - Cross-referencing respecting the current scope.

        - Possible to document anonymous entities.

        - More specific directives and roles for each type of entity,
          e.g., handling scoping of enumerators.

        - New role c;expr for rendering expressions and
          types in text.

   * Added ‘SphinxDirective.get_source_info()’ and
     ‘SphinxRole.get_source_info()’.

   * #7324: sphinx-build: Emit a warning if multiple files having
     different file extensions for same document found

3.0.0 final

   * Added ‘ObjectDescription.transform_content()’.

11.34.5 Bugs fixed
------------------

3.0.0b1

   * C++, fix cross reference lookup in certain cases involving function
     overloads.

   * #5078: C++, fix cross reference lookup when a directive contains
     multiple declarations.

   * C++, suppress warnings for directly dependent typenames in cross
     references generated automatically in signatures.

   * #5637: autodoc: Incorrect handling of nested class names on
     show-inheritance

   * #7267: autodoc: error message for invalid directive options has
     wrong location

   * #7329: autodoc: info-field-list is wrongly generated from type
     hints into the class description even if
     ‘autoclass_content='class'’ set

   * #7331: autodoc: a cython-function is not recognized as a function

   * #5637: inheritance_diagram: Incorrect handling of nested class
     names

   * #7139: ‘code-block:: guess’ does not work

   * #7325: html: source_suffix containing dot leads to wrong source
     link

   * #7357: html: Resizing SVG image fails with ValueError

   * #7278: html search: Fix use of ‘html_file_suffix’ instead of
     ‘html_link_suffix’ in search results

   * #7297: html theme: ‘bizstyle’ does not support ‘sidebarwidth’

   * #3842: singlehtml: Path to images broken when master doc is not in
     source root

   * #7179: std domain: Fix whitespaces are suppressed on referring
     GenericObject

   * #7289: console: use bright colors instead of bold

   * #1539: C, parse array types.

   * #2377: C, parse function pointers even in complex types.

   * #7345: sphinx-build: Sphinx crashes if output directory exists as a
     file

   * #7290: sphinx-build: Ignore bdb.BdbQuit when handling exceptions

   * #6240: napoleon: Attributes and Methods sections ignore :noindex:
     option

3.0.0 final

   * #7364: autosummary: crashed when autosummary_generate.
     is False

   * #7370: autosummary: raises UnboundLocalError when unknown module
     given

   * #7367: C++, alternate operator spellings are now supported.

   * C, alternate operator spellings are now supported.

   * #7368: C++, comma operator in expressions, pack expansion in
     template argument lists, and more comprehensive error messages in
     some cases.

   * C, C++, fix crash and wrong duplicate warnings related to anon
     symbols.

   * #6477: Escape first “!” in a cross reference linking no longer
     possible

   * #7219: py domain: The index entry generated by ‘py:function’
     directive is different with one from ‘index’ directive with
     “builtin” type

   * #7301: capital characters are not allowed for node_id

   * #7301: epub: duplicated node_ids are generated

   * #6564: html: a width of table was ignored on HTML builder

   * #7401: Incorrect argument is passed for env-get-outdated
     handlers

   * #7355: autodoc: a signature of cython-function is not recognized
     well

   * #7222: autodoc: ‘__wrapped__’ functions are not documented
     correctly

   * #7409: intersphinx: ValueError is raised when an extension sets up
     intersphinx_mapping on config-inited event

   * #7343: Sphinx builds has been slower since 2.4.0 on debug mode

11.35 Release 2.4.5 (released Nov 18, 2021)
===========================================

11.35.1 Dependencies
--------------------

   * #9807: Restrict docutils to 0.17.x or older

11.36 Release 2.4.4 (released Mar 05, 2020)
===========================================

11.36.1 Bugs fixed
------------------

   * #7197: LaTeX: platex cause error to build image directive with
     target url

   * #7223: Sphinx builds has been slower since 2.4.0

11.37 Release 2.4.3 (released Feb 22, 2020)
===========================================

11.37.1 Bugs fixed
------------------

   * #7184: autodoc: ‘*args’ and ‘**kwarg’ in type comments are not
     handled properly

   * #7189: autodoc: classmethod coroutines are not detected

   * #7183: intersphinx: ‘:attr:’ reference to property is broken

   * #6244, #6387: html search: Search breaks/hangs when built with
     dirhtml builder

   * #7195: todo: emit doctree-resolved event with non-document node
     incorrectly

11.38 Release 2.4.2 (released Feb 19, 2020)
===========================================

11.38.1 Bugs fixed
------------------

   * #7138: autodoc: ‘autodoc.typehints’ crashed when variable has
     unbound object as a value

   * #7156: autodoc: separator for keyword only arguments is not shown

   * #7146: autodoc: IndexError is raised on suppressed type_comment
     found

   * #7161: autodoc: typehints extension does not support parallel build

   * #7178: autodoc: TypeError is raised on fetching type annotations

   * #7151: crashed when extension assigns a value to ‘env.indexentries’

   * #7170: text: Remove debug print

   * #7137: viewcode: Avoid to crash when non-python code given

11.39 Release 2.4.1 (released Feb 11, 2020)
===========================================

11.39.1 Bugs fixed
------------------

   * #7120: html: crashed when on scaling SVG images which have float
     dimensions

   * #7126: autodoc: TypeError: ‘getset_descriptor’ object is not
     iterable

11.40 Release 2.4.0 (released Feb 09, 2020)
===========================================

11.40.1 Deprecated
------------------

   * The ‘decode’ argument of ‘sphinx.pycode.ModuleAnalyzer()’

   * ‘sphinx.directives.other.Index’

   * ‘sphinx.environment.temp_data['gloss_entries']’

   * ‘sphinx.environment.BuildEnvironment.indexentries’

   * ‘sphinx.environment.collectors.indexentries.IndexEntriesCollector’

   * ‘sphinx.ext.apidoc.INITPY’

   * ‘sphinx.ext.apidoc.shall_skip()’

   * ‘sphinx.io.FiletypeNotFoundError’

   * ‘sphinx.io.get_filetype()’

   * ‘sphinx.pycode.ModuleAnalyzer.encoding’

   * ‘sphinx.roles.Index’

   * ‘sphinx.util.detect_encoding()’

   * ‘sphinx.util.get_module_source()’

   * ‘sphinx.util.inspect.Signature’

   * ‘sphinx.util.inspect.safe_getmembers()’

   * ‘sphinx.writers.latex.LaTeXTranslator.settings.author’

   * ‘sphinx.writers.latex.LaTeXTranslator.settings.contentsname’

   * ‘sphinx.writers.latex.LaTeXTranslator.settings.docclass’

   * ‘sphinx.writers.latex.LaTeXTranslator.settings.docname’

   * ‘sphinx.writers.latex.LaTeXTranslator.settings.title’

   * ‘sphinx.writers.latex.ADDITIONAL_SETTINGS’

   * ‘sphinx.writers.latex.DEFAULT_SETTINGS’

   * ‘sphinx.writers.latex.LUALATEX_DEFAULT_FONTPKG’

   * ‘sphinx.writers.latex.PDFLATEX_DEFAULT_FONTPKG’

   * ‘sphinx.writers.latex.XELATEX_DEFAULT_FONTPKG’

   * ‘sphinx.writers.latex.XELATEX_GREEK_DEFAULT_FONTPKG’

11.40.2 Features added
----------------------

   * #6910: inheritance_diagram: Make the background of diagrams
     transparent

   * #6446: duration: Add ‘sphinx.ext.durations’ to inspect which
     documents slow down the build

   * #6837: LaTeX: Support a nested table

   * #7115: LaTeX: Allow to override LATEXOPTS and LATEXMKOPTS via
     environment variable

   * #6966: graphviz: Support ‘:class:’ option

   * #6696: html: ‘:scale:’ option of image/figure directive not working
     for SVG images (imagesize-1.2.0 or above is required)

   * #6994: imgconverter: Support illustrator file (.ai) to .png
     conversion

   * autodoc: Support Positional-Only Argument separator (PEP-570
     compliant)

   * autodoc: Support type annotations for variables

   * #2755: autodoc: Add new event:
     autodoc-before-process-signature.

   * #2755: autodoc: Support type_comment style (ex.  ‘# type: (str) ->
     str’) annotation (python3.8+ or typed_ast(1) is required)

   * #7051: autodoc: Support instance variables without defaults
     (PEP-526)

   * #6418: autodoc: Add a new extension ‘sphinx.ext.autodoc.typehints’.
     It shows typehints as object description if ‘autodoc_typehints =
     "description"’ set.  This is an experimental extension and it will
     be integrated into autodoc core in Sphinx-3.0

   * SphinxTranslator now calls visitor/departure method for super node
     class if visitor/departure method for original node class not found

   * #6418: Add new event: object-description-transform.

   * py domain: py;data and py;attribute take
     new options named ‘:type:’ and ‘:value:’ to describe its type and
     initial value

   * #6785: py domain: ‘:py:attr:’ is able to refer properties again

   * #6772: apidoc: Add ‘-q’ option for quiet mode

   ---------- Footnotes ----------

   (1) https://github.com/python/typed_ast

11.40.3 Bugs fixed
------------------

   * #6925: html: Remove redundant type=”text/javascript” from <script>
     elements

   * #7112: html: SVG image is not layouted as float even if aligned

   * #6906, #6907: autodoc: failed to read the source codes encoeded in
     cp1251

   * #6961: latex: warning for babel shown twice

   * #7059: latex: LaTeX compilation falls into infinite loop (wrapfig
     issue)

   * #6581: latex: ‘:reversed:’ option for toctree does not effect to
     LaTeX build

   * #6559: Wrong node-ids are generated in glossary directive

   * #6986: apidoc: misdetects module name for .so file inside module

   * #6899: apidoc: private members are not shown even if ‘--private’
     given

   * #6327: apidoc: Support a python package consisted of __init__.so
     file

   * #6999: napoleon: fails to parse tilde in :exc: role

   * #7019: gettext: Absolute path used in message catalogs

   * #7023: autodoc: nested partial functions are not listed

   * #7023: autodoc: partial functions imported from other modules are
     listed as module members without :impoprted-members: option

   * #6889: autodoc: Trailing comma in ‘:members::’ option causes
     cryptic warning

   * #6568: autosummary: ‘autosummary_imported_members’ is ignored on
     generating a stub file for submodule

   * #7055: linkcheck: redirect is treated as an error

   * #7088: HTML template: If ‘navigation_with_keys’ option is
     activated, modifier keys are ignored, which means the feature can
     interfere with browser features

   * #7090: std domain: Can’t assign numfig-numbers for custom container
     nodes

   * #7106: std domain: enumerated nodes are marked as duplicated when
     extensions call ‘note_explicit_target()’

   * #7095: dirhtml: Cross references are broken via intersphinx and
     ‘:doc:’ role

   * C++:

        - Don’t crash when using the ‘struct’ role in some cases.

        - Don’t warn when using the ‘var’/‘member’ role for function
          parameters.

        - Render call and braced-init expressions correctly.

   * #7097: Filenames of images generated by
     ‘sphinx.transforms.post_transforms.images.ImageConverter’ or its
     subclasses (used for latex build) are now sanitized, to prevent
     broken paths

11.41 Release 2.3.1 (released Dec 22, 2019)
===========================================

11.41.1 Bugs fixed
------------------

   * #6936: sphinx-autogen: raises AttributeError

11.42 Release 2.3.0 (released Dec 15, 2019)
===========================================

11.42.1 Incompatible changes
----------------------------

   * #6742: ‘end-before’ option of literalinclude directive
     does not match the first line of the code block.

   * #1331: Change default User-Agent header to ‘"Sphinx/X.Y.Z
     requests/X.Y.Z python/X.Y.Z"’.  It can be changed via
     user_agent.

   * #6867: text: content of admonitions starts after a blank line

11.42.2 Deprecated
------------------

   * ‘sphinx.builders.gettext.POHEADER’

   * ‘sphinx.io.SphinxStandaloneReader.app’

   * ‘sphinx.io.SphinxStandaloneReader.env’

   * ‘sphinx.util.texescape.tex_escape_map’

   * ‘sphinx.util.texescape.tex_hl_escape_map_new’

   * ‘sphinx.writers.latex.LaTeXTranslator.no_contractions’

11.42.3 Features added
----------------------

   * #6707: C++, support bit-fields.

   * #267: html: Eliminate prompt characters of doctest block from
     copyable text

   * #6548: html: Use favicon for OpenSearch if available

   * #6729: html theme: agogo theme now supports ‘rightsidebar’ option

   * #6780: Add PEP-561 Support

   * #6762: latex: Allow to load additional LaTeX packages via
     ‘extrapackages’ key of latex_elements.

   * #1331: Add new config variable: user_agent.

   * #6000: LaTeX: have backslash also be an inline literal word wrap
     break character

   * #4186: LaTeX: Support upLaTeX as a new latex_engine.
     (experimental)

   * #6812: Improve a warning message when extensions are not parallel
     safe

   * #6818: Improve Intersphinx performance for multiple remote
     inventories.

   * #2546: apidoc: .so file support

   * #6798: autosummary: emit ‘autodoc-skip-member’ event on generating
     stub file

   * #6483: i18n: make explicit titles in toctree translatable

   * #6816: linkcheck: Add linkcheck_auth option to provide
     authentication information when doing ‘linkcheck’ builds

   * #6872: linkcheck: Handles HTTP 308 Permanent Redirect

   * #6613: html: Wrap section number in span tag

   * #6781: gettext: Add ‘gettext_last_translator' and
     :confval:`gettext_language_team’ to customize headers of POT file

11.42.4 Bugs fixed
------------------

   * #6668: LaTeX: Longtable before header has incorrect distance (refs:
     latex3/latex2e#173(1))

   * #6618: LaTeX: Avoid section names at the end of a page

   * #6738: LaTeX: Do not replace unicode characters by LaTeX macros on
     unicode supported LaTeX engines: ¶, §, €, ∞, ±, →, ‣, –,
     superscript and subscript digits go through “as is” (as default
     OpenType font supports them)

   * #6704: linkcheck: Be defensive and handle newly defined HTTP error
     code

   * #6806: linkcheck: Failure on parsing content

   * #6655: image URLs containing ‘data:’ causes gettext builder crashed

   * #6584: i18n: Error when compiling message catalogs on Hindi

   * #6718: i18n: KeyError is raised if section title and table title
     are same

   * #6743: i18n: rst_prolog breaks the translation

   * #6708: mathbase: Some deprecated functions have removed

   * #6709: autodoc: mock object does not work as a class decorator

   * #5070: epub: Wrong internal href fragment links

   * #6712: Allow not to install sphinx.testing as runtime (mainly for
     ALT Linux)

   * #6741: html: search result was broken with empty
     html_file_suffix.

   * #6001: LaTeX does not wrap long code lines at backslash character

   * #6804: LaTeX: PDF build breaks if admonition of danger type
     contains code-block long enough not to fit on one page

   * #6809: LaTeX: code-block in a danger type admonition can easily
     spill over bottom of page

   * #6793: texinfo: Code examples broken following “sidebar”

   * #6813: An orphan warning is emitted for included document on
     Windows.  Thanks to @drillan

   * #6850: Fix smartypants module calls re.sub() with wrong options

   * #6824: HTML search: If a search term is partially matched in the
     title and fully matched in a text paragraph on the same page, the
     search does not include this match.

   * #6848: config.py shouldn’t pop extensions from overrides

   * #6867: text: extra spaces are inserted to hyphenated words on
     folding lines

   * #6886: LaTeX: xelatex converts straight double quotes into right
     curly ones (shows when smartquotes is ‘False’)

   * #6890: LaTeX: even with smartquotes off, PDF output transforms
     straight quotes and consecutive hyphens into curly quotes and
     dashes

   * #6876: LaTeX: multi-line display of authors on title page has
     ragged edges

   * #6887: Sphinx crashes with docutils-0.16b0

   * #6920: sphinx-build: A console message is wrongly highlighted

   * #6900: sphinx-build: ‘-D’ option does not considers ‘0’ and ‘1’ as
     a boolean value

   ---------- Footnotes ----------

   (1) https://github.com/latex3/latex2e/issues/173

11.43 Release 2.2.2 (released Dec 03, 2019)
===========================================

11.43.1 Incompatible changes
----------------------------

   * #6803: For security reason of python, parallel mode is disabled on
     macOS and Python3.8+

11.43.2 Bugs fixed
------------------

   * #6776: LaTeX: 2019-10-01 LaTeX release breaks ‘sphinxcyrillic.sty’

   * #6815: i18n: French, Hindi, Chinese, Japanese and Korean
     translation messages has been broken

   * #6803: parallel build causes AttributeError on macOS and Python3.8

11.44 Release 2.2.1 (released Oct 26, 2019)
===========================================

11.44.1 Bugs fixed
------------------

   * #6641: LaTeX: Undefined control sequence ‘\sphinxmaketitle’

   * #6710: LaTeX not well configured for Greek language as main
     language

   * #6759: validation of html static paths and extra paths no longer
     throws an error if the paths are in different directories

11.45 Release 2.2.0 (released Aug 19, 2019)
===========================================

11.45.1 Incompatible changes
----------------------------

   * apidoc: template files are renamed to ‘.rst_t’

   * html: Field lists will be styled by grid layout

11.45.2 Deprecated
------------------

   * ‘sphinx.domains.math.MathDomain.add_equation()’

   * ‘sphinx.domains.math.MathDomain.get_next_equation_number()’

   * The ‘info’ and ‘warn’ arguments of
     ‘sphinx.ext.autosummary.generate.generate_autosummary_docs()’

   * ‘sphinx.ext.autosummary.generate._simple_info()’

   * ‘sphinx.ext.autosummary.generate._simple_warn()’

   * ‘sphinx.ext.todo.merge_info()’

   * ‘sphinx.ext.todo.process_todo_nodes()’

   * ‘sphinx.ext.todo.process_todos()’

   * ‘sphinx.ext.todo.purge_todos()’

11.45.3 Features added
----------------------

   * #5124: graphviz: ‘:graphviz_dot:’ option is renamed to ‘:layout:’

   * #1464: html: emit a warning if html_static_path and
     html_extra_path directories are inside output directory

   * #6514: html: Add a label to search input for accessability purposes

   * #5602: apidoc: Add ‘--templatedir’ option

   * #6475: Add ‘override’ argument to ‘app.add_autodocumenter()’

   * #6310: imgmath: let imgmath_use_preview work also with
     the SVG format for images rendering inline math

   * #6533: LaTeX: refactor visit_enumerated_list() to use
     ‘\sphinxsetlistlabels’

   * #6628: quickstart: Use ‘https://docs.python.org/3/’ for default
     setting of intersphinx_mapping.

   * #6419: sphinx-build: give reasons why rebuilt

11.45.4 Bugs fixed
------------------

   * py domain: duplicated warning does not point the location of source
     code

   * #6499: html: Sphinx never updates a copy of html_logo.
     even if original file has changed

   * #1125: html theme: scrollbar is hard to see on classic theme and
     macOS

   * #5502: linkcheck: Consider HTTP 503 response as not an error

   * #6439: Make generated download links reproducible

   * #6486: UnboundLocalError is raised if broken extension installed

   * #6567: autodoc: autodoc_inherit_docstrings does not
     effect to ‘__init__()’ and ‘__new__()’

   * #6574: autodoc: autodoc_member_order does not refer
     order of imports when ‘'bysource'’ order

   * #6574: autodoc: missing type annotation for variadic and keyword
     parameters

   * #6589: autodoc: Formatting issues with autodoc_typehints=’none’

   * #6605: autodoc: crashed when target code contains custom
     method-like objects

   * #6498: autosummary: crashed with wrong autosummary_generate setting

   * #6507: autosummary: crashes without no autosummary_generate setting

   * #6511: LaTeX: autonumbered list can not be customized in LaTeX
     since Sphinx 1.8.0 (refs: #6533)

   * #6531: Failed to load last environment object when extension added

   * #736: Invalid sort in pair index

   * #6527: ‘last_updated’ wrongly assumes timezone as UTC

   * #5592: std domain: option directive registers an index
     entry for each comma separated option

   * #6549: sphinx-build: Escaped characters in error messages

   * #6545: doctest comments not getting trimmed since Sphinx 1.8.0

   * #6561: glossary: Wrong hyperlinks are generated for non
     alphanumeric terms

   * #6620: i18n: classifiers of definition list are not translated with
     docutils-0.15

   * #6474: ‘DocFieldTransformer’ raises AttributeError when given
     directive is not a subclass of ObjectDescription

11.46 Release 2.1.2 (released Jun 19, 2019)
===========================================

11.46.1 Bugs fixed
------------------

   * #6497: custom lexers fails highlighting when syntax error

   * #6478, #6488: info field lists are incorrectly recognized

11.47 Release 2.1.1 (released Jun 10, 2019)
===========================================

11.47.1 Incompatible changes
----------------------------

   * #6447: autodoc: Stop to generate document for undocumented module
     variables

11.47.2 Bugs fixed
------------------

   * #6442: LaTeX: admonitions of note type can get separated
     from immediately preceding section title by pagebreak

   * #6448: autodoc: crashed when autodocumenting classes with
     ‘__slots__ = None’

   * #6451: autodoc: generates docs for “optional import”ed modules as
     variables

   * #6452: autosummary: crashed when generating document of properties

   * #6455: napoleon: docstrings for properties are not processed

   * #6436: napoleon: “Unknown target name” error if variable name ends
     with underscore

   * #6440: apidoc: missing blank lines between modules

11.48 Release 2.1.0 (released Jun 02, 2019)
===========================================

11.48.1 Incompatible changes
----------------------------

   * Ignore filenames without file extension given to
     ‘Builder.build_specific()’ API directly

   * #6230: The anchor of term in glossary directive is changed if it is
     consisted by non-ASCII characters

   * #4550: html: Centering tables by default using CSS

   * #6239: latex: xelatex and xeCJK are used for Chinese documents by
     default

   * ‘Sphinx.add_lexer()’ now takes a Lexer class instead of instance.
     An instance of lexers are still supported until Sphinx-3.x.

11.48.2 Deprecated
------------------

   * ‘sphinx.builders.latex.LaTeXBuilder.apply_transforms()’

   * ‘sphinx.builders._epub_base.EpubBuilder.esc()’

   * ‘sphinx.directives.Acks’

   * ‘sphinx.directives.Author’

   * ‘sphinx.directives.Centered’

   * ‘sphinx.directives.Class’

   * ‘sphinx.directives.CodeBlock’

   * ‘sphinx.directives.Figure’

   * ‘sphinx.directives.HList’

   * ‘sphinx.directives.Highlight’

   * ‘sphinx.directives.Include’

   * ‘sphinx.directives.Index’

   * ‘sphinx.directives.LiteralInclude’

   * ‘sphinx.directives.Meta’

   * ‘sphinx.directives.Only’

   * ‘sphinx.directives.SeeAlso’

   * ‘sphinx.directives.TabularColumns’

   * ‘sphinx.directives.TocTree’

   * ‘sphinx.directives.VersionChange’

   * ‘sphinx.domains.python.PyClassmember’

   * ‘sphinx.domains.python.PyModulelevel’

   * ‘sphinx.domains.std.StandardDomain._resolve_citation_xref()’

   * ‘sphinx.domains.std.StandardDomain.note_citations()’

   * ‘sphinx.domains.std.StandardDomain.note_citation_refs()’

   * ‘sphinx.domains.std.StandardDomain.note_labels()’

   * ‘sphinx.environment.NoUri’

   * ‘sphinx.ext.apidoc.format_directive()’

   * ‘sphinx.ext.apidoc.format_heading()’

   * ‘sphinx.ext.apidoc.makename()’

   * ‘sphinx.ext.autodoc.importer.MockFinder’

   * ‘sphinx.ext.autodoc.importer.MockLoader’

   * ‘sphinx.ext.autodoc.importer.mock()’

   * ‘sphinx.ext.autosummary.autolink_role()’

   * ‘sphinx.ext.imgmath.DOC_BODY’

   * ‘sphinx.ext.imgmath.DOC_BODY_PREVIEW’

   * ‘sphinx.ext.imgmath.DOC_HEAD’

   * ‘sphinx.transforms.CitationReferences’

   * ‘sphinx.transforms.SmartQuotesSkipper’

   * ‘sphinx.util.docfields.DocFieldTransformer.preprocess_fieldtypes()’

   * ‘sphinx.util.node.find_source_node()’

   * ‘sphinx.util.i18n.find_catalog()’

   * ‘sphinx.util.i18n.find_catalog_files()’

   * ‘sphinx.util.i18n.find_catalog_source_files()’

For more details, see deprecation APIs list.

11.48.3 Features added
----------------------

   * Add a helper class
     ‘sphinx.transforms.post_transforms.SphinxPostTransform’

   * Add helper methods

        - ‘PythonDomain.note_module()’

        - ‘PythonDomain.note_object()’

        - ‘SphinxDirective.set_source_info()’

   * #6180: Support ‘--keep-going’ with BuildDoc setup command

   * ‘math’ directive now supports ‘:class:’ option

   * todo: ‘todo’ directive now supports ‘:name:’ option

   * Enable override via environment of ‘SPHINXOPTS’ and ‘SPHINXBUILD’
     Makefile variables (refs: #6232, #6303)

   * #6287: autodoc: Unable to document bound instance methods exported
     as module functions

   * #6289: autodoc: autodoc_default_options now supports
     ‘imported-members’ option

   * #4777: autodoc: Support coroutine

   * #744: autodoc: Support abstractmethod

   * #6325: autodoc: Support attributes in __slots__.  For dict-style
     __slots__, autodoc considers values as a docstring of the attribute

   * #6361: autodoc: Add autodoc_typehints to suppress
     typehints from signature

   * #1063: autodoc: ‘automodule’ directive now handles undocumented
     module level variables

   * #6212 autosummary: Add autosummary_imported_members to
     display imported members on autosummary

   * #6271: ‘make clean’ is catastrophically broken if building into ‘.’

   * #6363: Support ‘%O%’ environment variable in make.bat

   * #4777: py domain: Add ‘:async:’ option to py;function.
     directive

   * py domain: Add new options to py;method directive

        - ‘:abstractmethod:’

        - ‘:async:’

        - ‘:classmethod:’

        - ‘:property:’

        - ‘:staticmethod:’

   * rst domain: Add ‘directive:option’ directive to describe the option
     for directive

   * #6306: html: Add a label to search form for accessability purposes

   * #4390: html: Consistent and semantic CSS for signatures

   * #6358: The ‘rawsource’ property of ‘production’ nodes now contains
     the full production rule

   * #6373: autosectionlabel: Allow suppression of warnings

   * coverage: Support a new ‘coverage_ignore_pyobjects’ option

   * #6239: latex: Support to build Chinese documents

11.48.4 Bugs fixed
------------------

   * #6230: Inappropriate node_id has been generated by glossary
     directive if term is consisted by non-ASCII characters

   * #6213: ifconfig: contents after headings are not shown

   * commented term in glossary directive is wrongly recognized

   * #6299: rst domain: rst:directive directive generates waste space

   * #6379: py domain: Module index (py-modindex.html) has duplicate
     titles

   * #6331: man: invalid output when doctest follows rubric

   * #6351: “Hyperlink target is not referenced” message is shown even
     if referenced

   * #6165: autodoc: ‘tab_width’ setting of docutils has been ignored

   * #6347: autodoc: crashes with a plain Tuple on Python 3.6 and 3.5

   * #6311: autosummary: autosummary table gets confused by complex type
     hints

   * #6350: autosummary: confused by an argument having some kind of
     default value

   * Generated Makefiles lack a final EOL (refs: #6232)

   * #6375: extlinks: Cannot escape angle brackets in link caption

   * #6378: linkcheck: Send commonly used User-Agent

   * #6387: html search: failed to search document with haiku and
     scrolls themes

   * #6408: html search: Fix the ranking of search results

   * #6406: Wrong year is returned for ‘SOURCE_DATE_EPOCH’

   * #6402: image directive crashes by unknown image format

   * #6286: C++, allow 8 and 9 in hexadecimal integer literals.

   * #6305: Fix the string in quickstart for ‘path’ argument of parser

   * LaTeX: Figures in admonitions produced errors (refs: #6364)

11.49 Release 2.0.1 (released Apr 08, 2019)
===========================================

11.49.1 Bugs fixed
------------------

   * LaTeX: some system labels are not translated

   * RemovedInSphinx30Warning is marked as pending

   * deprecation warnings are not emitted

        - sphinx.application.CONFIG_FILENAME

        - sphinx.builders.htmlhelp

        - ‘viewcode_import’

   * #6208: C++, properly parse full xrefs that happen to have a short
     xref as prefix

   * #6220, #6225: napoleon: AttributeError is raised for raised section
     having references

   * #6245: circular import error on importing SerializingHTMLBuilder

   * #6243: LaTeX: ‘releasename’ setting for latex_elements is ignored

   * #6244: html: Search function is broken with 3rd party themes

   * #6263: html: HTML5Translator crashed with invalid field node

   * #6262: html theme: The style of field lists has changed in bizstyle
     theme

11.50 Release 2.0.0 (released Mar 29, 2019)
===========================================

11.50.1 Dependencies
--------------------

2.0.0b1

   * LaTeX builder now depends on TeX Live 2015 or above.

   * LaTeX builder (with ‘'pdflatex'’ latex_engine) will
     process Unicode Greek letters in text (not in math mark-up) via the
     text font and will not escape them to math mark-up.  See the
     discussion of the ‘'fontenc'’ key of latex_elements.;
     such (optional) support for Greek adds, for example on Ubuntu
     xenial, the ‘texlive-lang-greek’ and (if default font set-up is not
     modified) ‘cm-super(-minimal)’ as additional Sphinx LaTeX
     requirements.

   * LaTeX builder with latex_engine set to ‘'xelatex'’ or
     to ‘'lualatex'’ requires (by default) the ‘FreeFont’ fonts, which
     in Ubuntu xenial are provided by package ‘fonts-freefont-otf’, and
     e.g.  in Fedora 29 via package ‘texlive-gnu-freefont’.

   * requests 2.5.0 or above

   * The six package is no longer a dependency

   * The sphinxcontrib-websupport package is no longer a dependency

   * Some packages are separated to sub packages:

        - sphinxcontrib.applehelp

        - sphinxcontrib.devhelp

        - sphinxcontrib.htmlhelp

        - sphinxcontrib.jsmath

        - sphinxcontrib.serializinghtml

        - sphinxcontrib.qthelp

11.50.2 Incompatible changes
----------------------------

2.0.0b1

   * Drop python 2.7 and 3.4 support

   * Drop docutils 0.11 support

   * Drop features and APIs deprecated in 1.7.x

   * The default setting for master_doc is changed to
     ‘'index'’ which has been longly used as default of
     sphinx-quickstart.

   * LaTeX: Move message resources to ‘sphinxmessage.sty’

   * LaTeX: Stop using ‘\captions<lang>’ macro for some labels

   * LaTeX: for ‘'xelatex'’ and ‘'lualatex'’, use the ‘FreeFont’
     OpenType fonts as default choice (refs: #5645)

   * LaTeX: ‘'xelatex'’ and ‘'lualatex'’ now use ‘\small’ in code-blocks
     (due to ‘FreeMono’ character width) like ‘'pdflatex'’ already did
     (due to ‘Courier’ character width).  You may need to adjust this
     via latex_elements. ‘'fvset'’ key, in case of usage of
     some other OpenType fonts (refs: #5768)

   * LaTeX: Greek letters in text are not escaped to math mode mark-up,
     and they will use the text font not the math font.  The ‘LGR’ font
     encoding must be added to the ‘'fontenc'’ key of
     latex_elements for this to work (only if it is needed by the
     document, of course).

   * LaTeX: setting the language to ‘'en'’ triggered ‘Sonny’
     option of ‘fncychap’, now it is ‘Bjarne’ to match case of no
     language specified.  (refs: #5772)

   * #5770: doctest: Follow highlight_language on
     highlighting doctest block.  As a result, they are highlighted as
     python3 by default.

   * The order of argument for ‘HTMLTranslator’, ‘HTML5Translator’ and
     ‘ManualPageTranslator’ are changed

   * LaTeX: hard-coded redefinitions of ‘\l@section’ and ‘\l@subsection’
     formerly done during loading of ‘'manual'’ docclass get executed
     later, at time of ‘\sphinxtableofcontents’.  This means that custom
     user definitions from LaTeX preamble now get overwritten.  Use
     ‘\sphinxtableofcontentshook’ to insert custom user definitions.
     See Macros.

   * quickstart: Simplify generated ‘conf.py’

   * #4148: quickstart: some questions are removed.  They are still able
     to specify via command line options

   * websupport: unbundled from sphinx core.  Please use
     sphinxcontrib-websupport

   * C++, the visibility of base classes is now always rendered as
     present in the input.  That is, ‘private’ is now shown, where it
     was ellided before.

   * LaTeX: graphics inclusion of oversized images rescales to not
     exceed the text width and height, even if width and/or height
     option were used.  (refs: #5956)

   * epub: ‘epub_title’ defaults to the project option

   * #4550: All tables and figures without ‘align’ option are displayed
     to center

   * #4587: html: Output HTML5 by default

2.0.0b2

   * texinfo: image files are copied into ‘name-figure’ directory

11.50.3 Deprecated
------------------

2.0.0b1

   * Support for evaluating Python 2 syntax is deprecated.  This
     includes configuration files which should be converted to Python 3.

   * The arguments of ‘EpubBuilder.build_mimetype()’,
     ‘EpubBuilder.build_container()’, ‘EpubBuilder.bulid_content()’,
     ‘EpubBuilder.build_toc()’ and ‘EpubBuilder.build_epub()’

   * The arguments of ‘Epub3Builder.build_navigation_doc()’

   * The config variables

        - html_experimental_html5_writer.

   * The ‘encoding’ argument of ‘autodoc.Documenter.get_doc()’,
     ‘autodoc.DocstringSignatureMixin.get_doc()’,
     ‘autodoc.DocstringSignatureMixin._find_signature()’, and
     ‘autodoc.ClassDocumenter.get_doc()’ are deprecated.

   * The ‘importer’ argument of
     ‘sphinx.ext.autodoc.importer._MockModule’

   * The ‘nodetype’ argument of ‘sphinx.search.WordCollector.
     is_meta_keywords()’

   * The ‘suffix’ argument of ‘env.doc2path()’ is deprecated.

   * The string style ‘base’ argument of ‘env.doc2path()’ is deprecated.

   * The fallback to allow omitting the ‘filename’ argument from an
     overridden ‘IndexBuilder.feed()’ method is deprecated.

   * ‘sphinx.addnodes.abbreviation’

   * ‘sphinx.application.Sphinx._setting_up_extension’

   * ‘sphinx.builders.epub3.Epub3Builder.validate_config_value()’

   * ‘sphinx.builders.html.SingleFileHTMLBuilder’

   * ‘sphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()’

   * ‘sphinx.cmd.quickstart.term_decode()’

   * ‘sphinx.cmd.quickstart.TERM_ENCODING’

   * ‘sphinx.config.check_unicode()’

   * ‘sphinx.config.string_classes’

   * ‘sphinx.domains.cpp.DefinitionError.description’

   * ‘sphinx.domains.cpp.NoOldIdError.description’

   * ‘sphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded’

   * ‘sphinx.ext.autodoc.importer._MockImporter’

   * ‘sphinx.ext.autosummary.Autosummary.warn()’

   * ‘sphinx.ext.autosummary.Autosummary.genopt’

   * ‘sphinx.ext.autosummary.Autosummary.warnings’

   * ‘sphinx.ext.autosummary.Autosummary.result’

   * ‘sphinx.ext.doctest.doctest_encode()’

   * ‘sphinx.io.SphinxBaseFileInput’

   * ‘sphinx.io.SphinxFileInput.supported’

   * ‘sphinx.io.SphinxRSTFileInput’

   * ‘sphinx.registry.SphinxComponentRegistry.add_source_input()’

   * ‘sphinx.roles.abbr_role()’

   * ‘sphinx.roles.emph_literal_role()’

   * ‘sphinx.roles.menusel_role()’

   * ‘sphinx.roles.index_role()’

   * ‘sphinx.roles.indexmarkup_role()’

   * ‘sphinx.testing.util.remove_unicode_literal()’

   * ‘sphinx.util.attrdict’

   * ‘sphinx.util.force_decode()’

   * ‘sphinx.util.get_matching_docs()’

   * ‘sphinx.util.inspect.Parameter’

   * ‘sphinx.util.jsonimpl’

   * ‘sphinx.util.osutil.EEXIST’

   * ‘sphinx.util.osutil.EINVAL’

   * ‘sphinx.util.osutil.ENOENT’

   * ‘sphinx.util.osutil.EPIPE’

   * ‘sphinx.util.osutil.walk()’

   * ‘sphinx.util.PeekableIterator’

   * ‘sphinx.util.pycompat.NoneType’

   * ‘sphinx.util.pycompat.TextIOWrapper’

   * ‘sphinx.util.pycompat.UnicodeMixin’

   * ‘sphinx.util.pycompat.htmlescape’

   * ‘sphinx.util.pycompat.indent’

   * ‘sphinx.util.pycompat.sys_encoding’

   * ‘sphinx.util.pycompat.terminal_safe()’

   * ‘sphinx.util.pycompat.u’

   * ‘sphinx.writers.latex.ExtBabel’

   * ‘sphinx.writers.latex.LaTeXTranslator._make_visit_admonition()’

   * ‘sphinx.writers.latex.LaTeXTranslator.babel_defmacro()’

   * ‘sphinx.writers.latex.LaTeXTranslator.collect_footnotes()’

   * ‘sphinx.writers.latex.LaTeXTranslator.generate_numfig_format()’

   * ‘sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()’

   * ‘sphinx.writers.text.TextTranslator._make_depart_admonition()’

   * template variables for LaTeX template

        - ‘logo’

        - ‘numfig_format’

        - ‘pageautorefname’

        - ‘translatablestrings’

For more details, see deprecation APIs list.

11.50.4 Features added
----------------------

2.0.0b1

   * #1618: The search results preview of generated HTML documentation
     is reader-friendlier: instead of showing the snippets as raw
     reStructuredText markup, Sphinx now renders the corresponding HTML.
     This means the Sphinx extension Sphinx: pretty search results(1) is
     no longer necessary.  Note that changes to the search function of
     your custom or 3rd-party HTML template might overwrite this
     improvement.

   * #4182: autodoc: Support suppress_warnings.

   * #5533: autodoc: autodoc_default_options supports
     ‘member-order’

   * #5394: autodoc: Display readable names in type annotations for
     mocked objects

   * #5459: autodoc: autodoc_default_options accepts ‘True’
     as a value

   * #1148: autodoc: Add autodecorator directive for
     decorators

   * #5635: autosummary: Add autosummary_mock_imports to
     mock external libraries on importing targets

   * #4018: htmlhelp: Add htmlhelp_file_suffix and
     htmlhelp_link_suffix.

   * #5559: text: Support complex tables (colspan and rowspan)

   * LaTeX: support rendering (not in math, yet) of Greek and Cyrillic
     Unicode letters in non-Cyrillic document even with ‘'pdflatex'’ as
     latex_engine. (refs: #5645)

   * #5660: The ‘versionadded’, ‘versionchanged’ and ‘deprecated’
     directives are now generated with their own specific CSS classes
     (‘added’, ‘changed’ and ‘deprecated’, respectively) in addition to
     the generic ‘versionmodified’ class.

   * #5841: apidoc: Add –extensions option to sphinx-apidoc

   * #4981: C++, added an alias directive for inserting lists of
     declarations, that references existing declarations (e.g., for
     making a synopsis).

   * C++: add ‘cpp:struct’ to complement ‘cpp:class’.

   * #1341 the HTML search considers words that contain a search term of
     length three or longer a match.

   * #4611: epub: Show warning for duplicated ToC entries

   * #1851: Allow to omit an argument for code-block.
     directive.  If omitted, it follows highlight or
     highlight_language.

   * #4587: html: Add html4_writer to use old HTML4 writer

   * #6016: HTML search: A placeholder for the search summary prevents
     search result links from changing their position when the search
     terminates.  This makes navigating search results easier.

   * #5196: linkcheck also checks remote images exist

   * #5924: githubpages: create CNAME file for custom domains when
     html_baseurl set

   * #4261: autosectionlabel: restrict the labeled sections by new
     config value; see autosectionlabel_maxdepth.

   ---------- Footnotes ----------

   (1) https://github.com/sphinx-contrib/sphinx-pretty-searchresults

11.50.5 Bugs fixed
------------------

2.0.0b1

   * #1682: LaTeX: writer should not translate Greek unicode, but use
     textgreek package

   * #5247: LaTeX: PDF does not build with default font config for
     Russian language and ‘'xelatex'’ or ‘'lualatex'’ as
     latex_engine. (refs: #5251)

   * #5248: LaTeX: Greek letters in section titles disappear from PDF
     bookmarks

   * #5249: LaTeX: Unicode Greek letters in math directive break PDF
     build (fix requires extra set-up, see latex_elements.
     ‘'textgreek'’ key and/or latex_engine setting)

   * #5772: LaTeX: should the Bjarne style of fncychap be used for
     English also if passed as language option?

   * #5179: LaTeX: (lualatex only) escaping of ‘>’ by ‘\textgreater{}’
     is not enough as ‘\textgreater{}\textgreater{}’ applies
     TeX-ligature

   * LaTeX: project name is not escaped if latex_documents.
     omitted

   * LaTeX: authors are not shown if latex_documents omitted

   * HTML: Invalid HTML5 file is generated for a glossary having
     multiple terms for one description (refs: #4611)

   * QtHelp: OS dependent path separator is used in .qhp file

   * HTML search: search always returns nothing when multiple search
     terms are used and one term is shorter than three characters

2.0.0b2

   * #6096: html: Anchor links are not added to figures

   * #3620: html: Defer searchindex.js rather than loading it via ajax

   * #6113: html: Table cells and list items have large margins

   * #5508: ‘linenothreshold’ option for ‘highlight’ directive was
     ignored

   * texinfo: ‘make install-info’ causes syntax error

   * texinfo: ‘make install-info’ fails on macOS

   * #3079: texinfo: image files are not copied on ‘make install-info’

   * #5391: A cross reference in heading is rendered as literal

   * #5946: C++, fix ‘cpp:alias’ problems in LaTeX (and singlehtml)

   * #6147: classes attribute of ‘citation_reference’ node is lost

   * AssertionError is raised when custom ‘citation_reference’ node
     having classes attribute refers missing citation (refs: #6147)

   * #2155: Support ‘code’ directive

   * C++, fix parsing of braced initializers.

   * #6172: AttributeError is raised for old styled index nodes

   * #4872: inheritance_diagram: correctly describe behavior of ‘parts’
     option in docs, allow negative values.

   * #6178: i18n: Captions missing in translations for hidden TOCs

2.0.0 final

   * #6196: py domain: unexpected prefix is generated

11.50.6 Testing
---------------

2.0.0b1

   * Stop to use ‘SPHINX_TEST_TEMPDIR’ envvar

2.0.0b2

   * Add a helper function: ‘sphinx.testing.restructuredtext.parse()’

11.51 Release 1.8.6 (released Nov 18, 2021)
===========================================

11.51.1 Dependencies
--------------------

   * #9807: Restrict docutils to 0.17.x or older

11.52 Release 1.8.5 (released Mar 10, 2019)
===========================================

11.52.1 Bugs fixed
------------------

   * LaTeX: Remove extraneous space after author names on PDF title page
     (refs: #6004)

   * #6026: LaTeX: A cross reference to definition list does not work

   * #6046: LaTeX: ‘TypeError’ is raised when invalid latex_elements
     given

   * #6067: LaTeX: images having a target are concatenated to next line

   * #6067: LaTeX: images having a target are not aligned even if
     specified

   * #6149: LaTeX: ‘:index:’ role in titles causes ‘Use of \@icentercr
     doesn't match its definition’ error on latexpdf build

   * #6019: imgconverter: Including multipage PDF fails

   * #6047: autodoc: ‘autofunction’ emits a warning for method objects

   * #6028: graphviz: Ensure the graphviz filenames are reproducible

   * #6068: doctest: ‘skipif’ option may remove the code block from
     documentation

   * #6136: ‘:name:’ option for ‘math’ directive causes a crash

   * #6139: intersphinx: ValueError on failure reporting

   * #6135: changes: Fix UnboundLocalError when any module found

   * #3859: manpage: code-block captions are not displayed correctly

11.53 Release 1.8.4 (released Feb 03, 2019)
===========================================

11.53.1 Bugs fixed
------------------

   * #3707: latex: no bold checkmark (✔) available.

   * #5605: with the documentation language set to Chinese, English
     words could not be searched.

   * #5889: LaTeX: user ‘numfig_format’ is stripped of spaces and may
     cause build failure

   * C++, fix hyperlinks for declarations involving east cv-qualifiers.

   * #5755: C++, fix duplicate declaration error on function templates
     with constraints in the return type.

   * C++, parse unary right fold expressions and binary fold
     expressions.

   * pycode could not handle egg files on windows

   * #5928: KeyError: ‘DOCUTILSCONFIG’ when running build

   * #5936: LaTeX: PDF build broken by inclusion of image taller than
     page height in an admonition

   * #5231: “make html” does not read and build “po” files in “locale”
     dir

   * #5954: ‘:scale:’ image option may break PDF build if image in an
     admonition

   * #5966: mathjax has not been loaded on incremental build

   * #5960: LaTeX: modified PDF layout since September 2018 TeXLive
     update of ‘parskip.sty’

   * #5948: LaTeX: duplicated labels are generated for sections

   * #5958: versionadded directive causes crash with Python 3.5.0

   * #5995: autodoc: autodoc_mock_imports conflict with metaclass on
     Python 3.7

   * #5871: texinfo: a section title ‘.’ is not allowed

11.54 Release 1.8.3 (released Dec 26, 2018)
===========================================

11.54.1 Features added
----------------------

   * LaTeX: it is possible to insert custom material to appear on back
     of title page, see discussion of ‘'maketitle'’ key of
     latex_elements. (‘'manual'’ docclass only)

11.54.2 Bugs fixed
------------------

   * #5725: mathjax: Use CDN URL for “latest” version by default

   * #5460: html search does not work with some 3rd party themes

   * #5520: LaTeX, caption package incompatibility since Sphinx 1.6

   * #5614: autodoc: incremental build is broken when builtin modules
     are imported

   * #5627: qthelp: index.html missing in QtHelp

   * #5659: linkcheck: crashes for a hyperlink containing multibyte
     character

   * #5754: DOC: Fix some mistakes in LaTeX customization.

   * #5810: LaTeX: sphinxVerbatim requires explicit “hllines” set-up
     since 1.6.6 (refs: #1238)

   * #5636: C++, fix parsing of floating point literals.

   * #5496 (again): C++, fix assertion in partial builds with
     duplicates.

   * #5724: quickstart: sphinx-quickstart fails when $LC_ALL is empty

   * #1956: Default conf.py is not PEP8-compliant

   * #5849: LaTeX: document class ‘\maketitle’ is overwritten with no
     possibility to use original meaning in place of Sphinx custom one

   * #5834: apidoc: wrong help for ‘--tocfile’

   * #5800: todo: crashed if todo is defined in TextElement

   * #5846: htmlhelp: convert hex escaping to decimal escaping in
     .hhc/.hhk files

   * htmlhelp: broken .hhk file generated when title contains a double
     quote

11.55 Release 1.8.2 (released Nov 11, 2018)
===========================================

11.55.1 Incompatible changes
----------------------------

   * #5497: Do not include MathJax.js and jsmath.js unless it is really
     needed

11.55.2 Features added
----------------------

   * #5471: Show appropriate deprecation warnings

11.55.3 Bugs fixed
------------------

   * #5490: latex: enumerated list causes a crash with recommonmark

   * #5492: sphinx-build fails to build docs w/ Python < 3.5.2

   * #3704: latex: wrong ‘\label’ positioning for figures with a legend

   * #5496: C++, fix assertion when a symbol is declared more than
     twice.

   * #5493: gettext: crashed with broken template

   * #5495: csv-table directive with file option in included file is
     broken (refs: #4821)

   * #5498: autodoc: unable to find type hints for a ‘functools.partial’

   * #5480: autodoc: unable to find type hints for unresolvable Forward
     references

   * #5419: incompatible math_block node has been generated

   * #5548: Fix ensuredir() in case of pre-existing file

   * #5549: graphviz Correctly deal with non-existing static dir

   * #3002: i18n: multiple footnote_references referring same footnote
     cause duplicated node_ids

   * #5563: latex: footnote_references generated by extension causes a
     LaTeX builder crash

   * #5561: make all-pdf fails with old xindy version

   * #5557: quickstart: –no-batchfile isn’t honored

   * #3080: texinfo: multiline rubrics are broken

   * #3080: texinfo: multiline citations are broken

11.56 Release 1.8.1 (released Sep 22, 2018)
===========================================

11.56.1 Incompatible changes
----------------------------

   * LaTeX ‘\pagestyle’ commands have been moved to the LaTeX template.
     No changes in PDF, except possibly if ‘\sphinxtableofcontents’,
     which contained them, had been customized in ‘conf.py’.  (refs:
     #5455)

11.56.2 Bugs fixed
------------------

   * #5418: Incorrect default path for sphinx-build -d/doctrees files

   * #5421: autodoc emits deprecation warning for
     autodoc_default_flags.

   * #5422: lambda object causes PicklingError on storing environment

   * #5417: Sphinx fails to build with syntax error in Python 2.7.5

   * #4911: add latexpdf to make.bat for non make-mode

   * #5436: Autodoc does not work with enum subclasses with
     properties/methods

   * #5437: autodoc: crashed on modules importing eggs

   * #5433: latex: ImportError: cannot import name ‘DEFAULT_SETTINGS’

   * #5431: autodoc: ‘autofunction’ emits a warning for callable objects

   * #5457: Fix TypeError in error message when override is prohibited

   * #5453: PDF builds of ‘howto’ documents have no page numbers

   * #5463: mathbase: math_role and MathDirective was disappeared in
     1.8.0

   * #5454: latex: Index has disappeared from PDF for Japanese documents

   * #5432: py domain: ‘:type:’ field can’t process ‘:term:’ references

   * #5426: py domain: TypeError has been raised for class attribute

11.57 Release 1.8.0 (released Sep 13, 2018)
===========================================

11.57.1 Dependencies
--------------------

1.8.0b1

   * LaTeX: latex_use_xindy, if ‘True’ (default for
     ‘xelatex/lualatex’), instructs ‘make latexpdf’ to use ‘xindy’ for
     general index.  Make sure your LaTeX distribution includes it.
     (refs: #5134)

   * LaTeX: ‘latexmk’ is required for ‘make latexpdf’ on Windows

11.57.2 Incompatible changes
----------------------------

1.8.0b2

   * #5282: html theme: refer ‘pygments_style’ settings of HTML themes
     preferentially

   * The URL of download files are changed

   * #5127: quickstart: ‘Makefile’ and ‘make.bat’ are not overwritten if
     exists

1.8.0b1

   * #5156: the ‘sphinx.ext.graphviz: extension runs `dot’ in the
     directory of the document being built instead of in the root
     directory of the documentation.

   * #4460: extensions which stores any data to environment should
     return the version of its env data structure as metadata.  In
     detail, please see Extension metadata.

   * Sphinx expects source parser modules to have supported file formats
     as ‘Parser.supported’ attribute

   * The default value of epub_author and
     epub_publisher are changed from ‘'unknown'’ to the value of
     author.  This is same as a ‘conf.py’ file sphinx-build
     generates.

   * The ‘gettext_compact’ attribute is removed from ‘document.settings’
     object.  Please use ‘config.gettext_compact’ instead.

   * The processing order on reading phase is changed.  smart_quotes,
     sphinx domains, see doctree-read event and versioning
     doctrees are invoked earlier than so far.  For more details, please
     read a description of Sphinx.add_transform().

   * #4827: All ‘substitution_definition’ nodes are removed from doctree
     on reading phase

   * ‘docutils.conf’ in ‘$HOME’ or ‘/etc’ directories are ignored.  Only
     ‘docutils.conf’ from confdir is obeyed.

   * #789: ‘:samp:’ role supports to escape curly braces with backslash

   * #4811: The files under html_static_path are excluded
     from source files.

   * latex: Use ‘\sphinxcite’ for citation references instead
     ‘\hyperref’

   * The config value ‘viewcode_import’ is renamed to
     viewcode_follow_imported_members. (refs: #4035)

   * #1857: latex: latex_show_pagerefs does not add pagerefs
     for citations

   * #4648: latex: Now “rubric” elements are rendered as unnumbered
     section title

   * #4983: html: The anchor for productionlist tokens has been changed

   * Modifying a template variable ‘script_files’ in templates is
     allowed now.  Please use ‘app.add_js_file()’ instead.

   * #5072: Save environment object also with only new documents

   * #5035: qthelp builder allows dashes in qthelp_namespace.

   * LaTeX: with lualatex or xelatex use by default ‘xindy’ as UTF-8
     able replacement of ‘makeindex’ (refs: #5134).  After upgrading
     Sphinx, please clean latex build repertory of existing project
     before new build.

   * #5163: html: hlist items are now aligned to top

   * ‘highlightlang’ directive is processed on resolving phase

   * #4000: LaTeX: template changed.  Following elements moved to it:

        - ‘\begin{document}’

        - ‘shorthandoff’ variable

        - ‘maketitle’ variable

        - ‘tableofcontents’ variable

11.57.3 Deprecated
------------------

1.8.0b2

   * ‘sphinx.io.SphinxI18nReader.set_lineno_for_reporter()’ is
     deprecated

   * ‘sphinx.io.SphinxI18nReader.line’ is deprecated

   * ‘sphinx.util.i18n.find_catalog_source_file()’ has changed; the
     `gettext_compact' argument has been deprecated

   * #5403: ‘sphinx.util.images.guess_mimetype()’ has changed; the
     `content' argument has been deprecated

1.8.0b1

   * source_parsers is deprecated

   * autodoc_default_flags is deprecated

   * quickstart: ‘--epub’ option becomes default, so it is deprecated

   * Drop function based directive support.  For now, Sphinx only
     supports class based directives (see ‘Directive’)

   * ‘sphinx.util.docutils.directive_helper()’ is deprecated

   * ‘sphinx.cmdline’ is deprecated

   * ‘sphinx.make_mode’ is deprecated

   * ‘sphinx.locale.l_()’ is deprecated

   * #2157: helper function ‘warn()’ for HTML themes is deprecated

   * ‘app.override_domain()’ is deprecated

   * ‘app.add_stylesheet()’ is deprecated

   * ‘app.add_javascript()’ is deprecated

   * ‘app.import_object()’ is deprecated

   * ‘app.add_source_parser()’ has changed; the `suffix' argument has
     been deprecated

   * ‘sphinx.versioning.prepare()’ is deprecated

   * ‘Config.__init__()’ has changed; the `dirname', `filename' and
     `tags' argument has been deprecated

   * ‘Config.check_types()’ is deprecated

   * ‘Config.check_unicode()’ is deprecated

   * ‘sphinx.application.CONFIG_FILENAME’ is deprecated

   * ‘highlightlang’ directive is deprecated

   * ‘BuildEnvironment.load()’ is deprecated

   * ‘BuildEnvironment.loads()’ is deprecated

   * ‘BuildEnvironment.frompickle()’ is deprecated

   * ‘env.read_doc()’ is deprecated

   * ‘env.update()’ is deprecated

   * ‘env._read_serial()’ is deprecated

   * ‘env._read_parallel()’ is deprecated

   * ‘env.write_doctree()’ is deprecated

   * ‘env._nitpick_ignore’ is deprecated

   * ‘env.versionchanges’ is deprecated

   * ‘env.dump()’ is deprecated

   * ‘env.dumps()’ is deprecated

   * ‘env.topickle()’ is deprecated

   * ‘env.note_versionchange()’ is deprecated

   * ‘sphinx.writers.latex.Table.caption_footnotetexts’ is deprecated

   * ‘sphinx.writers.latex.Table.header_footnotetexts’ is deprecated

   * ‘sphinx.writers.latex.LaTeXTranslator.footnotestack’ is deprecated

   * ‘sphinx.writers.latex.LaTeXTranslator.in_container_literal_block’
     is deprecated

   * ‘sphinx.writers.latex.LaTeXTranslator.next_section_ids’ is
     deprecated

   * ‘sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids’ is
     deprecated

   * ‘sphinx.writers.latex.LaTeXTranslator.restrict_footnote()’ is
     deprecated

   * ‘sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote()’ is
     deprecated

   * ‘sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids()’ is
     deprecated

   * ‘sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids()’ is
     deprecated

   * ‘sphinx.writers.latex.LaTeXTranslator.check_latex_elements()’ is
     deprecated

   * ‘sphinx.writers.latex.LaTeXTranslator.bibitems’ is deprecated

   * ‘sphinx.writers.latex.LaTeXTranslator.hlsettingstack’ is deprecated

   * ‘sphinx.writers.latex.ExtBabel.get_shorthandoff()’ is deprecated

   * ‘sphinx.writers.html.HTMLTranslator.highlightlang’ is deprecated

   * ‘sphinx.writers.html.HTMLTranslator.highlightlang_base’ is
     deprecated

   * ‘sphinx.writers.html.HTMLTranslator.highlightlangopts’ is
     deprecated

   * ‘sphinx.writers.html.HTMLTranslator.highlightlinenothreshold’ is
     deprecated

   * ‘sphinx.writers.html5.HTMLTranslator.highlightlang’ is deprecated

   * ‘sphinx.writers.html5.HTMLTranslator.highlightlang_base’ is
     deprecated

   * ‘sphinx.writers.html5.HTMLTranslator.highlightlangopts’ is
     deprecated

   * ‘sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold’ is
     deprecated

   * ‘sphinx.ext.mathbase’ extension is deprecated

   * ‘sphinx.ext.mathbase.math’ node is deprecated

   * ‘sphinx.ext.mathbase.displaymath’ node is deprecated

   * ‘sphinx.ext.mathbase.eqref’ node is deprecated

   * ‘sphinx.ext.mathbase.is_in_section_title()’ is deprecated

   * ‘sphinx.ext.mathbase.MathDomain’ is deprecated

   * ‘sphinx.ext.mathbase.MathDirective’ is deprecated

   * ‘sphinx.ext.mathbase.math_role’ is deprecated

   * ‘sphinx.ext.mathbase.setup_math()’ is deprecated

   * ‘sphinx.directives.other.VersionChanges’ is deprecated

   * ‘sphinx.highlighting.PygmentsBridge.unhighlight()’ is deprecated

   * ‘sphinx.ext.mathbase.get_node_equation_number()’ is deprecated

   * ‘sphinx.ext.mathbase.wrap_displaymath()’ is deprecated

   * The ‘trim_doctest_flags’ argument of
     ‘sphinx.highlighting.PygmentsBridge’ is deprecated

For more details, see deprecation APIs list(1)

   ---------- Footnotes ----------

   (1)
http://www.sphinx-doc.org/en/master/extdev/index.html#deprecated-apis

11.57.4 Features added
----------------------

1.8.0b2

   * #5388: Ensure frozen object descriptions are reproducible

   * #5362: apidoc: Add ‘--tocfile’ option to change the filename of ToC

1.8.0b1

   * Add config-inited event

   * Add ‘sphinx.config.Any’ to represent the config value accepts any
     type of value

   * source_suffix allows a mapping fileext to file types

   * Add author as a configuration value

   * #2852: imgconverter: Support to convert GIF to PNG

   * ‘sphinx-build’ command supports i18n console output

   * Add ‘app.add_message_catalog()’ and
     ‘sphinx.locale.get_translations()’ to support translation for 3rd
     party extensions

   * helper function ‘warning()’ for HTML themes is added

   * Add ‘Domain.enumerable_nodes’ to manage own enumerable nodes for
     domains (experimental)

   * Add a new keyword argument ‘override’ to Application APIs

   * LaTeX: new key ‘'fvset'’ for latex_elements.  For
     XeLaTeX/LuaLaTeX its default sets ‘fanvyvrb’ to use normal, not
     small, fontsize in code-blocks (refs: #4793)

   * Add html_css_files and epub_css_files for
     adding CSS files from configuration

   * Add html_js_files for adding JS files from
     configuration

   * #4834: Ensure set object descriptions are reproducible.

   * #4828: Allow to override numfig_format partially.  Full
     definition is not needed.

   * Improve warning messages during including (refs: #4818)

   * LaTeX: separate customizability of guilabel and
     menuselection. (refs: #4830)

   * Add ‘Config.read()’ classmethod to create a new config object from
     configuration file

   * #4866: Wrap graphviz diagrams in ‘<div>’ tag

   * viewcode: Add viewcode-find-source and
     viewcode-follow-imported to load source code without loading

   * #4785: napoleon: Add strings to translation file for localisation

   * #4927: Display a warning when invalid values are passed to
     linenothreshold option of highlight directive

   * C++:

        - Add a ‘cpp:texpr’ role as a sibling to ‘cpp:expr’.

        - Add support for unions.

        - #3593, #2683: add support for anonymous entities using names
          staring with ‘@’.

        - #5147: add support for (most) character literals.

        - Cross-referencing entities inside primary templates is
          supported, and now properly documented.

        - #1552: add new cross-referencing format for ‘cpp:any’ and
          ‘cpp:func’ roles, for referencing specific function overloads.

   * #3606: MathJax should be loaded with async attribute

   * html: Output ‘canonical_url’ metadata if html_baseurl.
     set (refs: #4193)

   * #5029: autosummary: expose ‘inherited_members’ to template

   * #3784: mathjax: Add mathjax_options to give options to
     script tag for mathjax

   * #726, #969: mathjax: Add mathjax_config to give in-line
     configurations for mathjax

   * #4362: latex: Don’t overwrite .tex file if document not changed

   * #1431: latex: Add alphanumeric enumerated list support

   * Add latex_use_xindy for UTF-8 savvy indexing, defaults
     to ‘True’ if latex_engine is ‘'xelatex'’ or
     ‘'lualatex'’.  (refs: #5134, #5192, #5212)

   * #4976: ‘SphinxLoggerAdapter.info()’ now supports ‘location’
     parameter

   * #5122: setuptools: support nitpicky option

   * #2820: autoclass directive supports nested class

   * Add ‘app.add_html_math_renderer()’ to register a math renderer for
     HTML

   * Apply trim_doctest_flags to all builders (cf.  text,
     manpages)

   * #5140: linkcheck: Add better Accept header to HTTP client

   * #4614: sphinx-build: Add ‘--keep-going’ option to show all warnings

   * Add math;numref role to refer equations (Same as
     eq)

   * quickstart: epub builder is enabled by default

   * #5246: Add singlehtml_sidebars to configure sidebars
     for singlehtml builder

   * #5273: doctest: Skip doctest conditionally

   * #5306: autodoc: emit a warning for invalid typehints

   * #4075, #5215: autodoc: Add autodoc_default_options.
     which accepts option values as dict

11.57.5 Bugs fixed
------------------

1.8.0b2

   * html: search box overrides to other elements if scrolled

   * i18n: warnings for translation catalogs have wrong line numbers
     (refs: #5321)

   * #5325: latex: cross references has been broken by multiply labeled
     objects

   * C++, fixes for symbol addition and lookup.  Lookup should no longer
     break in partial builds.  See also #5337.

   * #5348: download reference to remote file is not displayed

   * #5282: html theme: ‘pygments_style’ of theme was overridden by
     ‘conf.py’ by default

   * #4379: toctree shows confusing warning when document is excluded

   * #2401: autodoc: ‘:members:’ causes ‘:special-members:’ not to be
     shown

   * autodoc: ImportError is replaced by AttributeError for deeper
     module

   * #2720, #4034: Incorrect links with ‘:download:’, duplicate names,
     and parallel builds

   * #5290: autodoc: failed to analyze source code in egg package

   * #5399: Sphinx crashes if unknown po file exists

1.8.0b1

   * i18n: message catalogs were reset on each initialization

   * #4850: latex: footnote inside footnote was not rendered

   * #4945: i18n: fix lang_COUNTRY not fallback correctly for
     IndexBuilder.  Thanks to Shengjing Zhu.

   * #4983: productionlist directive generates invalid IDs for the
     tokens

   * #5132: lualatex: PDF build fails if indexed word starts with
     Unicode character

   * #5133: latex: index headings “Symbols” and “Numbers” not
     internationalized

   * #5114: sphinx-build: Handle errors on scanning documents

   * epub: spine has been broken when “self” is listed on toctree (refs:
     #4611)

   * #344: autosummary does not understand docstring of module level
     attributes

   * #5191: C++, prevent nested declarations in functions to avoid
     lookup problems.

   * #5126: C++, add missing isPack method for certain template
     parameter types.

   * #5187: C++, parse attributes on declarators as well.

   * C++, parse delete expressions and basic new expressions as well.

   * #5002: graphviz: SVGs do not adapt to the column width

11.57.6 Features removed
------------------------

1.8.0b1

   * ‘sphinx.ext.pngmath’ extension

11.57.7 Documentation
---------------------

1.8.0b1

   * #5083: Fix wrong make.bat option for internationalization.

   * #5115: napoleon: add admonitions added by #4613 to the docs.

11.58 Release 1.7.9 (released Sep 05, 2018)
===========================================

11.58.1 Features added
----------------------

   * #5359: Make generated texinfo files reproducible by sorting the
     anchors

11.58.2 Bugs fixed
------------------

   * #5361: crashed on incremental build if document uses include
     directive

11.59 Release 1.7.8 (released Aug 29, 2018)
===========================================

11.59.1 Incompatible changes
----------------------------

   * The type of ‘env.included’ has been changed to dict of set

11.59.2 Bugs fixed
------------------

   * #5320: intersphinx: crashed if invalid url given

   * #5326: manpage: crashed when invalid docname is specified as
     ‘man_pages’

   * #5322: autodoc: ‘Any’ typehint causes formatting error

   * #5327: “document isn’t included in any toctree” warning on rebuild
     with generated files

   * #5335: quickstart: escape sequence has been displayed with
     MacPorts’ python

11.60 Release 1.7.7 (released Aug 19, 2018)
===========================================

11.60.1 Bugs fixed
------------------

   * #5198: document not in toctree warning when including files only
     for parallel builds

   * LaTeX: reduce “Token not allowed in a PDF string” hyperref warnings
     in latex console output (refs: #5236)

   * LaTeX: suppress “remreset Warning: The remreset package is
     obsolete” in latex console output with recent LaTeX (refs: #5237)

   * #5234: PDF output: usage of PAPER environment variable is broken
     since Sphinx 1.5

   * LaTeX: fix the latex_engine documentation regarding
     Latin Modern font with XeLaTeX/LuaLateX (refs: #5251)

   * #5280: autodoc: Fix wrong type annotations for complex typing

   * autodoc: Optional types are wrongly rendered

   * #5291: autodoc crashed by ForwardRef types

   * #5211: autodoc: No docs generated for functools.partial functions

   * #5306: autodoc: ‘getargspec()’ raises NameError for invalid
     typehints

   * #5298: imgmath: math_number_all causes equations to have two
     numbers in html

   * #5294: sphinx-quickstart blank prompts in PowerShell

11.61 Release 1.7.6 (released Jul 17, 2018)
===========================================

11.61.1 Bugs fixed
------------------

   * #5037: LaTeX ‘\sphinxupquote{}’ breaks in Russian

   * sphinx.testing uses deprecated pytest API; ‘Node.get_marker(name)’

   * #5016: crashed when recommonmark.AutoStrictify is enabled

   * #5022: latex: crashed with docutils package provided by
     Debian/Ubuntu

   * #5009: latex: a label for table is vanished if table does not have
     a caption

   * #5048: crashed with numbered toctree

   * #2410: C, render empty argument lists for macros.

   * C++, fix lookup of full template specializations with no template
     arguments.

   * #4667: C++, fix assertion on missing references in global scope
     when using intersphinx.  Thanks to Alan M. Carroll.

   * #5019: autodoc: crashed by Form Feed Character

   * #5032: autodoc: loses the first staticmethod parameter for old
     styled classes

   * #5036: quickstart: Typing Ctrl-U clears the whole of line

   * #5066: html: “relations” sidebar is not shown by default

   * #5091: latex: curly braces in index entries are not handled
     correctly

   * #5070: epub: Wrong internal href fragment links

   * #5104: apidoc: Interface of ‘sphinx.apidoc:main()’ has changed

   * #4272: PDF builds of French projects have issues with XeTeX

   * #5076: napoleon raises RuntimeError with python 3.7

   * #5125: sphinx-build: Interface of ‘sphinx:main()’ has changed

   * sphinx-build: ‘sphinx.cmd.build.main()’ refers ‘sys.argv’ instead
     of given argument

   * #5146: autosummary: warning is emitted when the first line of
     docstring ends with literal notation

   * autosummary: warnings of autosummary indicates wrong location
     (refs: #5146)

   * #5143: autodoc: crashed on inspecting dict like object which does
     not support sorting

   * #5139: autodoc: Enum argument missing if it shares value with
     another

   * #4946: py domain: rtype field could not handle “None” as a type

   * #5176: LaTeX: indexing of terms containing ‘@’, ‘!’, or ‘"’ fails

   * #5161: html: crashes if copying static files are failed

   * #5167: autodoc: Fix formatting type annotations for tuples with
     more than two arguments

   * #3329: i18n: crashed by auto-symbol footnote references

   * #5158: autosummary: module summary has been broken when it starts
     with heading

11.62 Release 1.7.5 (released May 29, 2018)
===========================================

11.62.1 Bugs fixed
------------------

   * #4924: html search: Upper characters problem in any other languages

   * #4932: apidoc: some subpackage is ignored if sibling subpackage
     contains a module starting with underscore

   * #4863, #4938, #4939: i18n doesn’t handle correctly node.title as
     used for contents, topic, admonition, table and section.

   * #4913: i18n: literal blocks in bullet list are not translated

   * #4962: C++, raised TypeError on duplicate declaration.

   * #4825: C++, properly parse expr roles and give better error
     messages when (escaped) line breaks are present.

   * C++, properly use ‘desc_addname’ nodes for prefixes of names.

   * C++, parse pack expansions in function calls.

   * #4915, #4916: links on search page are broken when using dirhtml
     builder

   * #4969: autodoc: constructor method should not have return
     annotation

   * latex: deeply nested enumerated list which is beginning with non-1
     causes LaTeX engine crashed

   * #4978: latex: shorthandoff is not set up for Brazil locale

   * #4928: i18n: Ignore dot-directories like .git/ in LC_MESSAGES/

   * #4946: py domain: type field could not handle “None” as a type

   * #4979: latex: Incorrect escaping of curly braces in index entries

   * #4956: autodoc: Failed to extract document from a subclass of the
     class on mocked module

   * #4973: latex: glossary directive adds whitespace to each item

   * #4980: latex: Explicit labels on code blocks are duplicated

   * #4919: node.asdom() crashes if toctree has :numbered: option

   * #4914: autodoc: Parsing error when using dataclasses without
     default values

   * #4931: autodoc: crashed when handler for autodoc-skip-member raises
     an error

   * #4931: autodoc: crashed when subclass of mocked class are processed
     by napoleon module

   * #5007: sphinx-build crashes when error log contains a “%” character

11.63 Release 1.7.4 (released Apr 25, 2018)
===========================================

11.63.1 Bugs fixed
------------------

   * #4885, #4887: domains: Crashed with duplicated objects

   * #4889: latex: sphinx.writers.latex causes recursive import

11.64 Release 1.7.3 (released Apr 23, 2018)
===========================================

11.64.1 Bugs fixed
------------------

   * #4769: autodoc loses the first staticmethod parameter

   * #4790: autosummary: too wide two column tables in PDF builds

   * #4795: Latex customization via ‘_templates/longtable.tex_t’ is
     broken

   * #4789: imgconverter: confused by convert.exe of Windows

   * #4783: On windows, Sphinx crashed when drives of srcdir and outdir
     are different

   * #4812: autodoc ignores type annotated variables

   * #4817: wrong URLs on warning messages

   * #4784: latex: latex_show_urls assigns incorrect
     footnote numbers if hyperlinks exists inside substitutions

   * #4837: latex with class memoir Error: Font command ‘\sf’ is not
     supported

   * #4803: latex: too slow in proportion to number of auto numbered
     footnotes

   * #4838: htmlhelp: The entries in .hhp file is not ordered

   * toctree directive tries to glob for URL having query_string

   * #4871: html search: Upper characters problem in German

   * #4717: latex: Compilation for German docs failed with LuaLaTeX and
     XeLaTeX

   * #4459: duplicated labels detector does not work well in parallel
     build

   * #4878: Crashed with extension which returns invalid metadata

11.65 Release 1.7.2 (released Mar 21, 2018)
===========================================

11.65.1 Incompatible changes
----------------------------

   * #4520: apidoc: folders with an empty __init__.py are no longer
     excluded from TOC

11.65.2 Bugs fixed
------------------

   * #4669: sphinx.build_main and sphinx.make_main throw NameError

   * #4685: autosummary emits meaningless warnings

   * autodoc: crashed when invalid options given

   * pydomain: always strip parenthesis if empty (refs: #1042)

   * #4689: autosummary: unexpectedly strips docstrings containing
     “i.e.”

   * #4701: viewcode: Misplaced ‘<div>’ in viewcode html output

   * #4444: Don’t require numfig to use :numref: on sections

   * #4727: Option clash for package textcomp

   * #4725: Sphinx does not work with python 3.5.0 and 3.5.1

   * #4716: Generation PDF file with TexLive on Windows, file not found
     error

   * #4574: vertical space before equation in latex

   * #4720: message when an image is mismatched for builder is not clear

   * #4655, #4684: Incomplete localization strings in Polish and Chinese

   * #2286: Sphinx crashes when error is happens in rendering HTML pages

   * #4688: Error to download remote images having long URL

   * #4754: sphinx/pycode/__init__.py raises AttributeError

   * #1435: qthelp builder should htmlescape keywords

   * epub: Fix docTitle elements of toc.ncx is not escaped

   * #4520: apidoc: Subpackage not in toc (introduced in 1.6.6) now
     fixed

   * #4767: html: search highlighting breaks mathjax equations

11.66 Release 1.7.1 (released Feb 23, 2018)
===========================================

11.66.1 Deprecated
------------------

   * #4623: ‘sphinx.build_main()’ is deprecated.

   * autosummary: The interface of
     ‘sphinx.ext.autosummary.get_documenter()’ has been changed (Since
     1.7.0)

   * #4664: ‘sphinx.ext.intersphinx.debug()’ is deprecated.

For more details, see deprecation APIs list(1)

   ---------- Footnotes ----------

   (1)
http://www.sphinx-doc.org/en/master/extdev/index.html#deprecated-apis

11.66.2 Bugs fixed
------------------

   * #4608: epub: Invalid meta tag is generated

   * #4260: autodoc: keyword only argument separator is not disappeared
     if it is appeared at top of the argument list

   * #4622: epub: epub_scheme does not effect to content.opf

   * #4627: graphviz: Fit graphviz images to page

   * #4617: quickstart: PROJECT_DIR argument is required

   * #4623: sphinx.build_main no longer exists in 1.7.0

   * #4615: The argument of ‘sphinx.build’ has been changed in 1.7.0

   * autosummary: The interface of
     ‘sphinx.ext.autosummary.get_documenter()’ has been changed

   * #4630: Have order on msgids in sphinx.pot deterministic

   * #4563: autosummary: Incorrect end of line punctuation detection

   * #4577: Enumerated sublists with explicit start with wrong number

   * #4641: A external link in TOC cannot contain “?” with ‘:glob:’
     option

   * C++, add missing parsing of explicit casts and typeid in expression
     parsing.

   * C++, add missing parsing of ‘this’ in expression parsing.

   * #4655: Fix incomplete localization strings in Polish

   * #4653: Fix error reporting for parameterless ImportErrors

   * #4664: Reading objects.inv fails again

   * #4662: ‘any’ refs with ‘term’ targets crash when an ambiguity is
     encountered

11.67 Release 1.7.0 (released Feb 12, 2018)
===========================================

11.67.1 Dependencies
--------------------

1.7.0b1

   * Add ‘packaging’ package

11.67.2 Incompatible changes
----------------------------

1.7.0b1

   * #3668: The arguments has changed of main functions for each command

   * #3893: Unknown html_theme_options throw warnings instead of errors

   * #3927: Python parameter/variable types should match classes, not
     all objects

   * #3962: sphinx-apidoc now recognizes given directory as an implicit
     namespace package when ‘--implicit-namespaces’ option given, not
     subdirectories of given directory.

   * #3929: apidoc: Move sphinx.apidoc to sphinx.ext.apidoc

   * #4226: apidoc: Generate new style makefile (make-mode)

   * #4274: sphinx-build returns 2 as an exit code on argument error

   * #4389: output directory will be created after loading extensions

   * autodoc does not generate warnings messages to the generated
     document even if keep_warnings is True.  They are only
     emitted to stderr.

   * shebang line is removed from generated conf.py

   * #2557: autodoc: autodoc_mock_imports only mocks
     specified modules with their descendants.  It does not mock their
     ancestors.  If you want to mock them, please specify the name of
     ancestors explicitly.

   * #3620: html theme: move DOCUMENTATION_OPTIONS to independent
     JavaScript file (refs: #4295)

   * #4246: Limit width of text body for all themes.  Configurable via
     theme options ‘body_min_width’ and ‘body_max_width’.

   * #4771: apidoc: The ‘exclude_patterns’ arguments are ignored if they
     are placed just after command line options

1.7.0b2

   * #4467: html theme: Rename ‘csss’ block to ‘css’

11.67.3 Deprecated
------------------

1.7.0b1

   * using a string value for html_sidebars is deprecated
     and only list values will be accepted at 2.0.

   * ‘format_annotation()’ and ‘formatargspec()’ is deprecated.  Please
     use ‘sphinx.util.inspect.Signature’ instead.

   * ‘sphinx.ext.autodoc.AutodocReporter’ is replaced by
     ‘sphinx.util.docutils. switch_source_input()’ and now deprecated.
     It will be removed in Sphinx-2.0.

   * ‘sphinx.ext.autodoc.add_documenter()’ and ‘AutoDirective._register’
     is now deprecated.  Please use ‘app.add_autodocumenter()’ instead.

   * ‘AutoDirective._special_attrgetters’ is now deprecated.  Please use
     ‘app.add_autodoc_attrgetter()’ instead.

11.67.4 Features added
----------------------

1.7.0b1

   * C++, handle ‘decltype(auto)’.

   * #2406: C++, add proper parsing of expressions, including linking of
     identifiers.

   * C++, add a ‘cpp:expr’ role for inserting inline C++ expressions or
     types.

   * C++, support explicit member instantiations with shorthand
     ‘template’ prefix

   * C++, make function parameters linkable, like template params.

   * #3638: Allow to change a label of reference to equation using
     ‘math_eqref_format’

   * Now suppress_warnings accepts following configurations:

        - ‘ref.python’ (ref: #3866)

   * #3872: Add latex key to configure literal blocks caption position
     in PDF output (refs #3792, #1723)

   * In case of missing docstring try to retrieve doc from base classes
     (ref: #3140)

   * #4023: Clarify error message when any role has more than one
     target.

   * #3973: epub: allow to override build date

   * #3972: epub: Sort manifest entries by filename

   * #4052: viewcode: Sort before highlighting module code

   * #1448: qthelp: Add new config value; see qthelp_namespace.

   * #4140: html themes: Make body tag inheritable

   * #4168: improve zh search with jieba

   * HTML themes can set up default sidebars through ‘theme.conf’

   * #3160: html: Use ‘<kdb>’ to represent ‘:kbd:’ role

   * #4212: autosummary: catch all exceptions when importing modules

   * #4166: Add math_numfig for equation numbering by
     section (refs: #3991, #4080).  Thanks to Oliver Jahn.

   * #4311: Let LaTeX obey numfig_secnum_depth for figures,
     tables, and code-blocks

   * #947: autodoc now supports ignore-module-all to ignore a module’s
     ‘__all__’

   * #4332: Let LaTeX obey math_numfig for equation
     numbering

   * #4093: sphinx-build creates empty directories for unknown
     targets/builders

   * Add ‘top-classes’ option for the ‘sphinx.ext.inheritance_diagram’
     extension to limit the scope of inheritance graphs.

   * #4183: doctest: ‘:pyversion:’ option also follows PEP-440
     specification

   * #4235: html: Add manpages_url to make manpage roles to
     hyperlinks

   * #3570: autodoc: Do not display ‘typing.’ module for type hints

   * #4354: sphinx-build now emits finish message.  Builders can modify
     it through ‘Builder.epilog’ attribute

   * #4245: html themes: Add ‘language’ to javascript vars list

   * #4079: html: Add ‘notranslate’ class to each code-blocks, literals
     and maths to let Google Translate know they are not translatable

   * #4137: doctest: doctest block is always highlighted as python
     console (pycon)

   * #4137: doctest: testcode block is always highlighted as python

   * #3998: text: Assign section numbers by default.  You can control it
     using text_add_secnumbers and
     text_secnumber_suffix.

1.7.0b2

   * #4271: sphinx-build supports an option called ‘-j auto’ to adjust
     numbers of processes automatically.

   * Napoleon: added option to specify custom section tags.

11.67.5 Features removed
------------------------

1.7.0b1

   * Configuration variables

        - html_use_smartypants

        - latex_keep_old_macro_names

        - latex_elements[‘footer’]

   * utility methods of ‘sphinx.application.Sphinx’ class

        - buildername (property)

        - _display_chunk()

        - old_status_iterator()

        - status_iterator()

        - _directive_helper()

   * utility methods of ‘sphinx.environment.BuildEnvironment’ class

        - currmodule (property)

        - currclass (property)

   * epub2 builder

   * prefix and colorfunc parameter for warn()

   * ‘sphinx.util.compat’ module

   * ‘sphinx.util.nodes.process_only_nodes()’

   * LaTeX environment ‘notice’, use ‘sphinxadmonition’ instead

   * LaTeX ‘\sphinxstylethead’, use ‘\sphinxstyletheadfamily’

   * C++, support of function concepts.  Thanks to mickk-on-cpp.

   * Not used and previously not documented LaTeX macros ‘\shortversion’
     and ‘\setshortversion’

11.67.6 Bugs fixed
------------------

1.7.0b1

   * #3882: Update the order of files for HTMLHelp and QTHelp

   * #3962: sphinx-apidoc does not recognize implicit namespace packages
     correctly

   * #4094: C++, allow empty template argument lists.

   * C++, also hyperlink types in the name of declarations with
     qualified names.

   * C++, do not add index entries for declarations inside concepts.

   * C++, support the template disambiguator for dependent names.

   * #4314: For PDF ‘howto’ documents, numbering of code-blocks differs
     from the one of figures and tables

   * #4330: PDF ‘howto’ documents have an incoherent default LaTeX
     tocdepth counter setting

   * #4198: autosummary emits multiple ‘autodoc-process-docstring’
     event.  Thanks to Joel Nothman.

   * #4081: Warnings and errors colored the same when building

   * latex: Do not display ‘Release’ label if release is not
     set

1.7.0b2

   * #4415: autodoc classifies inherited classmethods as regular methods

   * #4415: autodoc classifies inherited staticmethods as regular
     methods

   * #4472: DOCUMENTATION_OPTIONS is not defined

   * #4491: autodoc: prefer _MockImporter over other importers in
     sys.meta_path

   * #4490: autodoc: type annotation is broken with python 3.7.0a4+

   * utils package is no longer installed

   * #3952: apidoc: module header is too escaped

   * #4275: Formats accepted by sphinx.util.i18n.format_date are limited

   * #4493: recommonmark raises AttributeError if AutoStructify enabled

   * #4209: intersphinx: In link title, “v” should be optional if target
     has no version

   * #4230: slowdown in writing pages with sphinx 1.6

   * #4522: epub: document is not rebuilt even if config changed

1.7.0b3

   * #4019: inheritance_diagram AttributeError stopping make process

   * #4531: autosummary: methods are not treated as attributes

   * #4538: autodoc: ‘sphinx.ext.autodoc.Options’ has been moved

   * #4539: autodoc emits warnings for partialmethods

   * #4223: doctest: failing tests reported in wrong file, at wrong line

   * i18n: message catalogs are not compiled if specific filenames are
     given for ‘sphinx-build’ as arguments (refs: #4560)

   * #4027: sphinx.ext.autosectionlabel now expects labels to be the
     same as they are in the raw source; no smart quotes, nothig fancy.

   * #4581: apidoc: Excluded modules still included

11.67.7 Testing
---------------

1.7.0b1

   * Add support for docutils 0.14

   * Add tests for the ‘sphinx.ext.inheritance_diagram’ extension.

11.68 Release 1.6.7 (released Feb 04, 2018)
===========================================

11.68.1 Bugs fixed
------------------

   * #1922: html search: Upper characters problem in French

   * #4412: Updated jQuery version from 3.1.0 to 3.2.1

   * #4438: math: math with labels with whitespace cause html error

   * #2437: make full reference for classes, aliased with “alias of”

   * #4434: pure numbers as link targets produce warning

   * #4477: Build fails after building specific files

   * #4449: apidoc: include “empty” packages that contain modules

   * #3917: citation labels are transformed to ellipsis

   * #4501: graphviz: epub3 validation error caused if graph is not
     clickable

   * #4514: graphviz: workaround for wrong map ID which graphviz
     generates

   * #4525: autosectionlabel does not support parallel build

   * #3953: Do not raise warning when there is a working intersphinx
     inventory

   * #4487: math: ValueError is raised on parallel build.  Thanks to
     jschueller.

   * #2372: autosummary: invalid signatures are shown for type annotated
     functions

   * #3942: html: table is not aligned to center even if ‘:align:
     center’

11.69 Release 1.6.6 (released Jan 08, 2018)
===========================================

11.69.1 Features added
----------------------

   * #4181: autodoc: Sort dictionary keys when possible

   * ‘VerbatimHighlightColor’ is a new LaTeX ‘sphinxsetup’.
     key (refs: #4285)

   * Easier customizability of LaTeX macros involved in rendering of
     code-blocks

   * Show traceback if conf.py raises an exception (refs: #4369)

   * Add smartquotes to disable smart quotes through
     ‘conf.py’ (refs: #3967)

   * Add smartquotes_action and smartquotes_excludes.
     (refs: #4142, #4357)

11.69.2 Bugs fixed
------------------

   * #4334: sphinx-apidoc: Don’t generate references to non-existing
     files in TOC

   * #4206: latex: reST label between paragraphs loses paragraph break

   * #4231: html: Apply fixFirefoxAnchorBug only under Firefox

   * #4221: napoleon depends on autodoc, but users need to load it
     manually

   * #2298: automodule fails to document a class attribute

   * #4099: C++: properly link class reference to class from inside
     constructor

   * #4267: PDF build broken by Unicode U+2116 NUMERO SIGN character

   * #4249: PDF output: Pygments error highlighting increases line
     spacing in code blocks

   * #1238: Support ‘:emphasize-lines:’ in PDF output

   * #4279: Sphinx crashes with pickling error when run with multiple
     processes and remote image

   * #1421: Respect the quiet flag in sphinx-quickstart

   * #4281: Race conditions when creating output directory

   * #4315: For PDF ‘howto’ documents,
     ‘latex_toplevel_sectioning='part'’ generates ‘\chapter’ commands

   * #4214: Two todolist directives break sphinx-1.6.5

   * Fix links to external option docs with intersphinx (refs: #3769)

   * #4091: Private members not documented without :undoc-members:

11.70 Release 1.6.5 (released Oct 23, 2017)
===========================================

11.70.1 Features added
----------------------

   * #4107: Make searchtools.js compatible with pre-Sphinx1.5 templates

   * #4112: Don’t override the smart_quotes setting if it was already
     set

   * #4125: Display reference texts of original and translated passages
     on i18n warning message

   * #4147: Include the exception when logging PO/MO file read/write

11.70.2 Bugs fixed
------------------

   * #4085: Failed PDF build from image in parsed-literal using
     ‘:align:’ option

   * #4100: Remove debug print from autodoc extension

   * #3987: Changing theme from alabaster causes HTML build to fail

   * #4096: C++, don’t crash when using the wrong role type.  Thanks to
     mitya57.

   * #4070, #4111: crashes when the warning message contains format
     strings (again)

   * #4108: Search word highlighting breaks SVG images

   * #3692: Unable to build HTML if writing .buildinfo failed

   * #4152: HTML writer crashes if a field list is placed on top of the
     document

   * #4063: Sphinx crashes when labeling directive ‘.. todolist::’

   * #4134: [doc] ‘docutils.conf’ is not documented explicitly

   * #4169: Chinese language doesn’t trigger Chinese search
     automatically

   * #1020: ext.todo todolist not linking to the page in pdflatex

   * #3965: New quickstart generates wrong SPHINXBUILD in Makefile

   * #3739: ‘:module:’ option is ignored at content of pyobjects

   * #4149: Documentation: Help choosing latex_engine.

   * #4090: [doc] latex_additional_files with extra LaTeX
     macros should not use ‘.tex’ extension

   * Failed to convert reST parser error to warning (refs: #4132)

11.71 Release 1.6.4 (released Sep 26, 2017)
===========================================

11.71.1 Features added
----------------------

   * #3926: Add ‘autodoc_warningiserror’ to suppress the behavior of
     ‘-W’ option during importing target modules on autodoc

11.71.2 Bugs fixed
------------------

   * #3924: docname lost after dynamically parsing RST in extension

   * #3946: Typo in sphinx.sty (this was a bug with no effect in default
     context)

   *
pep: and :rfc: does not supports ‘default-role’ directive (refs:
     #3960)

   * #3960: default_role = ‘guilabel’ not functioning

   * Missing ‘texinputs_win/Makefile’ to be used in latexpdf builder on
     windows.

   * #4026: nature: Fix macOS Safari scrollbar color

   * #3877: Fix for C++ multiline signatures.

   * #4006: Fix crash on parallel build

   * #3969: private instance attributes causes AttributeError

   * #4041: C++, remove extra name linking in function pointers.

   * #4038: C, add missing documentation of ‘member’ role.

   * #4044: An empty multicolumn cell causes extra row height in PDF
     output

   * #4049: Fix typo in output of sphinx-build -h

   * #4062: hashlib.sha1() must take bytes, not unicode on Python 3

   * Avoid indent after index entries in latex (refs: #4066)

   * #4070: crashes when the warning message contains format strings

   * #4067: Return non-zero exit status when make subprocess fails

   * #4055: graphviz: the :align: option does not work for SVG output

   * #4055: graphviz: the :align: center option does not work for latex
     output

   * #4051: ‘warn()’ function for HTML theme outputs ‘None’ string

11.72 Release 1.6.3 (released Jul 02, 2017)
===========================================

11.72.1 Features added
----------------------

   * latex: hint that code-block continues on next page (refs: #3764,
     #3792)

11.72.2 Bugs fixed
------------------

   * #3821: Failed to import sphinx.util.compat with docutils-0.14rc1

   * #3829: sphinx-quickstart template is incomplete regarding use of
     alabaster

   * #3772: ‘str object’ has no attribute ‘filename’

   * Emit wrong warnings if citation label includes hyphens (refs:
     #3565)

   * #3858: Some warnings are not colored when using –color option

   * #3775: Remove unwanted whitespace in default template

   * #3835: sphinx.ext.imgmath fails to convert SVG images if project
     directory name contains spaces

   * #3850: Fix color handling in make mode’s help command

   * #3865: use of self.env.warn in sphinx extension fails

   * #3824: production lists apply smart quotes transform since Sphinx
     1.6.1

   * latex: fix ‘\sphinxbfcode’ swallows initial space of argument

   * #3878: Quotes in auto-documented class attributes should be
     straight quotes in PDF output

   * #3881: LaTeX figure floated to next page sometimes leaves extra
     vertical whitespace

   * #3885: duplicated footnotes raises IndexError

   * #3873: Failure of deprecation warning mechanism of
     ‘sphinx.util.compat.Directive’

   * #3874: Bogus warnings for “citation not referenced” for cross-file
     citations

   * #3860: Don’t download images when builders not supported images

   * #3860: Remote image URIs without filename break builders not
     supported remote images

   * #3833: command line messages are translated unintentionally with
     ‘language’ setting.

   * #3840: make checking ‘epub_uid’ strict

   * #3851, #3706: Fix about box drawing characters for PDF output

   * #3900: autosummary could not find methods

   * #3902: Emit error if ‘latex_documents’ contains non-unicode string
     in py2

11.73 Release 1.6.2 (released May 28, 2017)
===========================================

11.73.1 Incompatible changes
----------------------------

   * #3789: Do not require typing module for python>=3.5

11.73.2 Bugs fixed
------------------

   * #3754: HTML builder crashes if HTML theme appends own stylesheets

   * #3756: epub: Entity ‘mdash’ not defined

   * #3758: Sphinx crashed if logs are emitted in conf.py

   * #3755: incorrectly warns about dedent with literalinclude

   * #3742: RTD(1) PDF builds of Sphinx own docs are missing an index
     entry in the bookmarks and table of contents.  This is
     rtfd/readthedocs.org#2857(2) issue, a workaround is obtained using
     some extra LaTeX code in Sphinx’s own ‘conf.py’

   * #3770: Build fails when a “code-block” has the option
     emphasize-lines and the number indicated is higher than the number
     of lines

   * #3774: Incremental HTML building broken when using citations

   * #3763: got epubcheck validations error if epub_cover is set

   * #3779: ‘ImportError’ in sphinx.ext.autodoc due to broken
     ‘sys.meta_path’.  Thanks to Tatiana Tereshchenko.

   * #3796: env.resolve_references() crashes when non-document node
     given

   * #3803: Sphinx crashes with invalid PO files

   * #3791: PDF “continued on next page” for long tables isn’t
     internationalized

   * #3788: smartquotes emits warnings for unsupported languages

   * #3807: latex Makefile for ‘make latexpdf’ is only for unixen

   * #3781: double hyphens in option directive are compiled as endashes

   * #3817: latex builder raises AttributeError

   ---------- Footnotes ----------

   (1) https://readthedocs.org/

   (2) https://github.com/rtfd/readthedocs.org/issues/2857

11.74 Release 1.6.1 (released May 16, 2017)
===========================================

11.74.1 Dependencies
--------------------

1.6b1

   * (updated) latex output is tested with Ubuntu trusty’s texlive
     packages (Feb.  2014) and earlier tex installations may not be
     fully compliant, particularly regarding Unicode engines xelatex and
     lualatex

   * (added) latexmk is required for ‘make latexpdf’ on GNU/Linux and
     Mac OS X (refs: #3082)

11.74.2 Incompatible changes
----------------------------

1.6b1

   * #1061, #2336, #3235: Now generation of autosummary doesn’t contain
     imported members by default.  Thanks to Luc Saffre.

   * LaTeX ‘\includegraphics’ command isn’t overloaded: only
     ‘\sphinxincludegraphics’ has the custom code to fit image to
     available width if oversized.

   * The subclasses of ‘sphinx.domains.Index’ should override
     ‘generate()’ method.  The default implementation raises
     NotImplementedError

   * LaTeX positioned long tables horizontally centered, and short ones
     flushed left (no text flow around table.)  The position now
     defaults to center in both cases, and it will obey Docutils 0.13
     ‘:align:’ option (refs #3415, #3377)

   * option directive also allows all punctuations for the option name
     (refs: #3366)

   * #3413: if literalinclude.’s ‘:start-after:’ is used, make
     ‘:lines:’ relative (refs #3412)

   * ‘literalinclude’ directive does not allow the combination of
     ‘:diff:’ option and other options (refs: #3416)

   * LuaLaTeX engine uses ‘fontspec’ like XeLaTeX. It is advised
     ‘latex_engine = 'lualatex'’ be used only on up-to-date TeX installs
     (refs #3070, #3466)

   * ‘latex_keep_old_macro_names’ default value has been changed from
     ‘True’ to ‘False’.  This means that some LaTeX macros for styling
     are by default defined only with ‘\sphinx..’ prefixed names.
     (refs: #3429)

   * Footer “Continued on next page” of LaTeX longtable’s now not framed
     (refs: #3497)

   * #3529: The arguments of ‘BuildEnvironment.__init__’ is changed

   * #3082: Use latexmk for pdf (and dvi) targets (Unix-like platforms
     only)

   * #3558: Emit warnings if footnotes and citations are not referenced.
     The warnings can be suppressed by ‘suppress_warnings’.

   * latex made available (non documented) colour macros from a file
     distributed with pdftex engine for Plain TeX. This is removed in
     order to provide better support for multiple TeX engines.  Only
     interface from ‘color’ or ‘xcolor’ packages should be used by
     extensions of Sphinx latex writer.  (refs #3550)

   * ‘Builder.env’ is not filled at instantiation

   * #3594: LaTeX: single raw directive has been considered as block
     level element

   * #3639: If ‘html_experimental_html5_writer’ is available, epub
     builder use it by default.

   * ‘Sphinx.add_source_parser()’ raises an error if duplicated

1.6b2

   * #3345: Replace the custom smartypants code with Docutils’
     smart_quotes.  Thanks to Dmitry Shachnev, and to Günter Milde at
     Docutils.

1.6b3

   * LaTeX package ‘eqparbox’ is not used and not loaded by Sphinx
     anymore

   * LaTeX package ‘multirow’ is not used and not loaded by Sphinx
     anymore

   * Add line numbers to citation data in std domain

1.6 final

   * LaTeX package ‘threeparttable’ is not used and not loaded by Sphinx
     anymore (refs #3686, #3532, #3377)

11.74.3 Features removed
------------------------

   * Configuration variables

        - epub3_contributor

        - epub3_description

        - epub3_page_progression_direction

        - html_translator_class

        - html_use_modindex

        - latex_font_size

        - latex_paper_size

        - latex_preamble

        - latex_use_modindex

        - latex_use_parts

   * ‘termsep’ node

   * defindex.html template

   * LDML format support in ‘today’, ‘today_fmt’ and
     ‘html_last_updated_fmt’

   * ‘:inline:’ option for the directives of sphinx.ext.graphviz
     extension

   * sphinx.ext.pngmath extension

   * ‘sphinx.util.compat.make_admonition()’

11.74.4 Features added
----------------------

1.6b1

   * #3136: Add ‘:name:’ option to the directives in
     ‘sphinx.ext.graphviz’

   * #2336: Add ‘imported_members’ option to ‘sphinx-autogen’ command to
     document imported members.

   * C++, add ‘:tparam-line-spec:’ option to templated declarations.
     When specified, each template parameter will be rendered on a
     separate line.

   * #3359: Allow sphinx.js in a user locale dir to override sphinx.js
     from Sphinx

   * #3303: Add ‘:pyversion:’ option to the doctest directive.

   * #3378: (latex) support for ‘:widths:’ option of table directives
     (refs: #3379, #3381)

   * #3402: Allow to suppress “download file not readable” warnings
     using suppress_warnings.

   * #3377: latex: Add support for Docutils 0.13 ‘:align:’ option for
     tables (but does not implement text flow around table).

   * latex: footnotes from inside tables are hyperlinked (except from
     captions or headers) (refs: #3422)

   * Emit warning if over dedent has detected on ‘literalinclude’
     directive (refs: #3416)

   * Use for LuaLaTeX same default settings as for XeLaTeX (i.e.
     ‘fontspec’ and ‘polyglossia’).  (refs: #3070, #3466)

   * Make ‘'extraclassoptions'’ key of ‘latex_elements’ public (refs
     #3480)

   * #3463: Add warning messages for required EPUB3 metadata.  Add
     default value to ‘epub_description’ to avoid warning like other
     settings.

   * #3476: setuptools: Support multiple builders

   * latex: merged cells in LaTeX tables allow code-blocks, lists,
     blockquotes… as do normal cells (refs: #3435)

   * HTML builder uses experimental HTML5 writer if
     ‘html_experimental_html5_writer’ is True and docutils 0.13 or later
     is installed.

   * LaTeX macros to customize space before and after tables in PDF
     output (refs #3504)

   * #3348: Show decorators in literalinclude and viewcode directives

   * #3108: Show warning if :start-at: and other literalinclude options
     does not match to the text

   * #3609: Allow to suppress “duplicate citation” warnings using
     ‘suppress_warnings’

   * #2803: Discovery of builders by entry point

   * #1764, #1676: Allow setting ‘rel’ and ‘title’ attributes for
     stylesheets

   * #3589: Support remote images on non-HTML builders

   * #3589: Support images in Data URI on non-HTML builders

   * #2961: improve autodoc_mock_imports.  Now the config
     value only requires to declare the top-level modules that should be
     mocked.  Thanks to Robin Jarry.

   * #3449: On py3, autodoc use inspect.signature for more accurate
     signature calculation.  Thanks to Nathaniel J. Smith.

   * #3641: Epub theme supports HTML structures that are generated by
     HTML5 writer.

   * #3644 autodoc uses inspect instead of checking types.  Thanks to
     Jeroen Demeyer.

   * Add a new extension; ‘sphinx.ext.imgconverter’.  It converts images
     in the document to appropriate format for builders

   * latex: Use templates to render tables (refs #3389, 2a37b0e)

1.6b2

   * ‘LATEXMKOPTS’ variable for the Makefile in ‘$BUILDDIR/latex’ to
     pass options to ‘latexmk’ when executing ‘make latexpdf’ (refs
     #3695, #3720)

   * Add a new event env-check-consistency to check
     consistency to extensions

   * Add Domain.check_consistency() to check consistency

11.74.5 Bugs fixed
------------------

1.6b1

   * ‘literalinclude’ directive expands tabs after dedent-ing (refs:
     #3416)

   * #1574: Paragraphs in table cell doesn’t work in Latex output

   * #3288: Table with merged headers not wrapping text

   * #3491: Inconsistent vertical space around table and longtable in
     PDF

   * #3506: Depart functions for all admonitions in HTML writer now
     properly pass ‘node’ to ‘depart_admonition’.

   * #2693: Sphinx latex style file wrongly inhibits colours for section
     headings for latex+dvi(ps,pdf,pdfmx)

   * C++, properly look up ‘any’ references.

   * #3624: sphinx.ext.intersphinx couldn’t load inventories compressed
     with gzip

   * #3551: PDF information dictionary is lacking author and title data

   * #3351: intersphinx does not refers context like ‘py:module’,
     ‘py:class’ and so on.

   * Fail to load template file if the parent template is archived

1.6b2

   * #3661: sphinx-build crashes on parallel build

   * #3669: gettext builder fails with “ValueError: substring not found”

   * #3660: Sphinx always depends on sphinxcontrib-websupport and its
     dependencies

   * #3472: smart quotes getting wrong in latex (at least with list of
     strings via autoattribute) (refs: #3345, #3666)

1.6b3

   * #3588: No compact (p tag) html output in the i18n document build
     even when html_compact_lists is True.

   * The ‘make latexpdf’ from 1.6b1 (for GNU/Linux and Mac OS, using
     ‘latexmk’) aborted earlier in case of LaTeX errors than was the
     case with 1.5 series, due to hard-coded usage of ‘--halt-on-error’
     option (refs #3695)

   * #3683: sphinx.websupport module is not provided by default

   * #3683: Failed to build document if builder.css_file.insert() is
     called

   * #3714: viewcode extension not taking ‘highlight_code='none'’ in
     account

   * #3698: Moving :doc: to std domain broke backwards compatibility

   * #3633: misdetect unreferenced citations

1.6 final

   * LaTeX tables do not allow multiple paragraphs in a header cell

   * LATEXOPTS is not passed over correctly to pdflatex since 1.6b3

   * #3532: Figure or literal block captions in cells of short tables
     cause havoc in PDF output

   * Fix: in PDF captions of tables are rendered differently whether
     table is of longtable class or not (refs #3686)

   * #3725: Todo looks different from note in LaTeX output

   * #3479: stub-columns have no effect in LaTeX output

   * #3738: Nonsensical code in theming.py

   * #3746: PDF builds fail with latexmk 4.48 or earlier due to
     undefined options ‘-pdfxe’ and ‘-pdflua’

11.74.6 Deprecated
------------------

1.6b1

   * ‘sphinx.util.compat.Directive’ class is now deprecated.  Please use
     instead ‘docutils.parsers.rst.Directive’

   * ‘sphinx.util.compat.docutils_version’ is now deprecated

   * #2367: ‘Sphinx.warn()’, ‘Sphinx.info()’ and other logging methods
     are now deprecated.  Please use ‘sphinx.util.logging’ (see
     Logging API) instead.

   * #3318: ‘notice’ is now deprecated as LaTeX environment name and
     will be removed at Sphinx 1.7.  Extension authors please use
     ‘sphinxadmonition’ instead (as Sphinx does since 1.5.)

   * ‘Sphinx.status_iterator()’ and ‘Sphinx.old_status_iterator()’ is
     now deprecated.  Please use ‘sphinx.util:status_iterator()’
     instead.

   * ‘Sphinx._directive_helper()’ is deprecated.  Please use
     ‘sphinx.util.docutils.directive_helper()’ instead.

   * ‘BuildEnvironment.set_warnfunc()’ is now deprecated

   * Following methods of ‘BuildEnvironment’ is now deprecated.

        - ‘BuildEnvironment.note_toctree()’

        - ‘BuildEnvironment.get_toc_for()’

        - ‘BuildEnvironment.get_toctree_for()’

        - ‘BuildEnvironment.create_index()’

     Please use ‘sphinx.environment.adapters’ modules instead.

   * latex package ‘footnote’ is not loaded anymore by its bundled
     replacement ‘footnotehyper-sphinx’.  The redefined macros keep the
     same names as in the original package.

   * #3429: deprecate config setting ‘latex_keep_old_macro_names’.  It
     will be removed at 1.7, and already its default value has changed
     from ‘True’ to ‘False’.

   * #3221: epub2 builder is deprecated

   * #3254: ‘sphinx.websupport’ is now separated into independent
     package; ‘sphinxcontrib-websupport’.  ‘sphinx.websupport’ will be
     removed in Sphinx-2.0.

   * #3628: ‘sphinx_themes’ entry_point is deprecated.  Please use
     ‘sphinx.html_themes’ instead.

1.6b2

   * #3662: ‘builder.css_files’ is deprecated.  Please use
     ‘add_stylesheet()’ API instead.

1.6 final

   * LaTeX ‘\sphinxstylethead’ is deprecated at 1.6 and will be removed
     at 1.7.  Please move customization into new macro
     ‘\sphinxstyletheadfamily’.

11.74.7 Testing
---------------

1.6 final

   * #3458: Add ‘sphinx.testing’ (experimental)

11.75 Release 1.6 (unreleased)
==============================

   * not released (because of package script error)

11.76 Release 1.5.6 (released May 15, 2017)
===========================================

11.76.1 Bugs fixed
------------------

   * #3614: Sphinx crashes with requests-2.5.0

   * #3618: autodoc crashes with tupled arguments

   * #3664: No space after the bullet in items of a latex list produced
     by Sphinx

   * #3657: EPUB builder crashes if a document starting with genindex
     exists

   * #3588: No compact (p tag) html output in the i18n document build
     even when html_compact_lists is True.

   * #3685: AttributeError when using 3rd party domains

   * #3702: LaTeX writer styles figure legends with a hard-coded
     ‘\small’

   * #3708: LaTeX writer allows irc scheme

   * #3717: Stop enforcing that favicon’s must be .ico

   * #3731, #3732: Protect isenumclass predicate against non-class
     arguments

   * #3320: Warning about reference target not being found for container
     types

   * Misspelled ARCHIVEPREFIX in Makefile for latex build repertory

11.77 Release 1.5.5 (released Apr 03, 2017)
===========================================

11.77.1 Bugs fixed
------------------

   * #3597: python domain raises UnboundLocalError if invalid name given

   * #3599: Move to new MathJax CDN

11.78 Release 1.5.4 (released Apr 02, 2017)
===========================================

11.78.1 Features added
----------------------

   * #3470: Make genindex support all kinds of letters, not only Latin
     ones

11.78.2 Bugs fixed
------------------

   * #3445: setting ‘'inputenc'’ key to ‘\\usepackage[utf8x]{inputenc}’
     leads to failed PDF build

   * EPUB file has duplicated ‘nav.xhtml’ link in ‘content.opf’ except
     first time build

   * #3488: objects.inv has broken when ‘release’ or ‘version’ contain
     return code

   * #2073, #3443, #3490: gettext builder that writes pot files unless
     the content are same without creation date.  Thanks to Yoshiki
     Shibukawa.

   * #3487: intersphinx: failed to refer options

   * #3496: latex longtable’s last column may be much wider than its
     contents

   * #3507: wrong quotes in latex output for productionlist directive

   * #3533: Moving from Sphinx 1.3.1 to 1.5.3 breaks LaTeX compilation
     of links rendered as code

   * #2665, #2607: Link names in C++ docfields, and make it possible for
     other domains.

   * #3542: C++, fix parsing error of non-type template argument with
     template.

   * #3065, #3520: python domain fails to recognize nested class

   * #3575: Problems with pdflatex in a Turkish document built with
     sphinx has reappeared (refs #2997, #2397)

   * #3577: Fix intersphinx debug tool

   * A LaTeX command such as ‘\\large’ inserted in the title items of
     latex_documents causes failed PDF build (refs #3551,
     #3567)

11.79 Release 1.5.3 (released Feb 26, 2017)
===========================================

11.79.1 Features added
----------------------

   * Support requests-2.0.0 (experimental) (refs: #3367)

   * (latex) PDF page margin dimensions may be customized (refs: #3387)

   * ‘literalinclude’ directive allows combination of ‘:pyobject:’ and
     ‘:lines:’ options (refs: #3416)

   * #3400: make-mode doesn’t use subprocess on building docs

11.79.2 Bugs fixed
------------------

   * #3370: the caption of code-block is not picked up for translation

   * LaTeX: release is not escaped (refs: #3362)

   * #3364: sphinx-quickstart prompts overflow on Console with 80 chars
     width

   * since 1.5, PDF’s TOC and bookmarks lack an entry for general Index
     (refs: #3383)

   * #3392: ‘'releasename'’ in latex_elements is not working

   * #3356: Page layout for Japanese ‘'manual'’ docclass has a shorter
     text area

   * #3394: When ‘'pointsize'’ is not ‘10pt’, Japanese ‘'manual'’
     document gets wrong PDF page dimensions

   * #3399: quickstart: conf.py was not overwritten by template

   * #3366: option directive does not allow punctuations

   * #3410: return code in release breaks html search

   * #3427: autodoc: memory addresses are not stripped on Windows

   * #3428: xetex build tests fail due to fontspec v2.6 defining
     ‘\strong’

   * #3349: Result of ‘IndexBuilder.load()’ is broken

   * #3450: &nbsp is appeared in EPUB docs

   * #3418: Search button is misaligned in nature and pyramid theme

   * #3421: Could not translate a caption of tables

   * #3552: linkcheck raises UnboundLocalError

11.80 Release 1.5.2 (released Jan 22, 2017)
===========================================

11.80.1 Incompatible changes
----------------------------

   * Dependency requirement updates: requests 2.4.0 or above (refs:
     #3268, #3310)

11.80.2 Features added
----------------------

   * #3241: emit latex warning if buggy titlesec (ref #3210)

   * #3194: Refer the $MAKE environment variable to determine ‘make’
     command

   * Emit warning for nested numbered toctrees (refs: #3142)

   * #978: intersphinx_mapping also allows a list as a
     parameter

   * #3340: (LaTeX) long lines in parsed-literal(1) are wrapped like in
     code-block, inline math and footnotes are fully
     functional.

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#parsed-literal

11.80.3 Bugs fixed
------------------

   * #3246: xapian search adapter crashes

   * #3253: In Py2 environment, building another locale with a
     non-captioned toctree produces ‘None’ captions

   * #185: References to section title including raw node has broken

   * #3255: In Py3.4 environment, autodoc doesn’t support documentation
     for attributes of Enum class correctly.

   * #3261: ‘latex_use_parts’ makes sphinx crash

   * The warning type ‘misc.highlighting_failure’ does not work

   * #3294: ‘add_latex_package()’ make crashes non-LaTeX builders

   * The caption of table are rendered as invalid HTML (refs: #3287)

   * #3268: Sphinx crashes with requests package from Debian jessie

   * #3284: Sphinx crashes on parallel build with an extension which
     raises unserializable exception

   * #3315: Bibliography crashes on latex build with docclass ‘memoir’

   * #3328: Could not refer rubric implicitly

   * #3329: emit warnings if po file is invalid and can’t read it.  Also
     writing mo

   * #3337: Ugly rendering of definition list term’s classifier

   * #3335: gettext does not extract field_name of a field in a
     field_list

   * #2952: C++, fix refs to operator() functions.

   * Fix Unicode super- and subscript digits in code-block.
     and parsed-literal LaTeX output (ref #3342)

   * LaTeX writer: leave ‘"’ character inside parsed-literal as is (ref
     #3341)

   * #3234: intersphinx failed for encoded inventories

   * #3158: too much space after captions in PDF output

   * #3317: An URL in parsed-literal contents gets wrongly rendered in
     PDF if with hyphen

   * LaTeX crash if the filename of an image inserted in parsed-literal
     via a substitution contains an hyphen (ref #3340)

   * LaTeX rendering of inserted footnotes in parsed-literal is wrong
     (ref #3340)

   * Inline math in parsed-literal is not rendered well by LaTeX (ref
     #3340)

   * #3308: Parsed-literals don’t wrap very long lines with pdf builder
     (ref #3340)

   * #3295: Could not import extension sphinx.builders.linkcheck

   * #3285: autosummary: asterisks are escaped twice

   * LaTeX, pass dvipdfm option to geometry package for Japanese
     documents (ref #3363)

   * Fix parselinenos() could not parse left half open range (cf.  “-4”)

11.81 Release 1.5.1 (released Dec 13, 2016)
===========================================

11.81.1 Features added
----------------------

   * #3214: Allow to suppress “unknown mimetype” warnings from epub
     builder using suppress_warnings.

11.81.2 Bugs fixed
------------------

   * #3195: Can not build in parallel

   * #3198: AttributeError is raised when toctree has ‘self’

   * #3211: Remove untranslated sphinx locale catalogs (it was covered
     by untranslated it_IT)

   * #3212: HTML Builders crashes with docutils-0.13

   * #3207: more latex problems with references inside parsed-literal
     directive (‘\DUrole’)

   * #3205: sphinx.util.requests crashes with old pyOpenSSL (< 0.14)

   * #3220: KeyError when having a duplicate citation

   * #3200: LaTeX: xref inside desc_name not allowed

   * #3228: ‘build_sphinx’ command crashes when missing dependency

   * #2469: Ignore updates of catalog files for gettext builder.  Thanks
     to Hiroshi Ohkubo.

   * #3183: Randomized jump box order in generated index page.

11.82 Release 1.5 (released Dec 5, 2016)
========================================

11.82.1 Incompatible changes
----------------------------

1.5a1

   * latex, package fancybox is not any longer a dependency of
     sphinx.sty

   * Use ‘'locales'’ as a default value of locale_dirs.

   * latex, package ifthen is not any longer a dependency of sphinx.sty

   * latex, style file does not modify fancyvrb’s Verbatim (also
     available as OriginalVerbatim) but uses sphinxVerbatim for name of
     custom wrapper.

   * latex, package newfloat is not used (and not included) anymore (ref
     #2660; it was used since 1.3.4 and shipped with Sphinx since 1.4).

   * latex, literal blocks in tables do not use OriginalVerbatim but
     sphinxVerbatimintable which handles captions and wraps lines (ref
     #2704).

   * latex, replace ‘pt’ by TeX equivalent ‘bp’ if found in ‘width’ or
     ‘height’ attribute of an image.

   * latex, if ‘width’ or ‘height’ attribute of an image is given with
     no unit, use ‘px’ rather than ignore it.

   * latex: Separate stylesheets of pygments to independent .sty file

   * #2454: The filename of sourcelink is now changed.  The value of
     html_sourcelink_suffix will be appended to the original
     filename (like ‘index.rst.txt’).

   * ‘sphinx.util.copy_static_entry()’ is now deprecated.  Use
     ‘sphinx.util.fileutil.copy_asset()’ instead.

   * ‘sphinx.util.osutil.filecopy()’ skips copying if the file has not
     been changed (ref: #2510, #2753)

   * Internet Explorer 6-8, Opera 12.1x or Safari 5.1+ support is
     dropped because jQuery version is updated from 1.11.0 to 3.1.0
     (ref: #2634, #2773)

   * QtHelpBuilder doesn’t generate search page (ref: #2352)

   * QtHelpBuilder uses ‘nonav’ theme instead of default one to improve
     readability.

   * latex: To provide good default settings to Japanese documents,
     Sphinx uses ‘jreport’ and ‘jsbook’ as docclass if language
     is ‘ja’.

   * ‘sphinx-quickstart’ now allows a project version is empty

   * Fix :download: role on epub/qthelp builder.  They ignore the role
     because they don’t support it.

   * ‘sphinx.ext.viewcode’ doesn’t work on epub building by default.
     ‘viewcode_enable_epub’ option

   * ‘sphinx.ext.viewcode’ disabled on singlehtml builder.

   * Use make-mode of ‘sphinx-quickstart’ by default.  To disable this,
     use ‘-M’ option

   * Fix ‘genindex.html’, Sphinx’s document template, link address to
     itself to satisfy xhtml standard.

   * Use epub3 builder by default.  And the old epub builder is renamed
     to epub2.

   * Fix ‘epub’ and ‘epub3’ builders that contained links to ‘genindex’
     even if ‘epub_use_index = False’.

   * ‘html_translator_class’ is now deprecated.  Use
     Sphinx.set_translator(). API instead.

   * Drop python 2.6 and 3.3 support

   * Drop epub3 builder’s ‘epub3_page_progression_direction’ option (use
     ‘epub3_writing_mode’).

   * #2877: Rename ‘latex_elements['footer']’ to
     ‘latex_elements['atendofbody']’

1.5a2

   * #2983: Rename ‘epub3_description’ and ‘epub3_contributor’ to
     ‘epub_description’ and ‘epub_contributor’.

   * Remove themes/basic/defindex.html; no longer used

   * Sphinx does not ship anymore (but still uses) LaTeX style file
     ‘fncychap’

   * #2435: Slim down quickstarted conf.py

   * The ‘sphinx.sty’ latex package does not load itself “hyperref”, as
     this is done later in the preamble of the latex output via
     ‘'hyperref'’ key.

   * Sphinx does not ship anymore a custom modified LaTeX style file
     ‘tabulary’.  The non-modified package is used.

   * #3057: By default, footnote marks in latex PDF output are not
     preceded by a space anymore, ‘\sphinxBeforeFootnote’ allows user
     customization if needed.

   * LaTeX target requires that option ‘hyperfootnotes’ of package
     ‘hyperref’ be left unchanged to its default (i.e.  ‘true’) (refs:
     #3022)

1.5 final

   * #2986: ‘themes/basic/defindex.html’ is now deprecated

   * Emit warnings that will be deprecated in Sphinx 1.6 by default.
     Users can change the behavior by setting the environment variable
     PYTHONWARNINGS. Please refer Deprecation Warnings.

   * #2454: new JavaScript variable ‘SOURCELINK_SUFFIX’ is added

11.82.2 Deprecated
------------------

These features are removed in Sphinx-1.6:

   * LDML format support in i18n feature

   * ‘sphinx.addnodes.termsep’

   * Some functions and classes in ‘sphinx.util.pycompat’:
     ‘zip_longest’, ‘product’, ‘all’, ‘any’, ‘next’, ‘open’,
     ‘class_types’, ‘base_exception’, ‘relpath’, ‘StringIO’, ‘BytesIO’.
     Please use the standard library version instead;

If any deprecation warning like ‘RemovedInSphinxXXXWarning’ are
displayed, please refer Deprecation Warnings.

11.82.3 Features added
----------------------

1.5a1

   * #2951: Add ‘--implicit-namespaces’ PEP-0420 support to apidoc.

   * Add ‘:caption:’ option for sphinx.ext.inheritance_diagram.

   * #2471: Add config variable for default doctest flags.

   * Convert linkcheck builder to requests for better encoding handling

   * #2463, #2516: Add keywords of “meta” directive to search index

   * ‘:maxdepth:’ option of toctree affects ‘secnumdepth’ (ref: #2547)

   * #2575: Now ‘sphinx.ext.graphviz’ allows ‘:align:’ option

   * Show warnings if unknown key is specified to latex_elements.

   * Show warnings if no domains match with primary_domain.
     (ref: #2001)

   * C++, show warnings when the kind of role is misleading for the kind
     of target it refers to (e.g., using the class role for
     a function).

   * latex, writer abstracts more of text styling into customizable
     macros, e.g.  the ‘visit_emphasis’ will output
     ‘\sphinxstyleemphasis’ rather than ‘\emph’ (which may be in use
     elsewhere or in an added LaTeX package).  See list at end of
     ‘sphinx.sty’ (ref: #2686)

   * latex, public names for environments and parameters used by note,
     warning, and other admonition types, allowing full customizability
     from the ‘'preamble'’ key or an input file (ref: feature request
     #2674, #2685)

   * latex, better computes column widths of some tables (as a result,
     there will be slight changes as tables now correctly fill the line
     width; ref: #2708)

   * latex, sphinxVerbatim environment is more easily customizable (ref:
     #2704).  In addition to already existing VerbatimColor and
     VerbatimBorderColor:

        - two lengths ‘\sphinxverbatimsep’ and ‘\sphinxverbatimborder’,

        - booleans ‘\ifsphinxverbatimwithframe’ and
          ‘\ifsphinxverbatimwrapslines’.

   * latex, captions for literal blocks inside tables are handled, and
     long code lines wrapped to fit table cell (ref: #2704)

   * #2597: Show warning messages as darkred

   * latex, allow image dimensions using px unit (default is 96px=1in)

   * Show warnings if invalid dimension units found

   * #2650: Add ‘--pdb’ option to setup.py command

   * latex, make the use of ‘\small’ for code listings customizable (ref
     #2721)

   * #2663: Add ‘--warning-is-error’ option to setup.py command

   * Show warnings if deprecated latex options are used

   * Add sphinx.config.ENUM to check the config values is in candidates

   * math: Add hyperlink marker to each equations in HTML output

   * Add new theme ‘nonav’ that doesn’t include any navigation links.
     This is for any help generator like qthelp.

   * #2680: sphinx.ext.todo now emits warnings if
     todo_emit_warnings enabled.  Also, it emits an additional
     event named todo-defined to handle the TODO entries in
     3rd party extensions.

   * Python domain signature parser now uses the xref mixin for
     ‘exceptions’, allowing exception classes to be autolinked.

   * #2513: Add latex_engine to switch the LaTeX engine by
     conf.py

   * #2682: C++, basic support for attributes (C++11 style and GNU
     style).  The new configuration variables ‘cpp_id_attributes’ and
     ‘cpp_paren_attributes’ can be used to introduce custom attributes.

   * #1958: C++, add configuration variable ‘cpp_index_common_prefix’
     for removing prefixes from the index text of C++ objects.

   * C++, added concept directive.  Thanks to mickk-on-cpp.

   * C++, added support for template introduction syntax.  Thanks to
     mickk-on-cpp.

   * #2725: latex builder: allow to use user-defined template file
     (experimental)

   * apidoc now avoids invalidating cached files by not writing to files
     whose content doesn’t change.  This can lead to significant
     performance wins if apidoc is run frequently.

   * #2851: ‘sphinx.ext.math’ emits missing-reference event if equation
     not found

   * #1210: ‘eqref’ role now supports cross reference

   * #2892: Added ‘-a’ (‘--append-syspath’) option to ‘sphinx-apidoc’

   * #1604: epub3 builder: Obey font-related CSS when viewing in iBooks.

   * #646: ‘option’ directive support ‘.’ character as a part of options

   * Add document about kindlegen and fix document structure for it.

   * #2474: Add ‘intersphinx_timeout’ option to ‘sphinx.ext.intersphinx’

   * #2926: EPUB3 builder supports vertical mode (‘epub3_writing_mode’
     option)

   * #2695: ‘build_sphinx’ subcommand for setuptools handles exceptions
     as same as ‘sphinx-build’ does

   * #326: numref role can also refer sections

   * #2916: numref role can also refer caption as an its
     linktext

1.5a2

   * #3008: ‘linkcheck’ builder ignores self-signed certificate URL

   * #3020: new ‘'geometry'’ key to ‘latex_elements’ whose default uses
     LaTeX style file ‘geometry.sty’ to set page layout

   * #2843: Add :start-at: and :end-at: options to literalinclude
     directive

   * #2527: Add ‘:reversed:’ option to toctree directive

   * Add ‘-t’ and ‘-d’ option to ‘sphinx-quickstart’ to support
     templating generated sphinx project.

   * #3028: Add ‘{path}’ and ‘{basename}’ to the format of
     ‘figure_language_filename’

   * new ‘'hyperref'’ key in the ‘latex_elements’ dictionary (ref #3030)

   * #3022: Allow code-blocks in footnotes for LaTeX PDF output

1.5b1

   * #2513: A better default settings for XeLaTeX

   * #3096: ‘'maxlistdepth'’ key to work around LaTeX list limitations

   * #3060: autodoc supports documentation for attributes of Enum class.
     Now autodoc render just the value of Enum attributes instead of
     Enum attribute representation.

   * Add ‘--extensions’ to ‘sphinx-quickstart’ to support enable
     arbitrary extensions from command line (ref: #2904)

   * #3104, #3122: ‘'sphinxsetup'’ for key=value styling of Sphinx LaTeX

   * #3071: Autodoc: Allow mocked module decorators to pass-through
     functions unchanged

   * #2495: linkcheck: Allow skipping anchor checking using
     linkcheck_anchors_ignore.

   * #3083: let Unicode no-break space act like LaTeX ‘~’ (fixed #3019)

   * #3116: allow word wrap in PDF output for inline literals (ref
     #3110)

   * #930: sphinx-apidoc allow wildcards for excluding paths.  Thanks to
     Nick Coghlan.

   * #3121: add ‘inlineliteralwraps’ option to control if inline literal
     word-wraps in latex

1.5 final

   * #3095: Add tls_verify and tls_cacerts to
     support self-signed HTTPS servers in linkcheck and intersphinx

   * #2215: make.bat generated by sphinx-quickstart can be called from
     another dir.  Thanks to Timotheus Kampik.

   * #3185: Add new warning type ‘misc.highlighting_failure’

11.82.4 Bugs fixed
------------------

1.5a1

   * #2707: (latex) the column width is badly computed for tabular

   * #2799: Sphinx installs roles and directives automatically on
     importing sphinx module.  Now Sphinx installs them on running
     application.

   * sphinx.ext.autodoc crashes if target code imports * from
     mock modules by autodoc_mock_imports.

   * #1953: ‘Sphinx.add_node’ does not add handlers the translator
     installed by ‘html_translator_class’

   * #1797: text builder inserts blank line on top

   * #2894: quickstart main() doesn’t use argv argument

   * #2874: gettext builder could not extract all text under the ‘only’
     directives

   * #2485: autosummary crashes with multiple source_suffix values

   * #1734: Could not translate the caption of toctree directive

   * Could not translate the content of meta directive (ref: #1734)

   * #2550: external links are opened in help viewer

   * #2687: Running Sphinx multiple times produces ‘already registered’
     warnings

1.5a2

   * #2810: Problems with pdflatex in an Italian document

   * Use ‘latex_elements.papersize’ to specify papersize of LaTeX in
     Makefile

   * #2988: linkcheck: retry with GET request if denied HEAD request

   * #2990: linkcheck raises “Can’t convert ‘bytes’ object to str
     implicitly” error if linkcheck_anchors enabled

   * #3004: Invalid link types “top” and “up” are used

   * #3009: Bad rendering of parsed-literals in LaTeX since Sphinx 1.4.4

   * #3000: ‘option’ directive generates invalid HTML anchors

   * #2984: Invalid HTML has been generated if html_split_index
     enabled

   * #2986: themes/basic/defindex.html should be changed for html5
     friendly

   * #2987: Invalid HTML has been generated if multiple IDs are assigned
     to a list

   * #2891: HTML search does not provide all the results

   * #1986: Title in PDF Output

   * #147: Problem with latex chapter style

   * #3018: LaTeX problem with page layout dimensions and chapter titles

   * Fix an issue with ‘\pysigline’ in LaTeX style file (ref #3023)

   * #3038: ‘sphinx.ext.math*’ raises TypeError if labels are duplicated

   * #3031: incompatibility with LaTeX package ‘tocloft’

   * #3003: literal blocks in footnotes are not supported by Latex

   * #3047: spacing before footnote in pdf output is not coherent and
     allows breaks

   * #3045: HTML search index creator should ignore “raw” content if now
     html

   * #3039: English stemmer returns wrong word if the word is
     capitalized

   * Fix make-mode Makefile template (ref #3056, #2936)

1.5b1

   * #2432: Fix unwanted * between varargs and keyword only args.
     Thanks to Alex Grönholm.

   * #3062: Failed to build PDF using 1.5a2 (undefined ‘\hypersetup’ for
     Japanese documents since PR#3030)

   * Better rendering of multiline signatures in html.

   * #777: LaTeX output “too deeply nested” (ref #3096)

   * Let LaTeX image inclusion obey ‘scale’ before textwidth fit (ref
     #2865, #3059)

   * #3019: LaTeX fails on description of C function with arguments (ref
     #3083)

   * fix latex inline literals where ‘< > -’ gobbled a space

1.5 final

   * #3069: Even if ‘'babel'’ key is set to empty string, LaTeX output
     contains one ‘\addto\captions...’

   * #3123: user ‘'babel'’ key setting is not obeyed anymore

   * #3155: Fix JavaScript for html_sourcelink_suffix fails
     with IE and Opera

   * #3085: keep current directory after breaking build documentation.
     Thanks to Timotheus Kampik.

   * #3181: pLaTeX crashes with a section contains endash

   * #3180: latex: add stretch/shrink between successive singleline or
     multipleline cpp signatures (ref #3072)

   * #3128: globing images does not support .svgz file

   * #3015: fix a broken test on Windows.

   * #1843: Fix documentation of descriptor classes that have a custom
     metaclass.  Thanks to Erik Bray.

   * #3190: util.split_docinfo fails to parse multi-line field bodies

   * #3024, #3037: In Python3, application.Sphinx._log crushed when the
     log message cannot be encoded into console encoding.

11.82.5 Testing
---------------

   * To simplify, sphinx uses external mock package even if
     unittest.mock exists.

11.83 Release 1.4.9 (released Nov 23, 2016)
===========================================

11.83.1 Bugs fixed
------------------

   * #2936: Fix doc/Makefile that can’t build man because doc/man exists

   * #3058: Using the same ‘caption’ attribute in multiple ‘toctree’
     directives results in warning / error

   * #3068: Allow the ‘=’ character in the -D option of sphinx-build.py

   * #3074: ‘add_source_parser()’ crashes in debug mode

   * #3135: ‘sphinx.ext.autodoc’ crashes with plain Callable

   * #3150: Fix query word splitter in JavaScript.  It behaves as same
     as Python’s regular expression.

   * #3093: gettext build broken on substituted images.

   * #3093: gettext build broken on image node under ‘note’ directive.

   * imgmath: crashes on showing error messages if image generation
     failed

   * #3117: LaTeX writer crashes if admonition is placed before first
     section title

   * #3164: Change search order of ‘sphinx.ext.inheritance_diagram’

11.84 Release 1.4.8 (released Oct 1, 2016)
==========================================

11.84.1 Bugs fixed
------------------

   * #2996: The wheel package of Sphinx got crash with ImportError

11.85 Release 1.4.7 (released Oct 1, 2016)
==========================================

11.85.1 Bugs fixed
------------------

   * #2890: Quickstart should return an error consistently on all error
     conditions

   * #2870: flatten genindex columns’ heights.

   * #2856: Search on generated HTML site doesn’t find some symbols

   * #2882: Fall back to a GET request on 403 status in linkcheck

   * #2902: jsdump.loads fails to load search index if keywords starts
     with underscore

   * #2900: Fix epub content.opf: add auto generated orphan files to
     spine.

   * #2899: Fix ‘hasdoc()’ function in Jinja2 template.  It will detect
     ‘genindex’, ‘search’ also.

   * #2901: Fix epub result: skip creating links from image tags to
     original image files.

   * #2917: inline code is hyphenated on HTML

   * #1462: autosummary warns for namedtuple with attribute with
     trailing underscore

   * Could not reference equations if ‘:nowrap:’ option specified

   * #2873: code-block overflow in latex (due to commas)

   * #1060, #2056: sphinx.ext.intersphinx: broken links are generated if
     relative paths are used in intersphinx_mapping.

   * #2931: code-block directive with same :caption: causes warning of
     duplicate target.  Now code-block and
     literalinclude does not define hyperlink target using its
     caption automatically.

   * #2962: latex: missing label of longtable

   * #2968: autodoc: show-inheritance option breaks docstrings

11.86 Release 1.4.6 (released Aug 20, 2016)
===========================================

11.86.1 Incompatible changes
----------------------------

   * #2867: linkcheck builder crashes with six-1.4.  Now Sphinx depends
     on six-1.5 or later

11.86.2 Bugs fixed
------------------

   * applehelp: Sphinx crashes if ‘hiutil’ or ‘codesign’ commands not
     found

   * Fix ‘make clean’ abort issue when build dir contains regular files
     like ‘DS_Store’.

   * Reduce epubcheck warnings/errors:

        * Fix DOCTYPE to html5

        * Change extension from .html to .xhtml.

        * Disable search page on epub results

   * #2778: Fix autodoc crashes if obj.__dict__ is a property method and
     raises exception

   * Fix duplicated toc in epub3 output.

   * #2775: Fix failing linkcheck with servers not supporting identity
     encoding

   * #2833: Fix formatting instance annotations in ext.autodoc.

   * #1911: ‘-D’ option of ‘sphinx-build’ does not override the
     ‘extensions’ variable

   * #2789: sphinx.ext.intersphinx generates wrong hyperlinks
     if the inventory is given

   * parsing errors for caption of code-blocks are displayed in document
     (ref: #2845)

   * #2846: ‘singlehtml’ builder does not include figure numbers

   * #2816: Fix data from builds cluttering the ‘Domain.initial_data’
     class attributes

11.87 Release 1.4.5 (released Jul 13, 2016)
===========================================

11.87.1 Incompatible changes
----------------------------

   * latex, inclusion of non-inline images from image directive resulted
     in non-coherent whitespaces depending on original image width; new
     behaviour by necessity differs from earlier one in some cases.
     (ref: #2672)

   * latex, use of ‘\includegraphics’ to refer to Sphinx custom variant
     is deprecated; in future it will revert to original LaTeX macro,
     custom one already has alternative name ‘\sphinxincludegraphics’.

11.87.2 Features added
----------------------

   * new config option ‘latex_keep_old_macro_names’, defaults to True.
     If False, lets macros (for text styling) be defined only with
     ‘\sphinx’-prefixed names

   * latex writer allows user customization of “shadowed” boxes
     (topics), via three length variables.

   * woff-format web font files now supported by the epub builder.

11.87.3 Bugs fixed
------------------

   * jsdump fix for python 3: fixes the HTML search on python > 3

   * #2676: (latex) Error with verbatim text in captions since Sphinx
     1.4.4

   * #2629: memoir class crashes LaTeX. Fixed by
     ‘latex_keep_old_macro_names=False’ (ref 2675)

   * #2684: sphinx.ext.intersphinx crashes with six-1.4.1

   * #2679: ‘float’ package needed for ‘'figure_align': 'H'’ latex
     option

   * #2671: image directive may lead to inconsistent spacing in pdf

   * #2705: ‘toctree’ generates empty bullet_list if ‘:titlesonly:’
     specified

   * #2479: sphinx.ext.viewcode uses python2 highlighter by
     default

   * #2700: HtmlHelp builder has hard coded index.html

   * latex, since 1.4.4 inline literal text is followed by spurious
     space

   * #2722: C++, fix id generation for var/member declarations to
     include namespaces.

   * latex, images (from image directive) in lists or quoted blocks did
     not obey indentation (fixed together with #2671)

   * #2733: since Sphinx-1.4.4 ‘make latexpdf’ generates lots of
     hyperref warnings

   * #2731: sphinx.ext.autodoc does not access
     propertymethods which raises any exceptions

   * #2666: C++, properly look up nested names involving constructors.

   * #2579: Could not refer a label including both spaces and colons via
     sphinx.ext.intersphinx.

   * #2718: Sphinx crashes if the document file is not readable

   * #2699: hyperlinks in help HTMLs are broken if
     html_file_suffix is set

   * #2723: extra spaces in latex pdf output from multirow cell

   * #2735: latexpdf ‘Underfull \hbox (badness 10000)’ warnings from
     title page

   * #2667: latex crashes if resized images appeared in section title

   * #2763: (html) Provide default value for required ‘alt’ attribute
     for image tags of SVG source, required to validate and now
     consistent w/ other formats.

11.88 Release 1.4.4 (released Jun 12, 2016)
===========================================

11.88.1 Bugs fixed
------------------

   * #2630: latex: sphinx.sty notice environment formatting problem

   * #2632: Warning directives fail in quote environment latex build

   * #2633: Sphinx crashes with old styled indices

   * Fix a ‘\begin{\minipage}’ typo in sphinx.sty from 1.4.2 (ref:
     68becb1)

   * #2622: Latex produces empty pages after title and table of contents

   * #2640: 1.4.2 LaTeX crashes if code-block inside warning directive

   * Let LaTeX use straight quotes also in inline code (ref #2627)

   * #2351: latex crashes if enumerated lists are placed on footnotes

   * #2646: latex crashes if math contains twice empty lines

   * #2480: sphinx.ext.autodoc.: memory addresses were shown

   * latex: allow code-blocks appearing inside lists and quotes at
     maximal nesting depth (ref #777, #2624, #2651)

   * #2635: Latex code directives produce inconsistent frames based on
     viewing resolution

   * #2639: Sphinx now bundles iftex.sty

   * Failed to build PDF with framed.sty 0.95

   * Sphinx now bundles needspace.sty

11.89 Release 1.4.3 (released Jun 5, 2016)
==========================================

11.89.1 Bugs fixed
------------------

   * #2530: got “Counter too large” error on building PDF if large
     numbered footnotes existed in admonitions

   * ‘width’ option of figure directive does not work if ‘align’ option
     specified at same time (ref: #2595)

   * #2590: The ‘inputenc’ package breaks compiling under lualatex and
     xelatex

   * #2540: date on latex front page use different font

   * Suppress “document isn’t included in any toctree” warning if the
     document is included (ref: #2603)

   * #2614: Some tables in PDF output will end up shifted if user sets
     non zero parindent in preamble

   * #2602: URL redirection breaks the hyperlinks generated by
     sphinx.ext.intersphinx.

   * #2613: Show warnings if merged extensions are loaded

   * #2619: make sure amstext LaTeX package always loaded (ref: d657225,
     488ee52, 9d82cad and #2615)

   * #2593: latex crashes if any figures in the table

11.90 Release 1.4.2 (released May 29, 2016)
===========================================

11.90.1 Features added
----------------------

   * Now suppress_warnings accepts following configurations
     (ref: #2451, #2466):

        - ‘app.add_node’

        - ‘app.add_directive’

        - ‘app.add_role’

        - ‘app.add_generic_role’

        - ‘app.add_source_parser’

        - ‘image.data_uri’

        - ‘image.nonlocal_uri’

   * #2453: LaTeX writer allows page breaks in topic contents; and their
     horizontal extent now fits in the line width (with shadow in
     margin).  Also warning-type admonitions allow page breaks and their
     vertical spacing has been made more coherent with the one for
     hint-type notices (ref #2446).

   * #2459: the framing of literal code-blocks in LaTeX output (and not
     only the code lines themselves) obey the indentation in lists or
     quoted blocks.

   * #2343: the long source lines in code-blocks are wrapped (without
     modifying the line numbering) in LaTeX output (ref #1534, #2304).

11.90.2 Bugs fixed
------------------

   * #2370: the equations are slightly misaligned in LaTeX writer

   * #1817, #2077: suppress pep8 warnings on conf.py generated by
     sphinx-quickstart

   * #2407: building docs crash if document includes large data image
     URIs

   * #2436: Sphinx does not check version by needs_sphinx if
     loading extensions failed

   * #2397: Setup shorthandoff for Turkish documents

   * #2447: VerbatimBorderColor wrongly used also for captions of PDF

   * #2456: C++, fix crash related to document merging (e.g., singlehtml
     and Latex builders).

   * #2446: latex(pdf) sets local tables of contents (or more generally
     topic nodes) in unbreakable boxes, causes overflow at bottom

   * #2476: Omit MathJax markers if :nowrap: is given

   * #2465: latex builder fails in case no caption option is provided to
     toctree directive

   * Sphinx crashes if self referenced toctree found

   * #2481: spelling mistake for mecab search splitter.  Thanks to Naoki
     Sato.

   * #2309: Fix could not refer “indirect hyperlink targets” by ref-role

   * intersphinx fails if mapping URL contains any port

   * #2088: intersphinx crashes if the mapping URL requires basic auth

   * #2304: auto line breaks in latexpdf codeblocks

   * #1534: Word wrap long lines in Latex verbatim blocks

   * #2460: too much white space on top of captioned literal blocks in
     PDF output

   * Show error reason when multiple math extensions are loaded (ref:
     #2499)

   * #2483: any figure number was not assigned if figure title contains
     only non text objects

   * #2501: Unicode subscript numbers are normalized in LaTeX

   * #2492: Figure directive with :figwidth: generates incorrect
     Latex-code

   * The caption of figure is always put on center even if ‘:align:’ was
     specified

   * #2526: LaTeX writer crashes if the section having only images

   * #2522: Sphinx touches mo files under installed directory that
     caused permission error.

   * #2536: C++, fix crash when an immediately nested scope has the same
     name as the current scope.

   * #2555: Fix crash on any-references with unicode.

   * #2517: wrong bookmark encoding in PDF if using LuaLaTeX

   * #2521: generated Makefile causes BSD make crashed if sphinx-build
     not found

   * #2470: ‘typing’ backport package causes autodoc errors with python
     2.7

   * ‘sphinx.ext.intersphinx’ crashes if non-string value is used for
     key of intersphinx_mapping.

   * #2518: intersphinx_mapping disallows non alphanumeric
     keys

   * #2558: unpack error on devhelp builder

   * #2561: Info builder crashes when a footnote contains a link

   * #2565: The descriptions of objects generated by
     ‘sphinx.ext.autosummary’ overflow lines at LaTeX writer

   * Extend pdflatex config in sphinx.sty to subparagraphs (ref: #2551)

   * #2445: rst_prolog and rst_epilog affect to
     non reST sources

   * #2576: ‘sphinx.ext.imgmath’ crashes if subprocess raises error

   * #2577: ‘sphinx.ext.imgmath’: Invalid argument are passed to dvisvgm

   * #2556: Xapian search does not work with Python 3

   * #2581: The search doesn’t work if language=”es” (Spanish)

   * #2382: Adjust spacing after abbreviations on figure numbers in
     LaTeX writer

   * #2383: The generated footnote by latex_show_urls.
     overflows lines

   * #2497, #2552: The label of search button does not fit for the
     button itself

11.91 Release 1.4.1 (released Apr 12, 2016)
===========================================

11.91.1 Incompatible changes
----------------------------

   * The default format of today_fmt and
     html_last_updated_fmt is back to strftime format again.
     Locale Date Markup Language is also supported for backward
     compatibility until Sphinx-1.5.

11.91.2 Translations
--------------------

   * Added Welsh translation, thanks to Geraint Palmer.

   * Added Greek translation, thanks to Stelios Vitalis.

   * Added Esperanto translation, thanks to Dinu Gherman.

   * Added Hindi translation, thanks to Purnank H. Ghumalia.

   * Added Romanian translation, thanks to Razvan Stefanescu.

11.91.3 Bugs fixed
------------------

   * C++, added support for ‘extern’ and ‘thread_local’.

   * C++, type declarations are now using the prefixes ‘typedef’,
     ‘using’, and ‘type’, depending on the style of declaration.

   * #2413: C++, fix crash on duplicate declarations

   * #2394: Sphinx crashes when html_last_updated_fmt is invalid

   * #2408: dummy builder not available in Makefile and make.bat

   * #2412: hyperlink targets are broken in LaTeX builder

   * figure directive crashes if non paragraph item is given as caption

   * #2418: time formats no longer allowed in today_fmt

   * #2395: Sphinx crashes if unicode character in image filename

   * #2396: “too many values to unpack” in genindex-single

   * #2405: numref link in PDF jumps to the wrong location

   * #2414: missing number in PDF hyperlinks to code listings

   * #2440: wrong import for gmtime.  Thanks to Uwe L. Korn.

11.92 Release 1.4 (released Mar 28, 2016)
=========================================

11.92.1 Incompatible changes
----------------------------

   * Drop ‘PorterStemmer’ package support.  Use ‘PyStemmer’ instead of
     ‘PorterStemmer’ to accelerate stemming.

   * sphinx_rtd_theme has become optional.  Please install it manually.
     Refs #2087, #2086, #1845 and #2097.  Thanks to Victor Zverovich.

   * #2231: Use DUrole instead of DUspan for custom roles in LaTeX
     writer.  It enables to take title of roles as an argument of custom
     macros.

   * #2022: ‘Thumbs.db’ and ‘.DS_Store’ are added to
     exclude_patterns default values in conf.py that will be
     provided on sphinx-quickstart.

   * #2027, #2208: The ‘html_title’ accepts string values only.  And The
     None value cannot be accepted.

   * ‘sphinx.ext.graphviz’: show graph image in inline by default

   * #2060, #2224: The ‘manpage’ role now generate
     ‘sphinx.addnodes.manpage’ node instead of
     ‘sphinx.addnodes.literal_emphasis’ node.

   * #2022: html_extra_path also copies dotfiles in the
     extra directory, and refers to exclude_patterns to
     exclude extra files and directories.

   * #2300: enhance autoclass:: to use the docstring of __new__ if
     __init__ method’s is missing of empty

   * #2251: Previously, under glossary directives, multiple terms for
     one definition are converted into single ‘term’ node and the each
     terms in the term node are separated by ‘termsep’ node.  In new
     implementation, each terms are converted into individual ‘term’
     nodes and ‘termsep’ node is removed.  By this change, output layout
     of every builders are changed a bit.

   * The default highlight language is now Python 3.  This means that
     source code is highlighted as Python 3 (which is mostly a superset
     of Python 2), and no parsing is attempted to distinguish valid
     code.  To get the old behavior back, add ‘highlight_language =
     "python"’ to conf.py.

   * Locale Date Markup Language(1) like ‘"MMMM dd, YYYY"’ is default
     format for today_fmt and html_last_updated_fmt.
     However strftime format like ‘"%B %d, %Y"’ is also supported
     for backward compatibility until Sphinx-1.5.  Later format will be
     disabled from Sphinx-1.5.

   * #2327: ‘latex_use_parts’ is deprecated now.  Use
     latex_toplevel_sectioning instead.

   * #2337: Use ‘\url{URL}’ macro instead of ‘\href{URL}{URL}’ in LaTeX
     writer.

   * #1498: manpage writer: don’t make whole of item in definition list
     bold if it includes strong node.

   * #582: Remove hint message from quick search box for html output.

   * #2378: Sphinx now bundles newfloat.sty

   ---------- Footnotes ----------

   (1)
https://unicode.org/reports/tr35/tr35-dates.html#Date_Format_Patterns

11.92.2 Features added
----------------------

   * #2092: add todo directive support in napoleon package.

   * #1962: when adding directives, roles or nodes from an extension,
     warn if such an element is already present (built-in or added by
     another extension).

   * #1909: Add “doc” references to Intersphinx inventories.

   * C++ type alias support (e.g., ‘.. type:: T = int’).

   * C++ template support for classes, functions, type aliases, and
     variables (#1729, #1314).

   * C++, added new scope management directives ‘namespace-push’ and
     ‘namespace-pop’.

   * #1970: Keyboard shortcuts to navigate Next and Previous topics

   * Intersphinx: Added support for fetching Intersphinx inventories
     with URLs using HTTP basic auth.

   * C++, added support for template parameter in function info field
     lists.

   * C++, added support for pointers to member (function).

   * #2113: Allow ‘:class:’ option to code-block directive.

   * #2192: Imgmath (pngmath with svg support).

   * #2200: Support XeTeX and LuaTeX for the LaTeX builder.

   * #1906: Use xcolor over color for fcolorbox where available for
     LaTeX output.

   * #2216: Texinputs makefile improvements.

   * #2170: Support for Chinese language search index.

   * #2214: Add sphinx.ext.githubpages to publish the docs on GitHub
     Pages

   * #1030: Make page reference names for latex_show_pagerefs
     translatable

   * #2162: Add Sphinx.add_source_parser() to add source_suffix and
     source_parsers from extension

   * #2207: Add sphinx.parsers.Parser class; a base class for new
     parsers

   * #656: Add ‘graphviz_dot’ option to graphviz directives to switch
     the ‘dot’ command

   * #1939: Added the ‘dummy’ builder: syntax check without output.

   * #2230: Add ‘math_number_all’ option to number all displayed math in
     math extensions

   * #2235: ‘needs_sphinx’ supports micro version comparison

   * #2282: Add “language” attribute to html tag in the “basic” theme

   * #1779: Add EPUB 3 builder

   * #1751: Add todo_link_only to avoid file path and line
     indication on todolist.  Thanks to Francesco Montesano.

   * #2199: Use ‘imagesize’ package to obtain size of images.

   * #1099: Add configurable retries to the linkcheck builder.  Thanks
     to Alex Gaynor.  Also don’t check anchors starting with ‘!’.

   * #2300: enhance autoclass:: to use the docstring of __new__ if
     __init__ method’s is missing of empty

   * #1858: Add Sphinx.add_enumerable_node() to add enumerable nodes for
     numfig feature

   * #1286, #2099: Add ‘sphinx.ext.autosectionlabel’ extension to allow
     reference sections using its title.  Thanks to Tadhg O’Higgins.

   * #1854: Allow to choose Janome for Japanese splitter.

   * #1853: support custom text splitter on html search with
     ‘language='ja'’.

   * #2320: classifier of glossary terms can be used for index entries
     grouping key The classifier also be used for translation.  See also
     Glossary.

   * #2308: Define ‘\tablecontinued’ macro to redefine the style of
     continued label for longtables.

   * Select an image by similarity if multiple images are globbed by ‘..
     image:: filename.*’

   * #1921: Support figure substitutions by language and
     figure_language_filename.

   * #2245: Add ‘latex_elements["passoptionstopackages"]’ option to call
     PassOptionsToPackages in early stage of preambles.

   * #2340: Math extension: support alignment of multiple equations for
     MathJax.

   * #2338: Define ‘\titleref’ macro to redefine the style of
     ‘title-reference’ roles.

   * Define ‘\menuselection’ and ‘\accelerator’ macros to redefine the
     style of menuselection roles.

   * Define ‘\crossref’ macro to redefine the style of references

   * #2301: Texts in the classic html theme should be hyphenated.

   * #2355: Define ‘\termref’ macro to redefine the style of ‘term’
     roles.

   * Add suppress_warnings to suppress arbitrary warning
     message (experimental)

   * #2229: Fix no warning is given for unknown options

   * #2327: Add latex_toplevel_sectioning to switch the top
     level sectioning of LaTeX document.

11.92.3 Bugs fixed
------------------

   * #1913: C++, fix assert bug for enumerators in next-to-global and
     global scope.

   * C++, fix parsing of ‘signed char’ and ‘unsigned char’ as types.

   * C++, add missing support for ‘friend’ functions.

   * C++, add missing support for virtual base classes (thanks to
     Rapptz).

   * C++, add support for final classes.

   * C++, fix parsing of types prefixed with ‘enum’.

   * #2023: Dutch search support uses Danish stemming info.

   * C++, add support for user-defined literals.

   * #1804: Now html output wraps overflowed long-line-text in the
     sidebar.  Thanks to Hassen ben tanfous.

   * #2183: Fix porterstemmer causes ‘make json’ to fail.

   * #1899: Ensure list is sent to OptParse.

   * #2164: Fix wrong check for pdftex inside sphinx.sty (for graphicx
     package option).

   * #2165, #2218: Remove faulty and non-need conditional from
     sphinx.sty.

   * Fix broken LaTeX code is generated if unknown language is given

   * #1944: Fix rst_prolog breaks file-wide metadata

   * #2074: make gettext should use canonical relative paths for .pot.
     Thanks to anatoly techtonik.

   * #2311: Fix sphinx.ext.inheritance_diagram raises AttributeError

   * #2251: Line breaks in .rst files are transferred to .pot files in a
     wrong way.

   * #794: Fix date formatting in latex output is not localized

   * Remove ‘image/gif’ from supported_image_types of LaTeX writer
     (#2272)

   * Fix ValueError is raised if LANGUAGE is empty string

   * Fix unpack warning is shown when the directives generated from
     ‘Sphinx.add_crossref_type’ is used

   * The default highlight language is now ‘default’.  This means that
     source code is highlighted as Python 3 (which is mostly a superset
     of Python 2) if possible.  To get the old behavior back, add
     ‘highlight_language = "python"’ to conf.py.

   * #2329: Refresh environment forcedly if source directory has
     changed.

   * #2331: Fix code-blocks are filled by block in dvi; remove ‘xcdraw’
     option from xcolor package

   * Fix the confval type checker emits warnings if unicode is given to
     confvals which expects string value

   * #2360: Fix numref in LaTeX output is broken

   * #2361: Fix additional paragraphs inside the “compound” directive
     are indented

   * #2364: Fix KeyError ‘rootSymbol’ on Sphinx upgrade from older
     version.

   * #2348: Move amsmath and amssymb to before fontpkg on LaTeX writer.

   * #2368: Ignore emacs lock files like ‘.#foo.rst’ by default.

   * #2262: literal_block and its caption has been separated by
     pagebreak in LaTeX output.

   * #2319: Fix table counter is overridden by code-block’s in LaTeX.
     Thanks to jfbu.

   * Fix unpack warning if combined with 3rd party domain extensions.

   * #1153: Fix figures in sidebar causes latex build error.

   * #2358: Fix user-preamble could not override the tocdepth
     definition.

   * #2358: Reduce tocdepth if ‘part’ or ‘chapter’ is used for
     top_sectionlevel

   * #2351: Fix footnote spacing

   * #2363: Fix ‘toctree()’ in templates generates broken links in
     SingleHTMLBuilder.

   * #2366: Fix empty hyperref is generated on toctree in HTML builder.

11.92.4 Documentation
---------------------

   * #1757: Fix for usage of html_last_updated_fmt.  Thanks
     to Ralf Hemmecke.

11.93 Release 1.3.6 (released Feb 29, 2016)
===========================================

11.93.1 Features added
----------------------

   * #1873, #1876, #2278: Add ‘page_source_suffix’ html context
     variable.  This should be introduced with source_parsers
     feature.  Thanks for Eric Holscher.

11.93.2 Bugs fixed
------------------

   * #2265: Fix babel is used in spite of disabling it on
     ‘latex_elements’

   * #2295: Avoid mutating dictionary errors while enumerating members
     in autodoc with Python 3

   * #2291: Fix pdflatex “Counter too large” error from footnotes inside
     tables of contents

   * #2292: Fix some footnotes disappear from LaTeX output

   * #2287: ‘sphinx.transforms.Locale’ always uses rst parser.  Sphinx
     i18n feature should support parsers that specified source_parsers.

   * #2290: Fix ‘sphinx.ext.mathbase’ use of amsfonts may break user
     choice of math fonts

   * #2324: Print a hint how to increase the recursion limit when it is
     hit.

   * #1565, #2229: Revert new warning; the new warning will be triggered
     from version 1.4 on.

   * #2329: Refresh environment forcedly if source directory has
     changed.

   * #2019: Fix the domain objects in search result are not escaped

11.94 Release 1.3.5 (released Jan 24, 2016)
===========================================

11.94.1 Bugs fixed
------------------

   * Fix line numbers was not shown on warnings in LaTeX and texinfo
     builders

   * Fix filenames were not shown on warnings of citations

   * Fix line numbers was not shown on warnings in LaTeX and texinfo
     builders

   * Fix line numbers was not shown on warnings of indices

   * #2026: Fix LaTeX builder raises error if parsed-literal includes
     links

   * #2243: Ignore strange docstring types for classes, do not crash

   * #2247: Fix #2205 breaks make html for definition list with
     classifiers that contains regular-expression like string

   * #1565: Sphinx will now emit a warning that highlighting was skipped
     if the syntax is incorrect for code-block,
     literalinclude and so on.

   * #2211: Fix paragraphs in table cell doesn’t work in Latex output

   * #2253: ‘:pyobject:’ option of ‘literalinclude’ directive can’t
     detect indented body block when the block starts with blank or
     comment lines.

   * Fix TOC is not shown when no ‘:maxdepth:’ for toctrees (ref: #771)

   * Fix warning message for ‘:numref:’ if target is in orphaned doc
     (ref: #2244)

11.95 Release 1.3.4 (released Jan 12, 2016)
===========================================

11.95.1 Bugs fixed
------------------

   * #2134: Fix figure caption with reference causes latex build error

   * #2094: Fix rubric with reference not working in Latex

   * #2147: Fix literalinclude code in latex does not break in pages

   * #1833: Fix email addresses is showed again if latex_show_urls is
     not None

   * #2176: sphinx.ext.graphviz: use <object> instead of <img> to embed
     svg

   * #967: Fix SVG inheritance diagram is not hyperlinked (clickable)

   * #1237: Fix footnotes not working in definition list in LaTeX

   * #2168: Fix raw directive does not work for text writer

   * #2171: Fix cannot linkcheck url with unicode

   * #2182: LaTeX: support image file names with more than 1 dots

   * #2189: Fix previous sibling link for first file in subdirectory
     uses last file, not intended previous from root toctree

   * #2003: Fix decode error under python2 (only) when ‘make linkcheck’
     is run

   * #2186: Fix LaTeX output of mathbb in math

   * #1480, #2188: LaTeX: Support math in section titles

   * #2071: Fix same footnote in more than two section titles =>
     LaTeX/PDF Bug

   * #2040: Fix UnicodeDecodeError in sphinx-apidoc when author contains
     non-ascii characters

   * #2193: Fix shutil.SameFileError if source directory and destination
     directory are same

   * #2178: Fix unparsable C++ cross-reference when referencing a
     function with :cpp:any:

   * #2206: Fix Sphinx latex doc build failed due to a footnotes

   * #2201: Fix wrong table caption for tables with over 30 rows

   * #2213: Set <blockquote> in the classic theme to fit with <p>

   * #1815: Fix linkcheck does not raise an exception if warniserror set
     to true and link is broken

   * #2197: Fix slightly cryptic error message for missing index.rst
     file

   * #1894: Unlisted phony targets in quickstart Makefile

   * #2125: Fix unifies behavior of collapsed fields (‘GroupedField’ and
     ‘TypedField’)

   * #1408: Check latex_logo validity before copying

   * #771: Fix latex output doesn’t set tocdepth

   * #1820: On Windows, console coloring is broken with colorama version
     0.3.3.  Now sphinx use colorama>=0.3.5 to avoid this problem.

   * #2072: Fix footnotes in chapter-titles do not appear in PDF output

   * #1580: Fix paragraphs in longtable don’t work in Latex output

   * #1366: Fix centered image not centered in latex

   * #1860: Fix man page using ‘:samp:’ with braces - font doesn’t reset

   * #1610: Sphinx crashes in Japanese indexing in some systems

   * Fix Sphinx crashes if mecab initialization failed

   * #2160: Fix broken TOC of PDFs if section includes an image

   * #2172: Fix dysfunctional admonition ‘\py@lightbox’ in sphinx.sty.
     Thanks to jfbu.

   * #2198,#2205: ‘make gettext’ generate broken msgid for definition
     lists.

   * #2062: Escape characters in doctests are treated incorrectly with
     Python 2.

   * #2225: Fix if the option does not begin with dash, linking is not
     performed

   * #2226: Fix math is not HTML-encoded when :nowrap: is given (jsmath,
     mathjax)

   * #1601, #2220: ‘any’ role breaks extended domains behavior.
     Affected extensions doesn’t support resolve_any_xref and
     resolve_xref returns problematic node instead of None.
     sphinxcontrib-httpdomain is one of them.

   * #2229: Fix no warning is given for unknown options

11.96 Release 1.3.3 (released Dec 2, 2015)
==========================================

11.96.1 Bugs fixed
------------------

   * #2177: Fix parallel hangs

   * #2012: Fix exception occurred if ‘numfig_format’ is invalid

   * #2142: Provide non-minified JS code in
     ‘sphinx/search/non-minified-js/*.js’ for source distribution on
     PyPI.

   * #2148: Error while building devhelp target with non-ASCII document.

11.97 Release 1.3.2 (released Nov 29, 2015)
===========================================

11.97.1 Features added
----------------------

   * #1935: Make “numfig_format” overridable in latex_elements.

11.97.2 Bugs fixed
------------------

   * #1976: Avoid “2.0” version of Babel because it doesn’t work with
     Windows environment.

   * Add a “default.css” stylesheet (which imports “classic.css”) for
     compatibility

   * #1788: graphviz extension raises exception when caption option is
     present.

   * #1789: ‘:pyobject:’ option of ‘literalinclude’ directive includes
     following lines after class definitions

   * #1790: ‘literalinclude’ strips empty lines at the head and tail

   * #1802: load plugin themes automatically when theme.conf use it as
     ‘inherit’.  Thanks to Takayuki Hirai.

   * #1794: custom theme extended from alabaster or sphinx_rtd_theme
     can’t find base theme.

   * #1834: compatibility for docutils-0.13: handle_io_errors keyword
     argument for docutils.io.FileInput cause TypeError.

   * #1823: ‘.’ as <module_path> for sphinx-apidoc cause an unfriendly
     error.  Now ‘.’ is converted to absolute path automatically.

   * Fix a crash when setting up extensions which do not support
     metadata.

   * #1784: Provide non-minified JS code in
     ‘sphinx/search/non-minified-js/*.js’

   * #1822, #1892: Fix regression for #1061.  autosummary can’t generate
     doc for imported members since sphinx-1.3b3.  Thanks to Eric
     Larson.

   * #1793, #1819: “see also” misses a linebreak in text output.  Thanks
     to Takayuki Hirai.

   * #1780, #1866: “make text” shows “class” keyword twice.  Thanks to
     Takayuki Hirai.

   * #1871: Fix for LaTeX output of tables with one column and
     multirows.

   * Work around the lack of the HTMLParserError exception in Python
     3.5.

   * #1949: Use ‘safe_getattr’ in the coverage builder to avoid aborting
     with descriptors that have custom behavior.

   * #1915: Do not generate smart quotes in doc field type annotations.

   * #1796: On py3, automated .mo building caused UnicodeDecodeError.

   * #1923: Use babel features only if the babel latex element is
     nonempty.

   * #1942: Fix a KeyError in websupport.

   * #1903: Fix strange id generation for glossary terms.

   * ‘make text’ will crush if a definition list item has more than 1
     classifiers as: ‘term : classifier1 : classifier2’.

   * #1855: make gettext generates broken po file for definition lists
     with classifier.

   * #1869: Fix problems when dealing with files containing non-ASCII
     characters.  Thanks to Marvin Schmidt.

   * #1798: Fix building LaTeX with references in titles.

   * #1725: On py2 environment, doctest with using non-ASCII characters
     causes ‘'ascii' codec can't decode byte’ exception.

   * #1540: Fix RuntimeError with circular referenced toctree

   * #1983: i18n translation feature breaks references which uses
     section name.

   * #1990: Use caption of toctree to title of tableofcontents in LaTeX

   * #1987: Fix ampersand is ignored in ‘:menuselection:’ and
     ‘:guilabel:’ on LaTeX builder

   * #1994: More supporting non-standard parser (like recommonmark
     parser) for Translation and WebSupport feature.  Now node.rawsource
     is fall backed to node.astext() during docutils transforming.

   * #1989: “make blahblah” on Windows indicate help messages for
     sphinx-build every time.  It was caused by wrong make.bat that
     generated by Sphinx-1.3.0/1.3.1.

   * On Py2 environment, conf.py that is generated by sphinx-quickstart
     should have u prefixed config value for ‘version’ and ‘release’.

   * #2102: On Windows + Py3, using ‘|today|’ and non-ASCII date format
     will raise UnicodeEncodeError.

   * #1974: UnboundLocalError: local variable ‘domain’ referenced before
     assignment when using any role and
     sphinx.ext.intersphinx in same time.

   * #2121: multiple words search doesn’t find pages when words across
     on the page title and the page content.

   * #1884, #1885: plug-in html themes cannot inherit another plug-in
     theme.  Thanks to Suzumizaki.

   * #1818: sphinx.ext.todo directive generates broken html
     class attribute as ‘admonition-’ when language is
     specified with non-ASCII linguistic area like ‘ru’ or ‘ja’.  To fix
     this, now ‘todo’ directive can use ‘:class:’ option.

   * #2140: Fix footnotes in table has broken in LaTeX

   * #2127: MecabBinder for html searching feature doesn’t work with
     Python 3.  Thanks to Tomoko Uchida.

11.98 Release 1.3.1 (released Mar 17, 2015)
===========================================

11.98.1 Bugs fixed
------------------

   * #1769: allows generating quickstart files/dirs for destination dir
     that doesn’t overwrite existent files/dirs.  Thanks to WAKAYAMA
     shirou.

   * #1773: sphinx-quickstart doesn’t accept non-ASCII character as a
     option argument.

   * #1766: the message “least Python 2.6 to run” is at best misleading.

   * #1772: cross reference in docstrings like ‘:param .write:’ breaks
     building.

   * #1770, #1774: ‘literalinclude’ with empty file occurs exception.
     Thanks to Takayuki Hirai.

   * #1777: Sphinx 1.3 can’t load extra theme.  Thanks to tell-k.

   * #1776: ‘source_suffix = ['.rst']’ cause unfriendly error on prior
     version.

   * #1771: automated .mo building doesn’t work properly.

   * #1783: Autodoc: Python2 Allow unicode string in __all__.  Thanks to
     Jens Hedegaard Nielsen.

   * #1781: Setting html_domain_indices to a list raises a
     type check warnings.

11.99 Release 1.3 (released Mar 10, 2015)
=========================================

11.99.1 Incompatible changes
----------------------------

   * Roles ‘ref’, ‘term’ and ‘menusel’ now don’t generate emphasis(1)
     nodes anymore.  If you want to keep italic style, adapt your
     stylesheet.

   * Role ‘numref’ uses ‘%s’ as special character to indicate position
     of figure numbers instead ‘#’ symbol.

   ---------- Footnotes ----------

   (1) https://docutils.sourceforge.io/docs/ref/rst/roles.html#emphasis

11.99.2 Features added
----------------------

   * Add convenience directives and roles to the C++ domain: directive
     ‘cpp:var’ as alias for ‘cpp:member’, role ‘:cpp:var’ as alias for
     ‘:cpp:member’, and role any for cross-reference to any
     C++ declaraction.  #1577, #1744

   * The source_suffix config value can now be a list of
     multiple suffixes.

   * Add the ability to specify source parsers by source suffix with the
     source_parsers config value.

   * #1675: A new builder, AppleHelpBuilder, has been added that builds
     Apple Help Books.

11.99.3 Bugs fixed
------------------

   * 1.3b3 change breaks a previous gettext output that contains
     duplicated msgid such as “foo bar” and “version changes in 1.3: foo
     bar”.

   * #1745: latex builder cause maximum recursion depth exceeded when a
     footnote has a footnote mark itself.

   * #1748: SyntaxError in sphinx/ext/ifconfig.py with Python 2.6.

   * #1658, #1750: No link created (and warning given) if option does
     not begin with -, / or +.  Thanks to Takayuki Hirai.

   * #1753: C++, added missing support for more complex declarations.

   * #1700: Add ‘:caption:’ option for toctree.

   * #1742: ‘:name:’ option is provided for toctree,
     code-block and literalinclude directives.

   * #1756: Incorrect section titles in search that was introduced from
     1.3b3.

   * #1746: C++, fixed name lookup procedure, and added missing lookups
     in declarations.

   * #1765: C++, fix old id generation to use fully qualified names.

11.99.4 Documentation
---------------------

   * #1651: Add ‘vartype’ field description for python domain.

11.100 Release 1.3b3 (released Feb 24, 2015)
============================================

11.100.1 Incompatible changes
-----------------------------

   * Dependency requirement updates: docutils 0.11, Pygments 2.0

   * The ‘gettext_enables’ config value has been renamed to
     gettext_additional_targets.

   * #1735: Use ‘https://docs.python.org/’ instead of ‘http’ protocol.
     It was used for sphinx.ext.intersphinx and some
     documentation.

11.100.2 Features added
-----------------------

   * #1346: Add new default theme;

        * Add ‘alabaster’ theme.

        * Add ‘sphinx_rtd_theme’ theme.

        * The ‘default’ html theme has been renamed to ‘classic’.
          ‘default’ is still available, however it will emit notice a
          recommendation that using new ‘alabaster’ theme.

   * Added ‘highlight_options’ configuration value.

   * The ‘language’ config value is now available in the HTML templates.

   * The ‘env-updated’ event can now return a value, which is
     interpreted as an iterable of additional docnames that need to be
     rewritten.

   * #772: Support for scoped and unscoped enums in C++.  Enumerators in
     unscoped enums are injected into the parent scope in addition to
     the enum scope.

   * Add ‘todo_include_todos’ config option to quickstart conf file,
     handled as described in documentation.

   * HTML breadcrumb items tag has class “nav-item” and “nav-item-N”
     (like nav-item-0, 1, 2…).

   * New option sphinx-quickstart –use-make-mode for
     generating Makefile that use sphinx-build make-mode.

   * #1235: i18n: several node can be translated if it is set to
     gettext_additional_targets in conf.py.  Supported nodes are:

        - ‘literal-block’

        - ‘doctest-block’

        - ‘raw’

        - ‘image’

   * #1227: Add html_scaled_image_link config option to
     conf.py, to control scaled image link.

11.100.3 Bugs fixed
-------------------

   * LaTeX writer now generates correct markup for cells spanning
     multiple rows.

   * #1674: Do not crash if a module’s ‘__all__’ is not a list of
     strings.

   * #1629: Use VerbatimBorderColor to add frame to code-block in LaTeX

   * On windows, make-mode didn’t work on Win32 platform if sphinx was
     invoked as ‘python sphinx-build.py’.

   * #1687: linkcheck now treats 401 Unauthorized responses as
     “working”.

   * #1690: toctrees with ‘glob’ option now can also contain entries for
     single documents with explicit title.

   * #1591: html search results for C++ elements now has correct
     interpage links.

   * bizstyle theme: nested long title pages make long breadcrumb that
     breaks page layout.

   * bizstyle theme: all breadcrumb items become ‘Top’ on some mobile
     browser (iPhone5s safari).

   * #1722: restore ‘toctree()’ template function behavior that was
     changed at 1.3b1.

   * #1732: i18n: localized table caption raises exception.

   * #1718: ‘:numref:’ does not work with capital letters in the label

   * #1630: resolve CSS conflicts, ‘div.container’ css target for
     literal block wrapper now renamed to ‘div.literal-block-wrapper’.

   * ‘sphinx.util.pycompat’ has been restored in its
     backwards-compatibility; slated for removal in Sphinx 1.4.

   * #1719: LaTeX writer does not respect ‘numref_format’ option in
     captions

11.101 Release 1.3b2 (released Dec 5, 2014)
===========================================

11.101.1 Incompatible changes
-----------------------------

   * update bundled ez_setup.py for setuptools-7.0 that requires Python
     2.6 or later.

11.101.2 Features added
-----------------------

   * #1597: Added possibility to return a new template name from
     html-page-context.

   * PR#314, #1150: Configuration values are now checked for their type.
     A warning is raised if the configured and the default value do not
     have the same type and do not share a common non-trivial base
     class.

11.101.3 Bugs fixed
-------------------

   * PR#311: sphinx-quickstart does not work on python 3.4.

   * Fix autodoc_docstring_signature not working with
     signatures in class docstrings.

   * Rebuilding cause crash unexpectedly when source files were added.

   * #1607: Fix a crash when building latexpdf with “howto” class

   * #1251: Fix again.  Sections which depth are lower than :tocdepth:
     should not be shown on localtoc sidebar.

   * make-mode didn’t work on Win32 platform if sphinx was installed by
     wheel package.

11.102 Release 1.3b1 (released Oct 10, 2014)
============================================

11.102.1 Incompatible changes
-----------------------------

   * Dropped support for Python 2.5, 3.1 and 3.2.

   * Dropped support for docutils versions up to 0.9.

   * Removed the ‘sphinx.ext.oldcmarkup’ extension.

   * The deprecated config values ‘exclude_trees’, ‘exclude_dirnames’
     and ‘unused_docs’ have been removed.

   * A new node, ‘sphinx.addnodes.literal_strong’, has been added, for
     text that should appear literally (i.e.  no smart quotes) in strong
     font.  Custom writers will have to be adapted to handle this node.

   * PR#269, #1476: replace ‘<tt>’ tag by ‘<code>’.  User customized
     stylesheets should be updated If the css contain some styles for
     ‘tt>’ tag.  Thanks to Takeshi Komiya.

   * #1543: templates_path is automatically added to
     exclude_patterns to avoid reading autosummary rst templates in
     the templates directory.

   * Custom domains should implement the new
     Domain.resolve_any_xref method to make the any.
     role work properly.

   * gettext builder: gettext doesn’t emit uuid information to generated
     pot files by default.  Please set ‘True’ to gettext_uuid
     to emit uuid information.  Additionally, if the
     ‘python-levenshtein’ 3rd-party package is installed, it will
     improve the calculation time.

   * gettext builder: disable extracting/apply ‘index’ node by default.
     Please set ‘index’ to ‘gettext_enables’ to enable extracting index
     entries.

   * PR#307: Add frame to code-block in LaTeX. Thanks to Takeshi Komiya.

11.102.2 Features added
-----------------------

   * Add support for Python 3.4.

   * Add support for docutils 0.12

   * Added ‘sphinx.ext.napoleon’ extension for NumPy and Google style
     docstring support.

   * Added support for parallel reading (parsing) of source files with
     the sphinx-build -j option.  Third-party extensions
     will need to be checked for compatibility and may need to be
     adapted if they store information in the build environment object.
     See env-merge-info.

   * Added the any role that can be used to find a
     cross-reference of `any' type in `any' domain.  Custom domains
     should implement the new Domain.resolve_any_xref method
     to make this work properly.

   * Exception logs now contain the last 10 messages emitted by Sphinx.

   * Added support for extension versions (a string returned by
     ‘setup()’, these can be shown in the traceback log files).  Version
     requirements for extensions can be specified in projects using the
     new needs_extensions config value.

   * Changing the default role within a document with the
     default-role(1) directive is now supported.

   * PR#214: Added stemming support for 14 languages, so that the
     built-in document search can now handle these.  Thanks to Shibukawa
     Yoshiki.

   * PR#296, PR#303, #76: numfig feature: Assign numbers to figures,
     tables and code-blocks.  This feature is configured with
     numfig, numfig_secnum_depth and
     numfig_format.  Also numref role is available.
     Thanks to Takeshi Komiya.

   * PR#202: Allow “.” and “~” prefixed references in ‘:param:’ doc
     fields for Python.

   * PR#184: Add autodoc_mock_imports, allowing to mock
     imports of external modules that need not be present when
     autodocumenting.

   * #925: Allow list-typed config values to be provided on the command
     line, like ‘-D key=val1,val2’.

   * #668: Allow line numbering of code-block and
     literalinclude directives to start at an arbitrary line
     number, with a new ‘lineno-start’ option.

   * PR#172, PR#266: The code-block and literalinclude
     directives now can have a ‘caption’ option that shows a
     filename before the code in the output.  Thanks to Nasimul Haque,
     Takeshi Komiya.

   * Prompt for the document language in sphinx-quickstart.

   * PR#217: Added config values to suppress UUID and location
     information in generated gettext catalogs.

   * PR#236, #1456: apidoc: Add a -M option to put module documentation
     before submodule documentation.  Thanks to Wes Turner and Luc
     Saffre.

   * #1434: Provide non-minified JS files for jquery.js and
     underscore.js to clarify the source of the minified files.

   * PR#252, #1291: Windows color console support.  Thanks to meu31.

   * PR#255: When generating latex references, also insert latex
     target/anchor for the ids defined on the node.  Thanks to Olivier
     Heurtier.

   * PR#229: Allow registration of other translators.  Thanks to Russell
     Sim.

   * Add app.set_translator() API to register or override a Docutils
     translator class like ‘html_translator_class’.

   * PR#267, #1134: add ‘diff’ parameter to literalinclude.  Thanks to
     Richard Wall and WAKAYAMA shirou.

   * PR#272: Added ‘bizstyle’ theme.  Thanks to Shoji KUMAGAI.

   * Automatically compile ‘*.mo’ files from ‘*.po’ files when
     gettext_auto_build is True (default) and ‘*.po’ is newer than
     ‘*.mo’ file.

   * #623: sphinx.ext.viewcode supports imported
     function/class aliases.

   * PR#275: sphinx.ext.intersphinx supports multiple target
     for the inventory.  Thanks to Brigitta Sipocz.

   * PR#261: Added the env-before-read-docs event that can
     be connected to modify the order of documents before they are read
     by the environment.

   * #1284: Program options documented with option can now
     start with ‘+’.

   * PR#291: The caption of code-block is recognized as a
     title of ref target.  Thanks to Takeshi Komiya.

   * PR#298: Add new API: add_latex_package().  Thanks to
     Takeshi Komiya.

   * #1344: add ‘gettext_enables’ to enable extracting ‘index’ to
     gettext catalog output / applying translation catalog to generated
     documentation.

   * PR#301, #1583: Allow the line numbering of the directive
     literalinclude to match that of the included file, using a new
     ‘lineno-match’ option.  Thanks to Jeppe Pihl.

   * PR#299: add various options to sphinx-quickstart.  Quiet mode
     option ‘--quiet’ will skips wizard mode.  Thanks to WAKAYAMA
     shirou.

   * #1623: Return types specified with ‘:rtype:’ are now turned into
     links if possible.

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#default-role

11.102.3 Bugs fixed
-------------------

   * #1438: Updated jQuery version from 1.8.3 to 1.11.1.

   * #1568: Fix a crash when a “centered” directive contains a
     reference.

   * Now sphinx.ext.autodoc works with python-2.5 again.

   * #1563: add_search_language() raises AssertionError for
     correct type of argument.  Thanks to rikoman.

   * #1174: Fix smart quotes being applied inside roles like
     program or makevar.

   * PR#235: comment db schema of websupport lacked a length of the
     node_id field.  Thanks to solos.

   * #1466,PR#241: Fix failure of the cpp domain parser to parse C+11
     “variadic templates” declarations.  Thanks to Victor Zverovich.

   * #1459,PR#244: Fix default mathjax js path point to ‘http://’ that
     cause mixed-content error on HTTPS server.  Thanks to sbrandtb and
     robo9k.

   * PR#157: autodoc remove spurious signatures from @property decorated
     attributes.  Thanks to David Ham.

   * PR#159: Add coverage targets to quickstart generated Makefile and
     make.bat.  Thanks to Matthias Troffaes.

   * #1251: When specifying toctree :numbered: option and :tocdepth:
     metadata, sub section number that is larger depth than ‘:tocdepth:’
     is shrunk.

   * PR#260: Encode underscore in citation labels for latex export.
     Thanks to Lennart Fricke.

   * PR#264: Fix could not resolve xref for figure node with :name:
     option.  Thanks to Takeshi Komiya.

   * PR#265: Fix could not capture caption of graphviz node by xref.
     Thanks to Takeshi Komiya.

   * PR#263, #1013, #1103: Rewrite of C++ domain.  Thanks to Jakob Lykke
     Andersen.

        * Hyperlinks to all found nested names and template arguments
          (#1103).

        * Support for function types everywhere, e.g., in
          std::function<bool(int, int)> (#1013).

        * Support for virtual functions.

        * Changed interpretation of function arguments to following
          standard prototype declarations, i.e., void f(arg) means that
          arg is the type of the argument, instead of it being the name.

        * Updated tests.

        * Updated documentation with elaborate description of what
          declarations are supported and how the namespace declarations
          influence declaration and cross-reference lookup.

        * Index names may be different now.  Elements are indexed by
          their fully qualified name.  It should be rather easy to
          change this behaviour and potentially index by
          namespaces/classes as well.

   * PR#258, #939: Add dedent option for code-block and
     literalinclude.  Thanks to Zafar Siddiqui.

   * PR#268: Fix numbering section does not work at singlehtml mode.  It
     still ad-hoc fix because there is a issue that section IDs are
     conflicted.  Thanks to Takeshi Komiya.

   * PR#273, #1536: Fix RuntimeError with numbered circular toctree.
     Thanks to Takeshi Komiya.

   * PR#274: Set its URL as a default title value if URL appears in
     toctree.  Thanks to Takeshi Komiya.

   * PR#276, #1381: rfc and pep roles support
     custom link text.  Thanks to Takeshi Komiya.

   * PR#277, #1513: highlights for function pointers in argument list of
     c;function.  Thanks to Takeshi Komiya.

   * PR#278: Fix section entries were shown twice if toctree has been
     put under only directive.  Thanks to Takeshi Komiya.

   * #1547: pgen2 tokenizer doesn’t recognize ‘...’ literal (Ellipsis
     for py3).

   * PR#294: On LaTeX builder, wrap float environment on writing
     literal_block to avoid separation of caption and body.  Thanks to
     Takeshi Komiya.

   * PR#295, #1520: ‘make.bat latexpdf’ mechanism to ‘cd’ back to the
     current directory.  Thanks to Peter Suter.

   * PR#297, #1571: Add imgpath property to all builders.  It make
     easier to develop builder extensions.  Thanks to Takeshi Komiya.

   * #1584: Point to master doc in HTML “top” link.

   * #1585: Autosummary of modules broken in Sphinx-1.2.3.

   * #1610: Sphinx cause AttributeError when MeCab search option is
     enabled and python-mecab is not installed.

   * #1674: Do not crash if a module’s ‘__all__’ is not a list of
     strings.

   * #1673: Fix crashes with nitpick_ignore and ‘:doc:’
     references.

   * #1686: ifconfig directive doesn’t care about default config values.

   * #1642: Fix only one search result appearing in Chrome.

11.102.4 Documentation
----------------------

   * Add clarification about the syntax of tags.
     (‘doc/markup/misc.rst’)

11.103 Release 1.2.3 (released Sep 1, 2014)
===========================================

11.103.1 Features added
-----------------------

   * #1518: ‘sphinx-apidoc’ command now has a ‘--version’ option to show
     version information and exit

   * New locales: Hebrew, European Portuguese, Vietnamese.

11.103.2 Bugs fixed
-------------------

   * #636: Keep straight single quotes in literal blocks in the LaTeX
     build.

   * #1419: Generated i18n sphinx.js files are missing message catalog
     entries from ‘.js_t’ and ‘.html’.  The issue was introduced from
     Sphinx-1.1

   * #1363: Fix i18n: missing python domain’s cross-references with
     currentmodule directive or currentclass directive.

   * #1444: autosummary does not create the description from attributes
     docstring.

   * #1457: In python3 environment, make linkcheck cause “Can’t convert
     ‘bytes’ object to str implicitly” error when link target url has a
     hash part.  Thanks to Jorge_C.

   * #1467: Exception on Python3 if nonexistent method is specified by
     automethod

   * #1441: autosummary can’t handle nested classes correctly.

   * #1499: With non-callable ‘setup’ in a conf.py, now sphinx-build
     emits a user-friendly error message.

   * #1502: In autodoc, fix display of parameter defaults containing
     backslashes.

   * #1226: autodoc, autosummary: importing setup.py by automodule will
     invoke setup process and execute ‘sys.exit()’.  Now sphinx avoids
     SystemExit exception and emits warnings without unexpected
     termination.

   * #1503: py:function directive generate incorrectly signature when
     specifying a default parameter with an empty list ‘[]’.  Thanks to
     Geert Jansen.

   * #1508: Non-ASCII filename raise exception on make singlehtml,
     latex, man, texinfo and changes.

   * #1531: On Python3 environment, docutils.conf with
     ‘source_link=true’ in the general section cause type error.

   * PR#270, #1533: Non-ASCII docstring cause UnicodeDecodeError when
     uses with inheritance-diagram directive.  Thanks to WAKAYAMA
     shirou.

   * PR#281, PR#282, #1509: TODO extension not compatible with
     websupport.  Thanks to Takeshi Komiya.

   * #1477: gettext does not extract nodes.line in a table or list.

   * #1544: ‘make text’ generates wrong table when it has empty table
     cells.

   * #1522: Footnotes from table get displayed twice in LaTeX. This
     problem has been appeared from Sphinx-1.2.1 by #949.

   * #508: Sphinx every time exit with zero when is invoked from
     setup.py command.  ex.  ‘python setup.py build_sphinx -b doctest’
     return zero even if doctest failed.

11.104 Release 1.2.2 (released Mar 2, 2014)
===========================================

11.104.1 Bugs fixed
-------------------

   * PR#211: When checking for existence of the html_logo.
     file, check the full relative path and not the basename.

   * PR#212: Fix traceback with autodoc and ‘__init__’ methods without
     docstring.

   * PR#213: Fix a missing import in the setup command.

   * #1357: Option names documented by option are now again
     allowed to not start with a dash or slash, and referencing them
     will work correctly.

   * #1358: Fix handling of image paths outside of the source directory
     when using the “wildcard” style reference.

   * #1374: Fix for autosummary generating overly-long summaries if
     first line doesn’t end with a period.

   * #1383: Fix Python 2.5 compatibility of sphinx-apidoc.

   * #1391: Actually prevent using “pngmath” and “mathjax” extensions at
     the same time in sphinx-quickstart.

   * #1386: Fix bug preventing more than one theme being added by the
     entry point mechanism.

   * #1370: Ignore “toctree” nodes in text writer, instead of raising.

   * #1364: Fix ‘make gettext’ fails when the ‘..  todolist::’ directive
     is present.

   * #1367: Fix a change of PR#96 that break
     sphinx.util.docfields.Field.make_field interface/behavior for
     ‘item’ argument usage.

11.104.2 Documentation
----------------------

   * Extended the documentation about building extensions.

11.105 Release 1.2.1 (released Jan 19, 2014)
============================================

11.105.1 Bugs fixed
-------------------

   * #1335: Fix autosummary template overloading with exclamation prefix
     like ‘{% extends "!autosummary/class.rst" %}’ cause infinite
     recursive function call.  This was caused by PR#181.

   * #1337: Fix autodoc with ‘autoclass_content="both"’ uses useless
     ‘object.__init__’ docstring when class does not have ‘__init__’.
     This was caused by a change for #1138.

   * #1340: Can’t search alphabetical words on the HTML quick search
     generated with language=’ja’.

   * #1319: Do not crash if the html_logo file does not
     exist.

   * #603: Do not use the HTML-ized title for building the search index
     (that resulted in “literal” being found on every page with a
     literal in the title).

   * #751: Allow production lists longer than a page in LaTeX by using
     longtable.

   * #764: Always look for stopwords lowercased in JS search.

   * #814: autodoc: Guard against strange type objects that don’t have
     ‘__bases__’.

   * #932: autodoc: Do not crash if ‘__doc__’ is not a string.

   * #933: Do not crash if an option value is malformed
     (contains spaces but no option name).

   * #908: On Python 3, handle error messages from LaTeX correctly in
     the pngmath extension.

   * #943: In autosummary, recognize “first sentences” to pull from the
     docstring if they contain uppercase letters.

   * #923: Take the entire LaTeX document into account when caching
     pngmath-generated images.  This rebuilds them correctly when
     ‘pngmath_latex_preamble’ changes.

   * #901: Emit a warning when using docutils’ new “math” markup without
     a Sphinx math extension active.

   * #845: In code blocks, when the selected lexer fails, display line
     numbers nevertheless if configured.

   * #929: Support parsed-literal blocks in LaTeX output correctly.

   * #949: Update the tabulary.sty packed with Sphinx.

   * #1050: Add anonymous labels into ‘objects.inv’ to be referenced via
     intersphinx.

   * #1095: Fix print-media stylesheet being included always in the
     “scrolls” theme.

   * #1085: Fix current classname not getting set if class description
     has ‘:noindex:’ set.

   * #1181: Report option errors in autodoc directives more gracefully.

   * #1155: Fix autodocumenting C-defined methods as attributes in
     Python 3.

   * #1233: Allow finding both Python classes and exceptions with the
     “class” and “exc” roles in intersphinx.

   * #1198: Allow “image” for the “figwidth” option of the figure(1)
     directive as documented by docutils.

   * #1152: Fix pycode parsing errors of Python 3 code by including two
     grammar versions for Python 2 and 3, and loading the appropriate
     version for the running Python version.

   * #1017: Be helpful and tell the user when the argument to
     option does not match the required format.

   * #1345: Fix two bugs with nitpick_ignore.; now you don’t
     have to remove the store environment for changes to have effect.

   * #1072: In the JS search, fix issues searching for upper-cased words
     by lowercasing words before stemming.

   * #1299: Make behavior of the math directive more
     consistent and avoid producing empty environments in LaTeX output.

   * #1308: Strip HTML tags from the content of “raw” nodes before
     feeding it to the search indexer.

   * #1249: Fix duplicate LaTeX page numbering for manual documents.

   * #1292: In the linkchecker, retry HEAD requests when denied by HTTP
     405.  Also make the redirect code apparent and tweak the output a
     bit to be more obvious.

   * #1285: Avoid name clashes between C domain objects and section
     titles.

   * #848: Always take the newest code in incremental rebuilds with the
     sphinx.ext.viewcode extension.

   * #979, #1266: Fix exclude handling in ‘sphinx-apidoc’.

   * #1302: Fix regression in sphinx.ext.inheritance_diagram.
     when documenting classes that can’t be pickled.

   * #1316: Remove hard-coded ‘font-face’ resources from epub theme.

   * #1329: Fix traceback with empty translation msgstr in .po files.

   * #1300: Fix references not working in translated documents in some
     instances.

   * #1283: Fix a bug in the detection of changed files that would try
     to access doctrees of deleted documents.

   * #1330: Fix exclude_patterns behavior with subdirectories
     in the html_static_path.

   * #1323: Fix emitting empty ‘<ul>’ tags in the HTML writer, which is
     not valid HTML.

   * #1147: Don’t emit a sidebar search box in the “singlehtml” builder.

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure

11.105.2 Documentation
----------------------

   * #1325: Added a “Intersphinx” tutorial section.
     (‘doc/tutorial.rst’)

11.106 Release 1.2 (released Dec 10, 2013)
==========================================

11.106.1 Features added
-----------------------

   * Added ‘sphinx.version_info’ tuple for programmatic checking of the
     Sphinx version.

11.106.2 Incompatible changes
-----------------------------

   * Removed the ‘sphinx.ext.refcounting’ extension – it is very
     specific to CPython and has no place in the main distribution.

11.106.3 Bugs fixed
-------------------

   * Restore ‘versionmodified’ CSS class for versionadded/changed and
     deprecated directives.

   * PR#181: Fix ‘html_theme_path = ['.']’ is a trigger of rebuild all
     documents always (This change keeps the current “theme changes
     cause a rebuild” feature).

   * #1296: Fix invalid charset in HTML help generated HTML files for
     default locale.

   * PR#190: Fix gettext does not extract figure caption and rubric
     title inside other blocks.  Thanks to Michael Schlenker.

   * PR#176: Make sure setup_command test can always import Sphinx.
     Thanks to Dmitry Shachnev.

   * #1311: Fix test_linkcode.test_html fails with C locale and Python
     3.

   * #1269: Fix ResourceWarnings with Python 3.2 or later.

   * #1138: Fix: When ‘autodoc_docstring_signature = True’ and
     ‘autoclass_content = 'init'’ or ‘'both'’, __init__ line should be
     removed from class documentation.

11.107 Release 1.2 beta3 (released Oct 3, 2013)
===============================================

11.107.1 Features added
-----------------------

   * The Sphinx error log files will now include a list of the loaded
     extensions for help in debugging.

11.107.2 Incompatible changes
-----------------------------

   * PR#154: Remove “sphinx” prefix from LaTeX class name except
     ‘sphinxmanual’ and ‘sphinxhowto’.  Now you can use your custom
     document class without ‘sphinx’ prefix.  Thanks to Erik B.

11.107.3 Bugs fixed
-------------------

   * #1265: Fix i18n: crash when translating a section name that is
     pointed to from a named target.

   * A wrong condition broke the search feature on first page that is
     usually index.rst.  This issue was introduced in 1.2b1.

   * #703: When Sphinx can’t decode filenames with non-ASCII characters,
     Sphinx now catches UnicodeError and will continue if possible
     instead of raising the exception.

11.108 Release 1.2 beta2 (released Sep 17, 2013)
================================================

11.108.1 Features added
-----------------------

   * ‘apidoc’ now ignores “_private” modules by default, and has an
     option ‘-P’ to include them.

   * ‘apidoc’ now has an option to not generate headings for packages
     and modules, for the case that the module docstring already
     includes a reST heading.

   * PR#161: ‘apidoc’ can now write each module to a standalone page
     instead of combining all modules in a package on one page.

   * Builders: rebuild i18n target document when catalog updated.

   * Support docutils.conf ‘writers’ and ‘html4css1 writer’ section in
     the HTML writer.  The latex, manpage and texinfo writers also
     support their respective ‘writers’ sections.

   * The new html_extra_path config value allows to specify
     directories with files that should be copied directly to the HTML
     output directory.

   * Autodoc directives for module data and attributes now support an
     ‘annotation’ option, so that the default display of the
     data/attribute value can be overridden.

   * PR#136: Autodoc directives now support an ‘imported-members’ option
     to include members imported from different modules.

   * New locales: Macedonian, Sinhala, Indonesian.

   * Theme package collection by using setuptools plugin mechanism.

11.108.2 Incompatible changes
-----------------------------

   * PR#144, #1182: Force timezone offset to LocalTimeZone on
     POT-Creation-Date that was generated by gettext builder.  Thanks to
     masklinn and Jakub Wilk.

11.108.3 Bugs fixed
-------------------

   * PR#132: Updated jQuery version to 1.8.3.

   * PR#141, #982: Avoid crash when writing PNG file using Python 3.
     Thanks to Marcin Wojdyr.

   * PR#145: In parallel builds, sphinx drops second document file to
     write.  Thanks to tychoish.

   * PR#151: Some styling updates to tables in LaTeX.

   * PR#153: The “extensions” config value can now be overridden.

   * PR#155: Added support for some C++11 function qualifiers.

   * Fix: ‘make gettext’ caused UnicodeDecodeError when templates
     contain utf-8 encoded strings.

   * #828: use inspect.getfullargspec() to be able to document functions
     with keyword-only arguments on Python 3.

   * #1090: Fix i18n: multiple cross references (term, ref, doc) in the
     same line return the same link.

   * #1157: Combination of ‘globaltoc.html’ and hidden toctree caused
     exception.

   * #1159: fix wrong generation of objects inventory for Python
     modules, and add a workaround in intersphinx to fix handling of
     affected inventories.

   * #1160: Citation target missing caused an AssertionError.

   * #1162, PR#139: singlehtml builder didn’t copy images to _images/.

   * #1173: Adjust setup.py dependencies because Jinja2 2.7 discontinued
     compatibility with Python < 3.3 and Python < 2.6.  Thanks to
     Alexander Dupuy.

   * #1185: Don’t crash when a Python module has a wrong or no encoding
     declared, and non-ASCII characters are included.

   * #1188: sphinx-quickstart raises UnicodeEncodeError if “Project
     version” includes non-ASCII characters.

   * #1189: “Title underline is too short” WARNING is given when using
     fullwidth characters to “Project name” on quickstart.

   * #1190: Output TeX/texinfo/man filename has no basename (only
     extension) when using non-ASCII characters in the “Project name” on
     quickstart.

   * #1192: Fix escaping problem for hyperlinks in the manpage writer.

   * #1193: Fix i18n: multiple link references in the same line return
     the same link.

   * #1176: Fix i18n: footnote reference number missing for auto
     numbered named footnote and auto symbol footnote.

   * PR#146,#1172: Fix ZeroDivisionError in parallel builds.  Thanks to
     tychoish.

   * #1204: Fix wrong generation of links to local intersphinx targets.

   * #1206: Fix i18n: gettext did not translate admonition directive’s
     title.

   * #1232: Sphinx generated broken ePub files on Windows.

   * #1259: Guard the debug output call when emitting events; to prevent
     the repr() implementation of arbitrary objects causing build
     failures.

   * #1142: Fix NFC/NFD normalizing problem of rst filename on Mac OS X.

   * #1234: Ignoring the string consists only of white-space characters.

11.109 Release 1.2 beta1 (released Mar 31, 2013)
================================================

11.109.1 Incompatible changes
-----------------------------

   * Removed ‘sphinx.util.compat.directive_dwim()’ and
     ‘sphinx.roles.xfileref_role()’ which were deprecated since version
     1.0.

   * PR#122: the files given in latex_additional_files now
     override TeX files included by Sphinx, such as ‘sphinx.sty’.

   * PR#124: the node generated by versionadded,
     versionchanged and deprecated directives now
     includes all added markup (such as “New in version X”) as child
     nodes, and no additional text must be generated by writers.

   * PR#99: the seealso directive now generates admonition
     nodes instead of the custom ‘seealso’ node.

11.109.2 Features added
-----------------------

   * Markup

        - The toctree directive and the ‘toctree()’ template
          function now have an ‘includehidden’ option that includes
          hidden toctree entries (bugs #790 and #1047).  A bug in the
          ‘maxdepth’ option for the ‘toctree()’ template function has
          been fixed (bug #1046).

        - PR#99: Strip down seealso directives to normal admonitions.
          This removes their unusual CSS classes (admonition-see-also),
          inconsistent LaTeX admonition title (“See Also” instead of
          “See also”), and spurious indentation in the text builder.

   * HTML builder

        - #783: Create a link to full size image if it is scaled with
          width or height.

        - #1067: Improve the ordering of the JavaScript search results:
          matches in titles come before matches in full text, and object
          results are better categorized.  Also implement a pluggable
          search scorer.

        - #1053: The “rightsidebar” and “collapsiblesidebar” HTML theme
          options now work together.

        - Update to jQuery 1.7.1 and Underscore.js 1.3.1.

   * Texinfo builder

        - An “Index” node is no longer added when there are no entries.

        - “deffn” categories are no longer capitalized if they contain
          capital letters.

        - ‘desc_annotation’ nodes are now rendered.

        - ‘strong’ and ‘emphasis’ nodes are now formatted like
          ‘literal’s.  The reason for this is because the standard
          Texinfo markup (‘*strong*’ and ‘_emphasis_’) resulted in
          confusing output due to the common usage of using these
          constructs for documenting parameter names.

        - Field lists formatting has been tweaked to better display
          “Info field lists”.

        - ‘system_message’ and ‘problematic’ nodes are now formatted in
          a similar fashion as done by the text builder.

        - “en-dash” and “em-dash” conversion of hyphens is no longer
          performed in option directive signatures.

        - ‘@ref’ is now used instead of ‘@pxref’ for cross-references
          which prevents the word “see” from being added before the link
          (does not affect the Info output).

        - The ‘@finalout’ command has been added for better TeX output.

        - ‘transition’ nodes are now formatted using underscores (“_”)
          instead of asterisks (“*”).

        - The default value for the ‘paragraphindent’ has been changed
          from 2 to 0 meaning that paragraphs are no longer indented by
          default.

        - #1110: A new configuration value texinfo_no_detailmenu
          has been added for controlling whether a ‘@detailmenu’ is
          added in the “Top” node’s menu.

        - Detailed menus are no longer created except for the “Top”
          node.

        - Fixed an issue where duplicate domain indices would result in
          invalid output.

   * LaTeX builder:

        - PR#115: Add ‘'transition'’ item in latex_elements.
          for customizing how transitions are displayed.  Thanks to Jeff
          Klukas.

        - PR#114: The LaTeX writer now includes the “cmap” package by
          default.  The ‘'cmappkg'’ item in latex_elements.
          can be used to control this.  Thanks to Dmitry Shachnev.

        - The ‘'fontpkg'’ item in latex_elements now
          defaults to ‘''’ when the language uses the
          Cyrillic script.  Suggested by Dmitry Shachnev.

        - The latex_documents, texinfo_documents,
          and man_pages configuration values will be set to
          default values based on the master_doc if not
          explicitly set in ‘conf.py’.  Previously, if these values were
          not set, no output would be generated by their respective
          builders.

   * Internationalization:

        - Add i18n capabilities for custom templates.  For example: The
          Sphinx reference documentation in doc directory provides a
          ‘sphinx.pot’ file with message strings from
          ‘doc/_templates/*.html’ when using ‘make gettext’.

        - PR#61,#703: Add support for non-ASCII filename handling.

   * Other builders:

        - Added the Docutils-native XML and pseudo-XML builders.  See
          ‘XMLBuilder’ and ‘PseudoXMLBuilder’.

        - PR#45: The linkcheck builder now checks ‘#anchor’s for
          existence.

        - PR#123, #1106: Add epub_use_index configuration
          value.  If provided, it will be used instead of
          html_use_index for epub builder.

        - PR#126: Add epub_tocscope configuration value.
          The setting controls the generation of the epub toc.  The user
          can now also include hidden toc entries.

        - PR#112: Add epub_show_urls configuration value.

   * Extensions:

        - PR#52: ‘special_members’ flag to autodoc now behaves like
          ‘members’.

        - PR#47: Added sphinx.ext.linkcode extension.

        - PR#25: In inheritance diagrams, the first line of the class
          docstring is now the tooltip for the class.

   * Command-line interfaces:

        - PR#75: Added ‘--follow-links’ option to sphinx-apidoc.

        - #869: sphinx-build now has the option ‘-T’ for printing the
          full traceback after an unhandled exception.

        - sphinx-build now supports the standard ‘--help’ and
          ‘--version’ options.

        - sphinx-build now provides more specific error messages when
          called with invalid options or arguments.

        - sphinx-build now has a verbose option ‘-v’ which can be
          repeated for greater effect.  A single occurrence provides a
          slightly more verbose output than normal.  Two or more
          occurrences of this option provides more detailed output which
          may be useful for debugging.

   * Locales:

        - PR#74: Fix some Russian translation.

        - PR#54: Added Norwegian bokmaal translation.

        - PR#35: Added Slovak translation.

        - PR#28: Added Hungarian translation.

        - #1113: Add Hebrew locale.

        - #1097: Add Basque locale.

        - #1037: Fix typos in Polish translation.  Thanks to Jakub Wilk.

        - #1012: Update Estonian translation.

   * Optimizations:

        - Speed up building the search index by caching the results of
          the word stemming routines.  Saves about 20 seconds when
          building the Python documentation.

        - PR#108: Add experimental support for parallel building with a
          new sphinx-build -j option.

11.109.3 Documentation
----------------------

   * PR#88: Added the “Sphinx Developer’s Guide” (‘doc/devguide.rst’)
     which outlines the basic development process of the Sphinx project.

   * Added a detailed “Installing Sphinx” document (‘doc/install.rst’).

11.109.4 Bugs fixed
-------------------

   * PR#124: Fix paragraphs in versionmodified are ignored when it has
     no dangling paragraphs.  Fix wrong html output (nested ‘<p>’ tag).
     Fix versionmodified is not translatable.  Thanks to Nozomu Kaneko.

   * PR#111: Respect add_autodoc_attrgetter() even when
     inherited-members is set.  Thanks to A. Jesse Jiryu Davis.

   * PR#97: Fix footnote handling in translated documents.

   * Fix text writer not handling visit_legend for figure directive
     contents.

   * Fix text builder not respecting wide/fullwidth characters: title
     underline width, table layout width and text wrap width.

   * Fix leading space in LaTeX table header cells.

   * #1132: Fix LaTeX table output for multi-row cells in the first
     column.

   * #1128: Fix Unicode errors when trying to format time strings with a
     non-standard locale.

   * #1127: Fix traceback when autodoc tries to tokenize a non-Python
     file.

   * #1126: Fix double-hyphen to en-dash conversion in wrong places such
     as command-line option names in LaTeX.

   * #1123: Allow whitespaces in filenames given to
     literalinclude.

   * #1120: Added improvements about i18n for themes “basic”, “haiku”
     and “scrolls” that Sphinx built-in.  Thanks to Leonardo J.
     Caballero G.

   * #1118: Updated Spanish translation.  Thanks to Leonardo J.
     Caballero G.

   * #1117: Handle .pyx files in sphinx-apidoc.

   * #1112: Avoid duplicate download files when referenced from
     documents in different ways (absolute/relative).

   * #1111: Fix failure to find uppercase words in search when
     html_search_language is ‘ja’.  Thanks to Tomo Saito.

   * #1108: The text writer now correctly numbers enumerated lists with
     non-default start values (based on patch by Ewan Edwards).

   * #1102: Support multi-context “with” statements in autodoc.

   * #1090: Fix gettext not extracting glossary terms.

   * #1074: Add environment version info to the generated search index
     to avoid compatibility issues with old builds.

   * #1070: Avoid un-pickling issues when running Python 3 and the saved
     environment was created under Python 2.

   * #1069: Fixed error caused when autodoc would try to format
     signatures of “partial” functions without keyword arguments (patch
     by Artur Gaspar).

   * #1062: sphinx.ext.autodoc use __init__ method signature for class
     signature.

   * #1055: Fix web support with relative path to source directory.

   * #1043: Fix sphinx-quickstart asking again for yes/no questions
     because ‘input()’ returns values with an extra ‘r’ on Python 3.2.0
     + Windows.  Thanks to Régis Décamps.

   * #1041: Fix failure of the cpp domain parser to parse a const type
     with a modifier.

   * #1038: Fix failure of the cpp domain parser to parse C+11 “static
     constexpr” declarations.  Thanks to Jakub Wilk.

   * #1029: Fix intersphinx_mapping values not being stable if the
     mapping has plural key/value set with Python 3.3.

   * #1028: Fix line block output in the text builder.

   * #1024: Improve Makefile/make.bat error message if Sphinx is not
     found.  Thanks to Anatoly Techtonik.

   * #1018: Fix “container” directive handling in the text builder.

   * #1015: Stop overriding jQuery contains() in the JavaScript.

   * #1010: Make pngmath images transparent by default; IE7+ should
     handle it.

   * #1008: Fix test failures with Python 3.3.

   * #995: Fix table-of-contents and page numbering for the LaTeX
     “howto” class.

   * #976: Fix gettext does not extract index entries.

   * PR#72: #975: Fix gettext not extracting definition terms before
     docutils 0.10.

   * #961: Fix LaTeX output for triple quotes in code snippets.

   * #958: Do not preserve ‘environment.pickle’ after a failed build.

   * #955: Fix i18n transformation.

   * #940: Fix gettext does not extract figure caption.

   * #920: Fix PIL packaging issue that allowed to import ‘Image’
     without PIL namespace.  Thanks to Marc Schlaich.

   * #723: Fix the search function on local files in WebKit based
     browsers.

   * #440: Fix coarse timestamp resolution in some filesystem generating
     a wrong list of outdated files.

11.110 Release 1.1.3 (Mar 10, 2012)
===================================

   * PR#40: Fix ‘safe_repr’ function to decode bytestrings with
     non-ASCII characters correctly.

   * PR#37: Allow configuring sphinx-apidoc via ‘SPHINX_APIDOC_OPTIONS’.

   * PR#34: Restore Python 2.4 compatibility.

   * PR#36: Make the “bibliography to TOC” fix in LaTeX output specific
     to the document class.

   * #695: When the highlight language “python” is specified explicitly,
     do not try to parse the code to recognize non-Python snippets.

   * #859: Fix exception under certain circumstances when not finding
     appropriate objects to link to.

   * #860: Do not crash when encountering invalid doctest examples, just
     emit a warning.

   * #864: Fix crash with some settings of modindex_common_prefix.

   * #862: Fix handling of ‘-D’ and ‘-A’ options on Python 3.

   * #851: Recognize and warn about circular toctrees, instead of
     running into recursion errors.

   * #853: Restore compatibility with docutils trunk.

   * #852: Fix HtmlHelp index entry links again.

   * #854: Fix inheritance_diagram raising attribute errors on builtins.

   * #832: Fix crashes when putting comments or lone terms in a
     glossary.

   * #834, #818: Fix HTML help language/encoding mapping for all Sphinx
     supported languages.

   * #844: Fix crashes when dealing with Unicode output in doctest
     extension.

   * #831: Provide ‘--project’ flag in setup_command as advertised.

   * #875: Fix reading config files under Python 3.

   * #876: Fix quickstart test under Python 3.

   * #870: Fix spurious KeyErrors when removing documents.

   * #892: Fix single-HTML builder misbehaving with the master document
     in a subdirectory.

   * #873: Fix assertion errors with empty ‘only’ directives.

   * #816: Fix encoding issues in the Qt help builder.

11.111 Release 1.1.2 (Nov 1, 2011) – 1.1.1 is a silly version number anyway!
============================================================================

   * #809: Include custom fixers in the source distribution.

11.112 Release 1.1.1 (Nov 1, 2011)
==================================

   * #791: Fix QtHelp, DevHelp and HtmlHelp index entry links.

   * #792: Include “sphinx-apidoc” in the source distribution.

   * #797: Don’t crash on a misformatted glossary.

   * #801: Make intersphinx work properly without SSL support.

   * #805: Make the ‘Sphinx.add_index_to_domain’ method work correctly.

   * #780: Fix Python 2.5 compatibility.

11.113 Release 1.1 (Oct 9, 2011)
================================

11.113.1 Incompatible changes
-----------------------------

   * The py;module directive doesn’t output its ‘platform’
     option value anymore.  (It was the only thing that the directive
     did output, and therefore quite inconsistent.)

   * Removed support for old dependency versions; requirements are now:

        - Pygments >= 1.2

        - Docutils >= 0.7

        - Jinja2 >= 2.3

11.113.2 Features added
-----------------------

   * Added Python 3.x support.

   * New builders and subsystems:

        - Added a Texinfo builder.

        - Added i18n support for content, a ‘gettext’ builder and
          related utilities.

        - Added the ‘websupport’ library and builder.

        - #98: Added a ‘sphinx-apidoc’ script that autogenerates a
          hierarchy of source files containing autodoc directives to
          document modules and packages.

        - #273: Add an API for adding full-text search support for
          languages other than English.  Add support for Japanese.

   * Markup:

        - #138: Added an index role, to make inline index
          entries.

        - #454: Added more index markup capabilities: marking
          see/seealso entries, and main entries for a given key.

        - #460: Allowed limiting the depth of section numbers for HTML
          using the toctree.’s ‘numbered’ option.

        - #586: Implemented improved glossary markup which
          allows multiple terms per definition.

        - #478: Added py;decorator directive to describe
          decorators.

        - C++ domain now supports array definitions.

        - C++ domain now supports doc fields (‘:param x:’ inside
          directives).

        - Section headings in only directives are now
          correctly handled.

        - Added ‘emphasize-lines’ option to source code directives.

        - #678: C++ domain now supports superclasses.

   * HTML builder:

        - Added ‘pyramid’ theme.

        - #559: html_add_permalinks is now a string giving
          the text to display in permalinks.

        - #259: HTML table rows now have even/odd CSS classes to enable
          “Zebra styling”.

        - #554: Add theme option ‘sidebarwidth’ to the basic theme.

   * Other builders:

        - #516: Added new value of the latex_show_urls.
          option to show the URLs in footnotes.

        - #209: Added text_newlines and
          text_sectionchars config values.

        - Added man_show_urls config value.

        - #472: linkcheck builder: Check links in parallel, use HTTP
          HEAD requests and allow configuring the timeout.  New config
          values: linkcheck_timeout and
          linkcheck_workers.

        - #521: Added linkcheck_ignore config value.

        - #28: Support row/colspans in tables in the LaTeX builder.

   * Configuration and extensibility:

        - #537: Added nitpick_ignore.

        - #306: Added env-get-outdated event.

        - ‘Application.add_stylesheet()’ now accepts full URIs.

   * Autodoc:

        - #564: Add autodoc_docstring_signature.  When
          enabled (the default), autodoc retrieves the signature from
          the first line of the docstring, if it is found there.

        - #176: Provide ‘private-members’ option for autodoc directives.

        - #520: Provide ‘special-members’ option for autodoc directives.

        - #431: Doc comments for attributes can now be given on the same
          line as the assignment.

        - #437: autodoc now shows values of class data attributes.

        - autodoc now supports documenting the signatures of
          ‘functools.partial’ objects.

   * Other extensions:

        - Added the sphinx.ext.mathjax extension.

        - #443: Allow referencing external graphviz files.

        - Added ‘inline’ option to graphviz directives, and fixed the
          default (block-style) in LaTeX output.

        - #590: Added ‘caption’ option to graphviz directives.

        - #553: Added testcleanup blocks in the doctest
          extension.

        - #594: trim_doctest_flags now also removes
          ‘<BLANKLINE>’ indicators.

        - #367: Added automatic exclusion of hidden members in
          inheritance diagrams, and an option to selectively enable it.

        - Added ‘pngmath_add_tooltips’.

        - The math extension displaymath directives now support ‘name’
          in addition to ‘label’ for giving the equation label, for
          compatibility with Docutils.

   * New locales:

        - #221: Added Swedish locale.

        - #526: Added Iranian locale.

        - #694: Added Latvian locale.

        - Added Nepali locale.

        - #714: Added Korean locale.

        - #766: Added Estonian locale.

   * Bugs fixed:

        - #778: Fix “hide search matches” link on pages linked by
          search.

        - Fix the source positions referenced by the “viewcode”
          extension.

11.114 Release 1.0.8 (Sep 23, 2011)
===================================

   * #627: Fix tracebacks for AttributeErrors in autosummary generation.

   * Fix the ‘abbr’ role when the abbreviation has newlines in it.

   * #727: Fix the links to search results with custom object types.

   * #648: Fix line numbers reported in warnings about undefined
     references.

   * #696, #666: Fix C++ array definitions and template arguments that
     are not type names.

   * #633: Allow footnotes in section headers in LaTeX output.

   * #616: Allow keywords to be linked via intersphinx.

   * #613: Allow Unicode characters in production list token names.

   * #720: Add dummy visitors for graphviz nodes for text and man.

   * #704: Fix image file duplication bug.

   * #677: Fix parsing of multiple signatures in C++ domain.

   * #637: Ignore Emacs lock files when looking for source files.

   * #544: Allow .pyw extension for importable modules in autodoc.

   * #700: Use ‘$(MAKE)’ in quickstart-generated Makefiles.

   * #734: Make sidebar search box width consistent in browsers.

   * #644: Fix spacing of centered figures in HTML output.

   * #767: Safely encode SphinxError messages when printing them to
     sys.stderr.

   * #611: Fix LaTeX output error with a document with no sections but a
     link target.

   * Correctly treat built-in method descriptors as methods in autodoc.

   * #706: Stop monkeypatching the Python textwrap module.

   * #657: viewcode now works correctly with source files that have
     non-ASCII encoding.

   * #669: Respect the ‘noindex’ flag option in py:module directives.

   * #675: Fix IndexErrors when including nonexisting lines with
     literalinclude.

   * #676: Respect custom function/method parameter separator strings.

   * #682: Fix JS incompatibility with jQuery >= 1.5.

   * #693: Fix double encoding done when writing HTMLHelp .hhk files.

   * #647: Do not apply SmartyPants in parsed-literal blocks.

   * C++ domain now supports array definitions.

11.115 Release 1.0.7 (Jan 15, 2011)
===================================

   * #347: Fix wrong generation of directives of static methods in
     autosummary.

   * #599: Import PIL as ‘from PIL import Image’.

   * #558: Fix longtables with captions in LaTeX output.

   * Make token references work as hyperlinks again in LaTeX output.

   * #572: Show warnings by default when reference labels cannot be
     found.

   * #536: Include line number when complaining about missing reference
     targets in nitpicky mode.

   * #590: Fix inline display of graphviz diagrams in LaTeX output.

   * #589: Build using app.build() in setup command.

   * Fix a bug in the inheritance diagram exception that caused base
     classes to be skipped if one of them is a builtin.

   * Fix general index links for C++ domain objects.

   * #332: Make admonition boundaries in LaTeX output visible.

   * #573: Fix KeyErrors occurring on rebuild after removing a file.

   * Fix a traceback when removing files with globbed toctrees.

   * If an autodoc object cannot be imported, always re-read the
     document containing the directive on next build.

   * If an autodoc object cannot be imported, show the full traceback of
     the import error.

   * Fix a bug where the removal of download files and images wasn’t
     noticed.

   * #571: Implement ‘~’ cross-reference prefix for the C domain.

   * Fix regression of LaTeX output with the fix of #556.

   * #568: Fix lookup of class attribute documentation on descriptors so
     that comment documentation now works.

   * Fix traceback with ‘only’ directives preceded by targets.

   * Fix tracebacks occurring for duplicate C++ domain objects.

   * Fix JavaScript domain links to objects with ‘$’ in their name.

11.116 Release 1.0.6 (Jan 04, 2011)
===================================

   * #581: Fix traceback in Python domain for empty cross-reference
     targets.

   * #283: Fix literal block display issues on Chrome browsers.

   * #383, #148: Support sorting a limited range of accented characters
     in the general index and the glossary.

   * #570: Try decoding ‘-D’ and ‘-A’ command-line arguments with the
     locale’s preferred encoding.

   * #528: Observe locale_dirs when looking for the JS
     translations file.

   * #574: Add special code for better support of Japanese documents in
     the LaTeX builder.

   * Regression of #77: If there is only one parameter given with
     ‘:param:’ markup, the bullet list is now suppressed again.

   * #556: Fix missing paragraph breaks in LaTeX output in certain
     situations.

   * #567: Emit the ‘autodoc-process-docstring’ event even for objects
     without a docstring so that it can add content.

   * #565: In the LaTeX builder, not only literal blocks require
     different table handling, but also quite a few other list-like
     block elements.

   * #515: Fix tracebacks in the viewcode extension for Python objects
     that do not have a valid signature.

   * Fix strange reports of line numbers for warnings generated from
     autodoc-included docstrings, due to different behavior depending on
     docutils version.

   * Several fixes to the C++ domain.

11.117 Release 1.0.5 (Nov 12, 2010)
===================================

   * #557: Add CSS styles required by docutils 0.7 for aligned images
     and figures.

   * In the Makefile generated by LaTeX output, do not delete pdf files
     on clean; they might be required images.

   * #535: Fix LaTeX output generated for line blocks.

   * #544: Allow ‘.pyw’ as a source file extension.

11.118 Release 1.0.4 (Sep 17, 2010)
===================================

   * #524: Open intersphinx inventories in binary mode on Windows, since
     version 2 contains zlib-compressed data.

   * #513: Allow giving non-local URIs for JavaScript files, e.g.  in
     the JSMath extension.

   * #512: Fix traceback when ‘intersphinx_mapping’ is empty.

11.119 Release 1.0.3 (Aug 23, 2010)
===================================

   * #495: Fix internal vs.  external link distinction for links coming
     from a docutils table-of-contents.

   * #494: Fix the ‘maxdepth’ option for the ‘toctree()’ template
     callable when used with ‘collapse=True’.

   * #507: Fix crash parsing Python argument lists containing brackets
     in string literals.

   * #501: Fix regression when building LaTeX docs with figures that
     don’t have captions.

   * #510: Fix inheritance diagrams for classes that are not picklable.

   * #497: Introduce separate background color for the sidebar collapse
     button, making it easier to see.

   * #502, #503, #496: Fix small layout bugs in several builtin themes.

11.120 Release 1.0.2 (Aug 14, 2010)
===================================

   * #490: Fix cross-references to objects of types added by the
     ‘add_object_type()’ API function.

   * Fix handling of doc field types for different directive types.

   * Allow breaking long signatures, continuing with backlash-escaped
     newlines.

   * Fix unwanted styling of C domain references (because of a namespace
     clash with Pygments styles).

   * Allow references to PEPs and RFCs with explicit anchors.

   * #471: Fix LaTeX references to figures.

   * #482: When doing a non-exact search, match only the given type of
     object.

   * #481: Apply non-exact search for Python reference targets with
     ‘.name’ for modules too.

   * #484: Fix crash when duplicating a parameter in an info field list.

   * #487: Fix setting the default role to one provided by the
     ‘oldcmarkup’ extension.

   * #488: Fix crash when json-py is installed, which provides a ‘json’
     module but is incompatible to simplejson.

   * #480: Fix handling of target naming in intersphinx.

   * #486: Fix removal of ‘!’ for all cross-reference roles.

11.121 Release 1.0.1 (Jul 27, 2010)
===================================

   * #470: Fix generated target names for reST domain objects; they are
     not in the same namespace.

   * #266: Add Bengali language.

   * #473: Fix a bug in parsing JavaScript object names.

   * #474: Fix building with SingleHTMLBuilder when there is no toctree.

   * Fix display names for objects linked to by intersphinx with
     explicit targets.

   * Fix building with the JSON builder.

   * Fix hyperrefs in object descriptions for LaTeX.

11.122 Release 1.0 (Jul 23, 2010)
=================================

11.122.1 Incompatible changes
-----------------------------

   * Support for domains has been added.  A domain is a collection of
     directives and roles that all describe objects belonging together,
     e.g.  elements of a programming language.  A few builtin domains
     are provided:

        - Python

        - C

        - C++

        - JavaScript

        - reStructuredText

   * The old markup for defining and linking to C directives is now
     deprecated.  It will not work anymore in future versions without
     activating the ‘oldcmarkup’ extension; in Sphinx 1.0, it is
     activated by default.

   * Removed support for old dependency versions; requirements are now:

        - docutils >= 0.5

        - Jinja2 >= 2.2

   * Removed deprecated elements:

        - ‘exclude_dirs’ config value

        - ‘sphinx.builder’ module

11.122.2 Features added
-----------------------

   * General:

        - Added a “nitpicky” mode that emits warnings for all missing
          references.  It is activated by the sphinx-build -n
          command-line switch or the nitpicky config
          value.

        - Added ‘latexpdf’ target in quickstart Makefile.

   * Markup:

        - The menuselection and guilabel roles now
          support ampersand accelerators.

        - New more compact doc field syntax is now recognized: ‘:param
          type name: description’.

        - Added ‘tab-width’ option to literalinclude.
          directive.

        - Added ‘titlesonly’ option to toctree directive.

        - Added the ‘prepend’ and ‘append’ options to the
          literalinclude directive.

        - #284: All docinfo metadata is now put into the document
          metadata, not just the author.

        - The ref role can now also reference tables by
          caption.

        - The include(1) directive now supports absolute paths, which
          are interpreted as relative to the source directory.

        - In the Python domain, references like ‘:func:`.name`’ now look
          for matching names with any prefix if no direct match is
          found.

   * Configuration:

        - Added rst_prolog config value.

        - Added html_secnumber_suffix config value to
          control section numbering format.

        - Added html_compact_lists config value to control
          docutils’ compact lists feature.

        - The html_sidebars config value can now contain
          patterns as keys, and the values can be lists that explicitly
          select which sidebar templates should be rendered.  That means
          that the builtin sidebar contents can be included only
          selectively.

        - html_static_path can now contain single file
          entries.

        - The new universal config value exclude_patterns.
          makes the old ‘unused_docs’, ‘exclude_trees’ and
          ‘exclude_dirnames’ obsolete.

        - Added html_output_encoding config value.

        - Added the latex_docclass config value and made the
          “twoside” documentclass option overridable by “oneside”.

        - Added the trim_doctest_flags config value, which
          is true by default.

        - Added html_show_copyright config value.

        - Added latex_show_pagerefs and
          latex_show_urls config values.

        - The behavior of html_file_suffix changed slightly:
          the empty string now means “no suffix” instead of “default
          suffix”, use ‘None’ for “default suffix”.

   * New builders:

        - Added a builder for the Epub format.

        - Added a builder for manual pages.

        - Added a single-file HTML builder.

   * HTML output:

        - Inline roles now get a CSS class with their name, allowing
          styles to customize their appearance.  Domain-specific roles
          get two classes, ‘domain’ and ‘domain-rolename’.

        - References now get the class ‘internal’ if they are internal
          to the whole project, as opposed to internal to the current
          page.

        - External references can be styled differently with the new
          ‘externalrefs’ theme option for the default theme.

        - In the default theme, the sidebar can experimentally now be
          made collapsible using the new ‘collapsiblesidebar’ theme
          option.

        - #129: Toctrees are now wrapped in a ‘div’ tag with class
          ‘toctree-wrapper’ in HTML output.

        - The toctree callable in templates now has a
          ‘maxdepth’ keyword argument to control the depth of the
          generated tree.

        - The toctree callable in templates now accepts a
          ‘titles_only’ keyword argument.

        - Added ‘htmltitle’ block in layout template.

        - In the JavaScript search, allow searching for object names
          including the module name, like ‘sys.argv’.

        - Added new theme ‘haiku’, inspired by the Haiku OS user guide.

        - Added new theme ‘nature’.

        - Added new theme ‘agogo’, created by Andi Albrecht.

        - Added new theme ‘scrolls’, created by Armin Ronacher.

        - #193: Added a ‘visitedlinkcolor’ theme option to the default
          theme.

        - #322: Improved responsiveness of the search page by loading
          the search index asynchronously.

   * Extension API:

        - Added html-collect-pages.

        - Added needs_sphinx config value and
          require_sphinx() application API method.

        - #200: Added ‘add_stylesheet()’ application API method.

   * Extensions:

        - Added the viewcode extension.

        - Added the extlinks extension.

        - Added support for source ordering of members in autodoc, with
          ‘autodoc_member_order = 'bysource'’.

        - Added autodoc_default_flags config value, which
          can be used to select default flags for all autodoc
          directives.

        - Added a way for intersphinx to refer to named labels in other
          projects, and to specify the project you want to link to.

        - #280: Autodoc can now document instance attributes assigned in
          ‘__init__’ methods.

        - Many improvements and fixes to the autosummary.
          extension, thanks to Pauli Virtanen.

        - #309: The graphviz extension can now output SVG
          instead of PNG images, controlled by the
          graphviz_output_format config value.

        - Added ‘alt’ option to graphviz extension
          directives.

        - Added ‘exclude’ argument to autodoc.between().

   * Translations:

        - Added Croatian translation, thanks to Bojan Mihelač.

        - Added Turkish translation, thanks to Firat Ozgul.

        - Added Catalan translation, thanks to Pau Fernández.

        - Added simplified Chinese translation.

        - Added Danish translation, thanks to Hjorth Larsen.

        - Added Lithuanian translation, thanks to Dalius Dobravolskas.

   * Bugs fixed:

        - #445: Fix links to result pages when using the search function
          of HTML built with the ‘dirhtml’ builder.

        - #444: In templates, properly re-escape values treated with the
          “striptags” Jinja filter.

   ---------- Footnotes ----------

   (1)
https://docutils.sourceforge.io/docs/ref/rst/directives.html#include

11.123 Previous versions
========================

The changelog for versions before 1.0 can be found in the file
‘CHANGES.old’ in the source distribution or at GitHub(1).

   ---------- Footnotes ----------

   (1) https://github.com/sphinx-doc/sphinx/raw/master/CHANGES.old

12 Projects using Sphinx
************************

This is an (incomplete) alphabetic list of projects that use Sphinx or
are experimenting with using it for their documentation.  If you like to
be included, please mail to the Google group(1).

I’ve grouped the list into sections to make it easier to find
interesting examples.

   ---------- Footnotes ----------

   (1) https://groups.google.com/forum/#!forum/sphinx-users

12.1 Documentation using the alabaster theme
============================================

   * Alabaster(1)

   * Blinker(2)

   * Calibre(3)

   * Click(4) (customized)

   * coala(5) (customized)

   * CodePy(6)

   * Eve(7) (Python REST API framework)

   * Fabric(8)

   * Fityk(9)

   * Flask(10)

   * Flask-OpenID(11)

   * Invoke(12)

   * Jinja(13)

   * Lino(14) (customized)

   * marbl(15)

   * MDAnalysis(16) (customized)

   * MeshPy(17)

   * Molecule(18)

   * PyCUDA(19)

   * PyOpenCL(20)

   * PyLangAcq(21)

   * pytest(22) (customized)

   * python-apt(23)

   * PyVisfile(24)

   * Requests(25)

   * searx(26)

   * Spyder(27) (customized)

   * Tablib(28)

   * urllib3(29) (customized)

   * Werkzeug(30)

   * Write the Docs(31)

   ---------- Footnotes ----------

   (1) https://alabaster.readthedocs.io/

   (2) https://pythonhosted.org/blinker/

   (3) https://manual.calibre-ebook.com/

   (4) https://click.palletsprojects.com/

   (5) https://docs.coala.io/

   (6) https://documen.tician.de/codepy/

   (7) https://docs.python-eve.org/

   (8) https://docs.fabfile.org/

   (9) https://fityk.nieto.pl/

   (10) https://flask.palletsprojects.com/

   (11) https://pythonhosted.org/Flask-OpenID/

   (12) https://docs.pyinvoke.org/

   (13) https://jinja.palletsprojects.com/

   (14) https://www.lino-framework.org/

   (15) https://getmarbl.readthedocs.io/

   (16) https://www.mdanalysis.org/docs/

   (17) https://documen.tician.de/meshpy/

   (18) https://molecule.readthedocs.io/

   (19) https://documen.tician.de/pycuda/

   (20) https://documen.tician.de/pyopencl/

   (21) https://pylangacq.org/

   (22) https://docs.pytest.org/

   (23) https://apt.alioth.debian.org/python-apt-doc/

   (24) https://documen.tician.de/pyvisfile/

   (25) http://www.python-requests.org/

   (26) https://asciimoo.github.io/searx/

   (27) https://docs.spyder-ide.org/

   (28) http://docs.python-tablib.org/

   (29) https://urllib3.readthedocs.io/

   (30) https://werkzeug.palletsprojects.com/

   (31) https://writethedocs-www.readthedocs.io/

12.2 Documentation using the classic theme
==========================================

   * Advanced Generic Widgets(1) (customized)

   * Apache CouchDB(2) (customized)

   * APSW(3)

   * Arb(4)

   * Bazaar(5) (customized)

   * Beautiful Soup(6)

   * Blender API(7)

   * Bugzilla(8)

   * Buildbot(9)

   * CMake(10) (customized)

   * Chaco(11) (customized)

   * CORE(12)

   * CORE Python modules(13)

   * Cormoran(14)

   * DEAP(15) (customized)

   * Director(16)

   * EZ-Draw(17) (customized)

   * F2py(18)

   * Generic Mapping Tools (GMT)(19) (customized)

   * Genomedata(20)

   * GetFEM++(21) (customized)

   * Glasgow Haskell Compiler(22) (customized)

   * Grok(23) (customized)

   * GROMACS(24)

   * GSL Shell(25)

   * Hands-on Python Tutorial(26)

   * Kaa(27) (customized)

   * Leo(28)

   * LEPL(29) (customized)

   * Mayavi(30) (customized)

   * MediaGoblin(31) (customized)

   * mpmath(32)

   * OpenCV(33) (customized)

   * OpenEXR(34)

   * OpenGDA(35)

   * Peach^3(36) (customized)

   * Plone(37) (customized)

   * PyEMD(38)

   * Pyevolve(39)

   * Pygame(40) (customized)

   * PyMQI(41)

   * PyQt4(42) (customized)

   * PyQt5(43) (customized)

   * Python 2(44)

   * Python 3(45) (customized)

   * Python Packaging Authority(46) (customized)

   * Ring programming language(47) (customized)

   * SageMath(48) (customized)

   * Segway(49)

   * simuPOP(50) (customized)

   * Sprox(51) (customized)

   * SymPy(52)

   * TurboGears(53) (customized)

   * tvtk(54)

   * Varnish(55) (customized, alabaster for index)

   * Waf(56)

   * wxPython Phoenix(57) (customized)

   * Yum(58)

   * z3c(59)

   * zc.async(60) (customized)

   * Zope(61) (customized)

   ---------- Footnotes ----------

   (1) https://xoomer.virgilio.it/infinity77/AGW_Docs/

   (2) https://docs.couchdb.org/

   (3) https://rogerbinns.github.io/apsw/

   (4) https://arblib.org/

   (5) http://doc.bazaar.canonical.com/

   (6) https://www.crummy.com/software/BeautifulSoup/bs4/doc/

   (7) https://docs.blender.org/api/current/

   (8) https://bugzilla.readthedocs.io/

   (9) https://docs.buildbot.net/latest/

   (10) https://cmake.org/documentation/

   (11) https://docs.enthought.com/chaco/

   (12) https://downloads.pf.itd.nrl.navy.mil/docs/core/core-html/

   (13)
https://downloads.pf.itd.nrl.navy.mil/docs/core/core-python-html/

   (14) http://cormoran.nhopkg.org/docs/

   (15) https://deap.readthedocs.io/

   (16) https://pythonhosted.org/director/

   (17)
https://pageperso.lif.univ-mrs.fr/~edouard.thiel/ez-draw/doc/en/html/ez-manual.html

   (18) http://f2py.sourceforge.net/docs/

   (19) https://gmt.soest.hawaii.edu/doc/latest/

   (20) https://noble.gs.washington.edu/proj/genomedata/doc/1.3.3/

   (21) http://getfem.org/

   (22) https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/

   (23) http://grok.zope.org/doc/current/

   (24) https://manual.gromacs.org/documentation/

   (25) https://www.nongnu.org/gsl-shell/

   (26) https://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml/

   (27) https://api.freevo.org/kaa-base/

   (28) https://leoeditor.com/

   (29) http://www.acooke.org/lepl/

   (30) https://docs.enthought.com/mayavi/mayavi/

   (31) https://mediagoblin.readthedocs.io/

   (32) https://mpmath.org/doc/current/

   (33) https://docs.opencv.org/

   (34) https://excamera.com/articles/26/doc/index.html

   (35) http://www.opengda.org/gdadoc/html/

   (36) https://peach3.nl/doc/latest/userdoc/

   (37) https://docs.plone.org/

   (38) https://pyemd.readthedocs.io/

   (39) http://pyevolve.sourceforge.net/

   (40) https://www.pygame.org/docs/

   (41) https://pythonhosted.org/pymqi/

   (42) http://pyqt.sourceforge.net/Docs/PyQt4/

   (43) http://pyqt.sourceforge.net/Docs/PyQt5/

   (44) https://docs.python.org/2/

   (45) https://docs.python.org/3/

   (46) https://www.pypa.io/

   (47) http://ring-lang.sourceforge.net/doc/

   (48) https://doc.sagemath.org/

   (49)
https://noble.gs.washington.edu/proj/segway/doc/1.1.0/segway.html

   (50)
http://simupop.sourceforge.net/manual_release/build/userGuide.html

   (51) http://sprox.org/

   (52) https://docs.sympy.org/

   (53) https://turbogears.readthedocs.io/

   (54) https://docs.enthought.com/mayavi/tvtk/

   (55) https://www.varnish-cache.org/docs/

   (56) https://waf.io/apidocs/

   (57) https://wxpython.org/Phoenix/docs/html/main.html

   (58) http://yum.baseurl.org/api/yum/

   (59) https://www.ibiblio.org/paulcarduner/z3ctutorial/

   (60) https://pythonhosted.org/zc.async/

   (61) https://docs.zope.org/zope2/

12.3 Documentation using the sphinxdoc theme
============================================

   * ABRT(1)

   * cartopy(2)

   * Jython(3)

   * LLVM(4)

   * Matplotlib(5)

   * MDAnalysis Tutorial(6)

   * NetworkX(7)

   * PyCantonese(8)

   * Pyre(9)

   * pySPACE(10)

   * Pysparse(11)

   * PyTango(12)

   * Python Wild Magic(13) (customized)

   * RDKit(14)

   * Reteisi(15) (customized)

   * Sqlkit(16) (customized)

   * Turbulenz(17)

   ---------- Footnotes ----------

   (1) https://abrt.readthedocs.io/

   (2) https://scitools.org.uk/cartopy/docs/latest/

   (3) http://www.jython.org/docs/

   (4) https://llvm.org/docs/

   (5) https://matplotlib.org/

   (6) https://www.mdanalysis.org/MDAnalysisTutorial/

   (7) https://networkx.github.io/

   (8) https://pycantonese.org/

   (9) https://docs.danse.us/pyre/sphinx/

   (10) https://pyspace.github.io/pyspace/

   (11) http://pysparse.sourceforge.net/

   (12)
https://www.esrf.eu/computing/cs/tango/tango_doc/kernel_doc/pytango/latest/

   (13) https://vmlaker.github.io/pythonwildmagic/

   (14) https://www.rdkit.org/docs/

   (15) http://www.reteisi.org/contents.html

   (16) http://sqlkit.argolinux.org/

   (17) http://docs.turbulenz.com/

12.4 Documentation using the nature theme
=========================================

   * Alembic(1)

   * Cython(2)

   * easybuild(3)

   * jsFiddle(4)

   * libLAS(5) (customized)

   * Lmod(6)

   * MapServer(7) (customized)

   * Pandas(8)

   * pyglet(9) (customized)

   * PyWavelets(10)

   * Setuptools(11)

   * Spring Python(12)

   * StatsModels(13) (customized)

   * Sylli(14)

   ---------- Footnotes ----------

   (1) https://alembic.sqlalchemy.org/

   (2) https://docs.cython.org/

   (3) https://easybuild.readthedocs.io/

   (4) http://doc.jsfiddle.net/

   (5) https://www.liblas.org/

   (6) https://lmod.readthedocs.io/

   (7) https://mapserver.org/

   (8) https://pandas.pydata.org/pandas-docs/stable/

   (9) https://pyglet.readthedocs.io/

   (10) https://pywavelets.readthedocs.io/

   (11) https://setuptools.readthedocs.io/

   (12) https://docs.spring.io/spring-python/1.2.x/sphinx/html/

   (13) https://www.statsmodels.org/

   (14) http://sylli.sourceforge.net/

12.5 Documentation using another builtin theme
==============================================

   * Breathe(1) (haiku)

   * MPipe(2) (sphinx13)

   * NLTK(3) (agogo)

   * Programmieren mit PyGTK und Glade (German)(4) (agogo, customized)

   * PyPubSub(5) (bizstyle)

   * Pylons(6) (pyramid)

   * Pyramid web framework(7) (pyramid)

   * RxDock(8)

   * Sphinx(9) (sphinx13) :-)

   * Valence(10) (haiku, customized)

   ---------- Footnotes ----------

   (1) https://breathe.readthedocs.io/

   (2) https://vmlaker.github.io/mpipe/

   (3) https://www.nltk.org/

   (4) https://www.florian-diesch.de/doc/python-und-glade/online/

   (5) https://pypubsub.readthedocs.io/

   (6) https://docs.pylonsproject.org/projects/pylons-webframework/

   (7) https://docs.pylonsproject.org/projects/pyramid/

   (8) https://www.rxdock.org/documentation/html/devel/

   (9) https://www.sphinx-doc.org/

   (10) https://docs.valence.desire2learn.com/

12.6 Documentation using sphinx_rtd_theme
=========================================

   * Annotator(1)

   * Ansible(2) (customized)

   * Arcade(3)

   * aria2(4)

   * ASE(5)

   * asvin(6)

   * Autofac(7)

   * BigchainDB(8)

   * Blender Reference Manual(9)

   * Blocks(10)

   * bootstrap-datepicker(11)

   * Certbot(12)

   * Chainer(13) (customized)

   * CherryPy(14)

   * cloud-init(15)

   * CodeIgniter(16)

   * Conda(17)

   * Corda(18)

   * Dask(19)

   * Databricks(20) (customized)

   * Dataiku DSS(21)

   * DNF(22)

   * Django-cas-ng(23)

   * edX(24)

   * Electrum(25)

   * Elemental(26)

   * ESWP3(27)

   * Ethereum Homestead(28)

   * Exhale(29)

   * Faker(30)

   * Fidimag(31)

   * Flake8(32)

   * Flatpak(33)

   * FluidDyn(34)

   * Fluidsim(35)

   * Gallium(36)

   * GeoNode(37)

   * Glances(38)

   * Godot(39)

   * Graylog(40)

   * GPAW(41) (customized)

   * HDF5 for Python (h5py)(42)

   * Hyperledger Fabric(43)

   * Hyperledger Sawtooth(44)

   * IdentityServer(45)

   * Idris(46)

   * javasphinx(47)

   * Julia(48)

   * Jupyter Notebook(49)

   * Lasagne(50)

   * latexindent.pl(51)

   * Learning Apache Spark with Python(52)

   * LibCEED(53)

   * Linguistica(54)

   * Linux kernel(55)

   * Mailman(56)

   * MathJax(57)

   * MDTraj(58) (customized)

   * Mesa 3D(59)

   * micca - MICrobial Community Analysis(60)

   * MicroPython(61)

   * Minds(62) (customized)

   * Mink(63)

   * Mockery(64)

   * mod_wsgi(65)

   * MoinMoin(66)

   * Mopidy(67)

   * mpi4py(68)

   * MyHDL(69)

   * Nextflow(70)

   * NICOS(71) (customized)

   * OpenFAST(72)

   * Pelican(73)

   * picamera(74)

   * Pillow(75)

   * pip(76)

   * Paver(77)

   * peewee(78)

   * Phinx(79)

   * phpMyAdmin(80)

   * PROS(81) (customized)

   * Pushkin(82)

   * Pweave(83)

   * PyPy(84)

   * python-sqlparse(85)

   * PyVISA(86)

   * pyvista(87)

   * Read The Docs(88)

   * ROCm Platform(89)

   * Free your information from their silos (French)(90) (customized)

   * Releases Sphinx extension(91)

   * Qtile(92)

   * Quex(93)

   * QuTiP(94)

   * Satchmo(95)

   * Scapy(96)

   * SimGrid(97)

   * SimPy(98)

   * six(99)

   * SlamData(100)

   * Solidity(101)

   * Sonos Controller (SoCo)(102)

   * Sphinx AutoAPI(103)

   * sphinx-argparse(104)

   * Sphinx-Gallery(105) (customized)

   * Sphinx with Github Webpages(106)

   * SpotBugs(107)

   * StarUML(108)

   * Sublime Text Unofficial Documentation(109)

   * SunPy(110)

   * Sylius(111)

   * Syncthing(112)

   * Tango Controls(113) (customized)

   * Topshelf(114)

   * Theano(115)

   * ThreatConnect(116)

   * Tuleap(117)

   * TYPO3(118) (customized)

   * Veyon(119)

   * uWSGI(120)

   * virtualenv(121)

   * Wagtail(122)

   * Web Application Attack and Audit Framework (w3af)(123)

   * Weblate(124)

   * x265(125)

   * Zulip(126)

   ---------- Footnotes ----------

   (1) https://docs.annotatorjs.org/

   (2) https://docs.ansible.com/

   (3) https://arcade.academy/

   (4) https://aria2.github.io/manual/en/html/

   (5) https://wiki.fysik.dtu.dk/ase/

   (6) https://asvin.readthedocs.io/

   (7) https://docs.autofac.org/

   (8) https://docs.bigchaindb.com/

   (9) https://docs.blender.org/manual/

   (10) https://blocks.readthedocs.io/

   (11) https://bootstrap-datepicker.readthedocs.io/

   (12) https://letsencrypt.readthedocs.io/

   (13) https://docs.chainer.org/

   (14) https://docs.cherrypy.org/

   (15) https://cloudinit.readthedocs.io/

   (16) https://www.codeigniter.com/user_guide/

   (17) https://conda.io/docs/

   (18) https://docs.corda.net/

   (19) https://dask.pydata.org/

   (20) https://docs.databricks.com/

   (21) https://doc.dataiku.com/

   (22) https://dnf.readthedocs.io/

   (23) https://djangocas.dev/docs/

   (24) https://docs.edx.org/

   (25) https://docs.electrum.org/

   (26) https://libelemental.org/documentation/dev/

   (27) https://eswp3.readthedocs.io/

   (28) https://www.ethdocs.org/

   (29) https://exhale.readthedocs.io/

   (30) https://faker.readthedocs.io/

   (31) https://fidimag.readthedocs.io/

   (32) https://flake8.pycqa.org/

   (33) https://docs.flatpak.org/

   (34) https://fluiddyn.readthedocs.io/

   (35) https://fluidsim.readthedocs.io/

   (36) https://gallium.readthedocs.io/

   (37) https://docs.geonode.org/

   (38) https://glances.readthedocs.io/

   (39) https://godot.readthedocs.io/

   (40) https://docs.graylog.org/

   (41) https://wiki.fysik.dtu.dk/gpaw/

   (42) https://docs.h5py.org/

   (43) https://hyperledger-fabric.readthedocs.io/

   (44) https://intelledger.github.io/

   (45) https://docs.identityserver.io/

   (46) https://docs.idris-lang.org/

   (47) https://bronto-javasphinx.readthedocs.io/

   (48) https://julia.readthedocs.io/

   (49) https://jupyter-notebook.readthedocs.io/

   (50) https://lasagne.readthedocs.io/

   (51) https://latexindentpl.readthedocs.io/

   (52) https://runawayhorse001.github.io/LearningApacheSpark

   (53) https://libceed.readthedocs.io/

   (54) https://linguistica-uchicago.github.io/lxa5/

   (55) https://www.kernel.org/doc/html/latest/index.html

   (56) https://docs.list.org/

   (57) https://docs.mathjax.org/

   (58) http://mdtraj.org/latest/

   (59) https://docs.mesa3d.org/

   (60) https://micca.readthedocs.io/

   (61) https://docs.micropython.org/

   (62) https://www.minds.org/docs/

   (63) https://mink.behat.org/

   (64) https://docs.mockery.io/

   (65) https://modwsgi.readthedocs.io/

   (66) https://moin-20.readthedocs.io/

   (67) https://docs.mopidy.com/

   (68) https://mpi4py.readthedocs.io/

   (69) https://docs.myhdl.org/

   (70) https://www.nextflow.io/docs/latest/index.html

   (71) https://forge.frm2.tum.de/nicos/doc/nicos-master/

   (72) https://openfast.readthedocs.io/

   (73) https://docs.getpelican.com/

   (74) https://picamera.readthedocs.io/

   (75) https://pillow.readthedocs.io/

   (76) https://pip.pypa.io/

   (77) https://paver.readthedocs.io/

   (78) https://docs.peewee-orm.com/

   (79) https://docs.phinx.org/

   (80) https://docs.phpmyadmin.net/

   (81) https://pros.cs.purdue.edu/v5/

   (82) http://docs.pushkin.io/

   (83) https://mpastell.com/pweave/

   (84) https://doc.pypy.org/

   (85) https://sqlparse.readthedocs.io/

   (86) https://pyvisa.readthedocs.io/

   (87) https://docs.pyvista.org/

   (88) https://docs.readthedocs.io/

   (89) https://rocm-documentation.readthedocs.io/

   (90) https://redaction-technique.org/

   (91) https://releases.readthedocs.io/

   (92) https://docs.qtile.org/

   (93) http://quex.sourceforge.net/doc/html/main.html

   (94) https://qutip.org/docs/latest/

   (95) http://docs.satchmoproject.com/

   (96) https://scapy.readthedocs.io/

   (97) https://simgrid.org/doc/latest/

   (98) https://simpy.readthedocs.io/

   (99) https://six.readthedocs.io/

   (100) https://newdocs.slamdata.com

   (101) https://solidity.readthedocs.io/

   (102) https://docs.python-soco.com/

   (103) https://sphinx-autoapi.readthedocs.io/

   (104) https://sphinx-argparse.readthedocs.io/

   (105) https://sphinx-gallery.readthedocs.io/

   (106) https://runawayhorse001.github.io/SphinxGithub

   (107) https://spotbugs.readthedocs.io/

   (108) https://docs.staruml.io/

   (109) http://docs.sublimetext.info/

   (110) https://docs.sunpy.org/

   (111) http://docs.sylius.org/

   (112) https://docs.syncthing.net/

   (113) https://tango-controls.readthedocs.io/

   (114) https://docs.topshelf-project.com/

   (115) http://www.deeplearning.net/software/theano/

   (116) https://docs.threatconnect.com/

   (117) https://tuleap.net/doc/en/

   (118) https://docs.typo3.org/

   (119) https://docs.veyon.io/

   (120) https://uwsgi-docs.readthedocs.io/

   (121) https://virtualenv.readthedocs.io/

   (122) https://docs.wagtail.io/

   (123) https://docs.w3af.org/

   (124) https://docs.weblate.org/

   (125) https://x265.readthedocs.io/

   (126) https://zulip.readthedocs.io/

12.7 Documentation using sphinx_bootstrap_theme
===============================================

   * Bootstrap Theme(1)

   * C/C++ Software Development with Eclipse(2)

   * Dataverse(3)

   * e-cidadania(4)

   * Hangfire(5)

   * Hedge(6)

   * ObsPy(7)

   * Open Dylan(8)

   * OPNFV(9)

   * Pootle(10)

   * PyUblas(11)

   * seaborn(12)

   ---------- Footnotes ----------

   (1) https://ryan-roemer.github.io/sphinx-bootstrap-theme/

   (2) https://eclipsebook.in/

   (3) https://guides.dataverse.org/

   (4) https://e-cidadania.readthedocs.io/

   (5) https://docs.hangfire.io/

   (6) https://documen.tician.de/hedge/

   (7) https://docs.obspy.org/

   (8) https://opendylan.org/documentation/

   (9) https://docs.opnfv.org/

   (10) https://docs.translatehouse.org/projects/pootle/

   (11) https://documen.tician.de/pyublas/

   (12) https://seaborn.pydata.org/

12.8 Documentation using a custom theme or integrated in a website
==================================================================

   * AIOHTTP(1)

   * Apache Cassandra(2)

   * Astropy(3)

   * Bokeh(4)

   * Boto 3(5)

   * CakePHP(6)

   * CasperJS(7)

   * Ceph(8)

   * Chef(9)

   * CKAN(10)

   * Confluent Platform(11)

   * Django(12)

   * Doctrine(13)

   * Enterprise Toolkit for Acrobat products(14)

   * FreeFEM(15)

   * fmt(16)

   * Gameduino(17)

   * gensim(18)

   * GeoServer(19)

   * gevent(20)

   * GHC - Glasgow Haskell Compiler(21)

   * Guzzle(22)

   * H2O.ai(23)

   * Heka(24)

   * Istihza (Turkish Python documentation project)(25)

   * JupyterHub(26)

   * Kombu(27)

   * Lasso(28)

   * Mako(29)

   * MirrorBrain(30)

   * Mitiq(31)

   * MongoDB(32)

   * Music21(33)

   * MyHDL(34)

   * ndnSIM(35)

   * nose(36)

   * ns-3(37)

   * NumPy(38)

   * ObjectListView(39)

   * OpenERP(40)

   * OpenCV(41)

   * OpenLayers(42)

   * OpenTURNS(43)

   * Open vSwitch(44)

   * PlatformIO(45)

   * PyEphem(46)

   * Pygments(47)

   * Plone User Manual (German)(48)

   * PSI4(49)

   * PyMOTW(50)

   * python-aspectlib(51) (sphinx_py3doc_enhanced_theme(52))

   * QGIS(53)

   * qooxdoo(54)

   * Roundup(55)

   * SaltStack(56)

   * scikit-learn(57)

   * SciPy(58)

   * Scrapy(59)

   * Seaborn(60)

   * Selenium(61)

   * Self(62)

   * Substance D(63)

   * Sulu(64)

   * SQLAlchemy(65)

   * tinyTiM(66)

   * Twisted(67)

   * Ubuntu Packaging Guide(68)

   * WebFaction(69)

   * WTForms(70)

   ---------- Footnotes ----------

   (1) https://docs.aiohttp.org/

   (2) https://cassandra.apache.org/doc/

   (3) https://docs.astropy.org/

   (4) https://bokeh.pydata.org/

   (5) https://boto3.readthedocs.io/

   (6) https://book.cakephp.org/

   (7) http://docs.casperjs.org/

   (8) https://docs.ceph.com/docs/master/

   (9) https://docs.chef.io/

   (10) https://docs.ckan.org/

   (11) https://docs.confluent.io/

   (12) https://docs.djangoproject.com/

   (13) https://www.doctrine-project.org/

   (14) https://www.adobe.com/devnet-docs/acrobatetk/

   (15) https://doc.freefem.org/introduction/

   (16) https://fmt.dev/

   (17) https://excamera.com/sphinx/gameduino/

   (18) https://radimrehurek.com/gensim/

   (19) https://docs.geoserver.org/

   (20) https://www.gevent.org/

   (21) https://downloads.haskell.org/~ghc/master/users-guide/

   (22) https://docs.guzzlephp.org/

   (23) https://docs.h2o.ai/

   (24) https://hekad.readthedocs.io/

   (25) https://belgeler.yazbel.com/python-istihza/

   (26) https://jupyterhub.readthedocs.io/

   (27) http://docs.kombu.me/

   (28) https://lassoguide.com/

   (29) https://docs.makotemplates.org/

   (30) https://mirrorbrain.org/docs/

   (31) https://mitiq.readthedocs.io/

   (32) https://docs.mongodb.com/

   (33) https://web.mit.edu/music21/doc/

   (34) https://docs.myhdl.org/

   (35) https://ndnsim.net/current/

   (36) https://nose.readthedocs.io/

   (37) https://www.nsnam.org/documentation/

   (38) https://docs.scipy.org/doc/numpy/reference/

   (39) http://objectlistview.sourceforge.net/python/

   (40) https://doc.odoo.com/

   (41) https://docs.opencv.org/

   (42) http://docs.openlayers.org/

   (43) https://openturns.github.io/openturns/master/

   (44) https://docs.openvswitch.org/

   (45) https://docs.platformio.org/

   (46) https://rhodesmill.org/pyephem/

   (47) https://pygments.org/docs/

   (48) https://www.hasecke.com/plone-benutzerhandbuch/4.0/

   (49) https://www.psicode.org/psi4manual/master/index.html

   (50) https://pymotw.com/2/

   (51) https://python-aspectlib.readthedocs.io/

   (52) https://pypi.org/project/sphinx_py3doc_enhanced_theme/

   (53) https://qgis.org/en/docs/index.html

   (54) https://www.qooxdoo.org/current/

   (55) https://www.roundup-tracker.org/

   (56) https://docs.saltstack.com/

   (57) https://scikit-learn.org/stable/

   (58) https://docs.scipy.org/doc/scipy/reference/

   (59) https://doc.scrapy.org/

   (60) https://seaborn.pydata.org/

   (61) https://docs.seleniumhq.org/docs/

   (62) https://www.selflanguage.org/

   (63) https://docs.pylonsproject.org/projects/substanced/

   (64) https://docs.sulu.io/

   (65) https://docs.sqlalchemy.org/

   (66) http://tinytim.sourceforge.net/docs/2.0/

   (67) https://twistedmatrix.com/documents/current/

   (68) https://packaging.ubuntu.com/html/

   (69) https://docs.webfaction.com/

   (70) https://wtforms.readthedocs.io/

12.9 Homepages and other non-documentation sites
================================================

   * Arizona State University PHY494/PHY598/CHM598 Simulation approaches
     to Bio-and Nanophysics(1) (classic)

   * Benoit Boissinot(2) (classic, customized)

   * Computer Networks, Parallelization, and Simulation Laboratory
     (CNPSLab)(3) (sphinx_rtd_theme)

   * Deep Learning Tutorials(4) (sphinxdoc)

   * Eric Holscher(5) (alabaster)

   * Lei Ma’s Statistical Mechanics lecture notes(6)
     (sphinx_bootstrap_theme)

   * Loyola University Chicago COMP 339-439 Distributed Systems
     course(7) (sphinx_bootstrap_theme)

   * Pylearn2(8) (sphinxdoc, customized)

   * PyXLL(9) (sphinx_bootstrap_theme, customized)

   * SciPy Cookbook(10) (sphinx_rtd_theme)

   * Tech writer at work blog(11) (custom theme)

   * The Wine Cellar Book(12) (sphinxdoc)

   * Thomas Cokelaer’s Python, Sphinx and reStructuredText tutorials(13)
     (standard)

   * UC Berkeley ME233 Advanced Control Systems II course(14)
     (sphinxdoc)

   * Željko Svedružić’s Biomolecular Structure and Function Laboratory
     (BioSFLab)(15) (sphinx_bootstrap_theme)

   ---------- Footnotes ----------

   (1)
https://becksteinlab.physics.asu.edu/pages/courses/2013/SimBioNano/

   (2) https://bboissin.appspot.com/

   (3) https://lab.miletic.net/

   (4) http://www.deeplearning.net/tutorial/

   (5) https://ericholscher.com/

   (6) http://statisticalphysics.openmetric.org/

   (7) https://books.cs.luc.edu/distributedsystems/

   (8) http://www.deeplearning.net/software/pylearn2/

   (9) https://www.pyxll.com/

   (10) https://scipy-cookbook.readthedocs.io/

   (11) https://blog.documatt.com/

   (12) https://www.thewinecellarbook.com/doc/en/

   (13) https://thomas-cokelaer.info/tutorials/

   (14) https://berkeley-me233.github.io/

   (15) https://www.svedruziclab.com/

12.10 Books produced using Sphinx
=================================

   * "The Art of Community" (Japanese translation)(1)

   * "Die Wahrheit des Sehens.  Der DEKALOG von Krzysztof Kieślowski"(2)

   * "Expert Python Programming"(3)

   * "Expert Python Programming" (Japanese translation)(4)

   * "Expert Python Programming 2nd Edition" (Japanese translation)(5)

   * "The Hitchhiker’s Guide to Python"(6)

   * "LassoGuide"(7)

   * "Learning Sphinx" (in Japanese)(8)

   * "Learning System Programming with Go (Japanese)"(9)

   * "Mercurial: the definitive guide (Second edition)"(10)

   * "Mithril – The fastest clientside MVC (Japanese)"(11)

   * "Pioneers and Prominent Men of Utah"(12)

   * "Pomodoro Technique Illustrated" (Japanese translation)(13)

   * "Professional Software Development"(14)

   * "Python Professional Programming" (in Japanese)(15)

   * "Python Professional Programming 2nd Edition" (in Japanese)(16)

   * "Python Professional Programming 3rd Edition" (in Japanese)(17)

   * Python Course by Yuri Petrov (Russian)(18)

   * "Real World HTTP – Learning The Internet and Web Technology via its
     history and code (Japanese)"(19)

   * "Redmine Primer 5th Edition (in Japanese)"(20)

   * "The repoze.bfg Web Application Framework"(21)

   * "The Self-Taught Programmer" (Japanese translation)(22)

   * "Simple and Steady Way of Learning for Software Engineering" (in
     Japanese)(23)

   * "Software-Dokumentation mit Sphinx"(24)

   * "Theoretical Physics Reference"(25)

   * "The Varnish Book"(26)

   ---------- Footnotes ----------

   (1) https://www.oreilly.co.jp/books/9784873114958/

   (2)
https://literatur.hasecke.com/post/die-wahrheit-des-sehens-dekalog-kieslowski/

   (3)
https://www.packtpub.com/application-development/expert-python-programming

   (4) https://www.amazon.co.jp/dp/4048686291/

   (5) https://www.amazon.co.jp/dp/4048930613/

   (6) https://docs.python-guide.org/

   (7) https://www.lassosoft.com/Lasso-Documentation

   (8) https://www.oreilly.co.jp/books/9784873116488/

   (9) https://www.lambdanote.com/products/go

   (10) https://book.mercurial-scm.org/

   (11) https://www.oreilly.co.jp/books/9784873117447/

   (12) http://pioneers.rstebbing.com/

   (13) https://www.amazon.co.jp/dp/4048689525/

   (14) https://mixmastamyk.bitbucket.io/pro_soft_dev/

   (15) https://www.amazon.co.jp/dp/4798032948/

   (16) https://www.amazon.co.jp/dp/479804315X/

   (17) https://www.amazon.co.jp/dp/4798053821/

   (18) https://www.yuripetrov.ru/edu/python

   (19) https://www.oreilly.co.jp/books/9784873118048/

   (20) https://www.shuwasystem.co.jp/products/7980html/4825.html

   (21)
https://www.amazon.com/repoze-bfg-Web-Application-Framework-Version/dp/0615345379

   (22) https://www.amazon.co.jp/dp/4822292274/

   (23) https://www.amazon.co.jp/dp/477414259X/

   (24) https://www.amazon.de/dp/1497448689/

   (25) https://www.theoretical-physics.net/

   (26) https://info.varnish-software.com/the-varnish-book

12.11 These produced using Sphinx
=================================

   * "A Web-Based System for Comparative Analysis of OpenStreetMap Data
     by the Use of CouchDB"(1)

   * "Content Conditioning and Distribution for Dynamic Virtual
     Worlds"(2)

   * "The Sphinx Thesis Resource"(3)

   ---------- Footnotes ----------

   (1)
https://www.yumpu.com/et/document/view/11722645/masterthesis-markusmayr-0542042

   (2) https://www.cs.princeton.edu/research/techreps/TR-941-12

   (3) https://jterrace.github.io/sphinxtr/

12.12 Projects integrating Sphinx functionality
===============================================

   * Read the Docs(1), a software-as-a-service documentation hosting
     platform, uses Sphinx to automatically build documentation updates
     that are pushed to GitHub.

   * Spyder(2), the Scientific Python Development Environment, uses
     Sphinx in its help pane to render rich documentation for functions,
     classes and methods automatically or on-demand.

   ---------- Footnotes ----------

   (1) https://readthedocs.org/

   (2) https://docs.spyder-ide.org/help.html