sphinx-all - Man Page

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

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

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

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.

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 names, which in short means that you leave off the file name extension and use forward slashes (/) as directory separators.

[image: more info] [image]
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.)

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.

Update the below link when we add new guides on these.

[image: more info] [image]
See reStructuredText for a more in-depth introduction to reStructuredText, including markup added by Sphinx.

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 -M html sourcedir outputdir

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

[image: more info] [image]
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.

Move this whole section into a guide on rST or directives

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:

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.

[image: more info] [image]
See Domains for all the available domains and their directives/roles.

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

[image: more info] [image]
See Configuration for documentation of all available config values.

Move this entire doc to a different section

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 in your conf.py.

WARNING:

[image: more info] [image]
See sphinx.ext.autodoc for the complete description of the features of autodoc.

Move this doc to another section

Many Sphinx documents including the Python documentation are published on the Internet.  When you want to make links to such documents from your documentation, you can do it with 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.

[image: more info] [image]
See sphinx.ext.intersphinx for the complete description of the features of intersphinx.

• Other extensions:
• Static files
• Selecting a theme
• Templating
• Using extensions
• Writing extensions

• Overview
• Linux
• macOS
• Windows
• Installation from PyPI
• Docker
• Installation from source

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

Install either python3-sphinx using apt-get:

$ apt-get install python3-sphinx

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

Install python-sphinx using yum:

$ yum install python-sphinx

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

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

Sphinx can be installed using Homebrew, MacPorts, or as part of a Python distribution such as Anaconda.

$ brew install sphinx-doc

For more information, refer to the package overview.

Install either python3x-sphinx using port:

$ sudo port install py39-sphinx

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

$ sudo port select --set python python39
$ sudo port select --set sphinx py39-sphinx

For more information, refer to the package overview.

$ conda install sphinx

Sphinx can be install using Chocolatey or installed manually.

$ choco install sphinx

You would need to install Chocolatey before running this.

For more information, refer to the chocolatey page.

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 Python on Windows installation guides. You must install Python 3.

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

Sphinx packages are published on the Python Package Index.  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

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

SEE ALSO:

venv – creating virtual environments

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

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

• sphinxdoc/sphinx
• sphinxdoc/sphinx-latexpdf

Former one is used for standard usage of Sphinx, and latter one is mainly used for PDF builds using LaTeX.  Please choose one for your purpose.

NOTE:

sphinxdoc/sphinx-latexpdf contains TeXLive packages. So the image is very large (over 2GB!).

HINT:

When using docker images, please use docker run command to invoke sphinx commands.  For example, you can use following command to create a Sphinx project:

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

And you can use the following command to build HTML document:

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

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

You can install Sphinx directly from a clone of the Git repository.  This can be done either by cloning the repo and installing from the local clone, on simply installing directly via git.

$ git clone https://github.com/sphinx-doc/sphinx
$ cd sphinx
$ pip install .

$ pip install git+https://github.com/sphinx-doc/sphinx

You can also download a snapshot of the Git repo in either tar.gz or zip format.  Once downloaded and extracted, these can be installed with pip as above.

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:

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.

In a new directory, create a file called README.rst with the following content.

README.rst

Lumache
=======

**Lumache** (/lu'make/) is a Python library for cooks and food lovers that
creates recipes mixing random ingredients.

It is a good moment to create a Python virtual environment and install the required tools.  For that, open a command line terminal, cd into the directory you just created, and run the following commands:

$ 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!

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 -M html docs/source/ docs/build/

And finally, open docs/build/html/index.html in your browser.  You should see something like this:

There we go! You created your first HTML documentation using Sphinx. Now you can start customizing it.

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:

docs/source/index.rst

Welcome to Lumache's documentation!
===================================

**Lumache** (/lu'make/) is a Python library for cooks and food lovers that
creates recipes mixing random ingredients.  It pulls data from the `Open Food
Facts database <https://world.openfoodfacts.org/>`_ and offers a *simple* and
*intuitive* API.

.. note::

   This project is under active development.

This showcases several features of the reStructuredText syntax, including:

• a section header using === for the underline,
• two examples of 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!

Sphinx supports a variety of formats apart from HTML, including PDF, EPUB, 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, or preview index.xhtml on a web browser.

NOTE:

Each output format has some specific configuration options that you can tune, 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:

There are two main ways to customize your documentation beyond what is possible with core Sphinx: extensions and themes.

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:

docs/source/conf.py

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.duration',
]

After that, every time you generate your documentation, you will see a short durations report at the end of the console output, like this one:

(.venv) $ make html
...
The HTML pages are in build/html.

====================== slowest reading durations =======================
0.042 temp/source/index

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.

For example, to use the Furo 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:

docs/source/conf.py

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'furo'

With this change, you will notice that your HTML documentation has now a new appearance:

It is now time to expand the narrative documentation and split it into several documents.

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:

docs/source/usage.rst

Usage
=====

Installation
------------

To use Lumache, first install it using pip:

.. code-block:: console

   (.venv) $ pip install lumache

This new file contains two 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:

docs/source/index.rst

Contents
--------

.. toctree::

   usage

This step inserts that document in the root of the toctree, so now it belongs to the structure of your project, which so far looks like this:

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:

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:

docs/source/index.rst

Check out the :doc:`usage` section for further information.

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.

For example, to reference the “Installation” subsection, add a label right before the heading, as follows:

docs/source/usage.rst

Usage
=====

.. _installation:

Installation
------------

...

And make the sentence you added in index.rst look like this:

docs/source/index.rst

Check out the :doc:`usage` section for further information, including how to
:ref:`install <installation>` the project.

Notice a trick here: the install part specifies how the link will look like (we want it to be a specific word, so the sentence makes sense), whereas the <installation> part refers to the actual label we want to add a cross-reference to. If you do not include an explicit title, hence using :ref:`installation`, the section title will be used (in this case, Installation). Both the :doc: and the :ref: roles will be rendered as hyperlinks in the HTML documentation.

What about documenting code objects in Sphinx? Read on!

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.

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:

docs/source/usage.rst

Creating recipes
----------------

To retrieve a list of random ingredients,
you can use the ``lumache.get_random_ingredients()`` function:

.. py:function:: lumache.get_random_ingredients(kind=None)

   Return a list of random ingredients as strings.

   :param kind: Optional "kind" of ingredients.
   :type kind: list[str] or None
   :return: The ingredients list.
   :rtype: list[str]

Which will render like this:

Notice several things:

• Sphinx parsed the argument of the .. py:function directive and highlighted the module, the function name, and the parameters appropriately.
• The directive content includes a one-line description of the function, as well as an 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.

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:

docs/source/usage.rst

The ``kind`` parameter should be either ``"meat"``, ``"fish"``,
or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients`
will raise an exception.

When generating code documentation, Sphinx will generate a cross-reference automatically just by using the name of the object, without you having to explicitly use a role for that. For example, you can describe the custom exception raised by the function using the py:exception directive:

docs/source/usage.rst

.. py:exception:: lumache.InvalidKindError

   Raised if the kind is invalid.

Then, add this exception to the original description of the function:

docs/source/usage.rst

.. py:function:: lumache.get_random_ingredients(kind=None)

   Return a list of random ingredients as strings.

   :param kind: Optional "kind" of ingredients.
   :type kind: list[str] or None
   :raise lumache.InvalidKindError: If the kind is invalid.
   :return: The ingredients list.
   :rtype: list[str]

And finally, this is how the result would look:

Beautiful, isn’t it?

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:

docs/source/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())

NOTE:

An alternative to changing the sys.path variable is to create a pyproject.toml file and make the code installable, so it behaves like any other Python library. However, the sys.path approach is simpler.

Then, before adding doctests to your documentation, enable the doctest extension in conf.py:

docs/source/conf.py

extensions = [
    'sphinx.ext.duration',
    'sphinx.ext.doctest',
]

Next, write a doctest block as follows:

docs/source/usage.rst

>>> import lumache
>>> lumache.get_random_ingredients()
['shells', 'gorgonzola', 'parsley']

Doctests include the Python instructions to be run preceded by >>>, the standard Python interpreter prompt, as well as the expected output of each instruction. This way, Sphinx can check whether the actual output matches the expected one.

To observe how a doctest failure looks like (rather than a code error as above), let’s write the return value incorrectly first. Therefore, add a function get_random_ingredients like this:

lumache.py

def get_random_ingredients(kind=None):
    return ["eggs", "bacon", "spam"]

You can now run make doctest to execute the doctests of your documentation. Initially this will display an error, since the actual code does not behave as specified:

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

lumache.py

def get_random_ingredients(kind=None):
    return ["shells", "gorgonzola", "parsley"]

And finally, make doctest 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.

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,
• Julia, or
• PHP.

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:

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.

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 in the documentation, rather than having to write the information in two places.

Fortunately, the autodoc extension provides this functionality.

To use autodoc, first add it to the list of enabled extensions:

docs/source/conf.py

extensions = [
    'sphinx.ext.duration',
    'sphinx.ext.doctest',
    'sphinx.ext.autodoc',
]

Next, move the content of the .. py:function directive to the function docstring in the original Python file, as follows:

lumache.py

def get_random_ingredients(kind=None):
    """
    Return a list of random ingredients as strings.

    :param kind: Optional "kind" of ingredients.
    :type kind: list[str] or None
    :raise lumache.InvalidKindError: If the kind is invalid.
    :return: The ingredients list.
    :rtype: list[str]

    """
    return ["shells", "gorgonzola", "parsley"]

Finally, replace the .. py:function directive from the Sphinx documentation with autofunction:

docs/source/usage.rst

you can use the ``lumache.get_random_ingredients()`` function:

.. autofunction:: lumache.get_random_ingredients

If you now build the HTML documentation, the output will be the same! With the advantage that it is generated from the code itself. Sphinx took the reStructuredText from the docstring and included it, also generating proper cross-references.

You can also autogenerate documentation from other objects. For example, add the code for the InvalidKindError exception:

lumache.py

class InvalidKindError(Exception):
    """Raised if the kind is invalid."""
    pass

And replace the .. py:exception directive with autoexception as follows:

docs/source/usage.rst

or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients`
will raise an exception.

.. autoexception:: lumache.InvalidKindError

And again, after running make html, the output will be the same as before.

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:

docs/source/conf.py

extensions = [
   'sphinx.ext.duration',
   'sphinx.ext.doctest',
   'sphinx.ext.autodoc',
   'sphinx.ext.autosummary',
]

Next, create a new api.rst file with these contents:

docs/source/api.rst

API
===

.. autosummary::
   :toctree: generated

   lumache

Remember to include the new document in the root toctree:

docs/source/index.rst

Contents
--------

.. toctree::

   usage
   api

Finally, after you build the HTML documentation running make html, it will contain two new pages:

• api.html, corresponding to docs/source/api.rst and containing a table with the objects you included in the autosummary directive (in this case, only one).

• generated/lumache.html, corresponding to a newly created reST file generated/lumache.rst and containing a summary of members of the module, in this case one function and one exception.

  [image: Summary page created by autosummary] [image] Summary page created by autosummary.UNINDENT

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:

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.

There are several possible options you have to host your Sphinx documentation. Some of them are:

Read the Docs

Read the Docs is an online service specialized in hosting technical documentation written in Sphinx, as well as MkDocs. They have a number of extra features, such as versioned documentation, traffic and search analytics, custom domains, user-defined redirects, and more.

GitHub Pages

GitHub Pages is a simple static web hosting tightly integrated with GitHub: static HTML is served from one of the branches of a project, and usually sources are stored in another branch so that the output can be updated every time the sources change (for example using GitHub Actions). It is free to use and supports custom domains.

GitLab Pages

GitLab Pages is a similar concept to GitHub Pages, integrated with GitLab and usually automated with GitLab CI instead.

Netlify

Netlify is a sophisticated hosting for static sites enhanced by client-side web technologies like JavaScript (so-called “Jamstack”). They offer support for headless content management systems and serverless computing.

Your own server

You can always use your own web server to host Sphinx HTML documentation. It is the option that gives more flexibility, but also more complexity.

All these options have zero cost, with the option of paying for extra features.

The free offerings of most of the options listed above require your documentation sources to be publicly available. Moreover, these services expect you to use a Version Control System, a technology that tracks the evolution of a collection of files as a series of snapshots (“commits”). The practice of writing documentation in plain text files with the same tools as the ones used for software development is commonly known as “Docs as Code”.

The most popular Version Control System nowadays is Git, a free and open source tool that is the backbone of services like GitHub and GitLab. Since both Read the Docs and Netlify have integrations with GitHub and GitLab, and both GitHub and GitLab have an integrated Pages product, the most effective way of automatically build your documentation online is to upload your sources to either of these Git hosting services.

The quickest way to upload an existing project to GitHub is to:

1.

Sign up for a GitHub account.

2.

Create a new repository.

3.

Open the “Upload files” page of your new repository.

4.

Select the files on your operating system file browser (in your case README.rst, lumache.py, the makefiles under the docs directory, and everything under docs/source) and drag them to the GitHub interface to upload them all.

5.

Click on the 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, read this quickstart tutorial or consult the official GitHub documentation

Similarly to GitHub, the fastest way to upload your project to GitLab is using the web interface:

1. Sign up for a GitLab account.
2. Create a new blank project.
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 [1].

Again, these steps do not require additional software on your computer. To learn more, you can:

• Follow this tutorial to install Git on your machine.
• Browse the GitLab User documentation to understand the possibilities of the platform.

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.

[1]

At the time of writing, uploading whole directories to GitLab using only the web interface is not yet implemented.

Read the Docs offers integration with both GitHub and GitLab. The quickest way of getting started is to follow the RTD tutorial, which is loosely based on this one. You can publish your sources on GitHub as explained in the previous section, then skip directly to readthedocs:tutorial/index:Sign up for Read the Docs. If you choose GitLab instead, the process is similar.

GitHub Pages requires you to publish your sources on GitHub. After that, you will need an automated process that performs the make html step every time the sources change. That can be achieved using GitHub Actions.

After you have published your sources on GitHub, create a file named .github/workflows/sphinx.yml in your repository with the following contents:

.github/workflows/

name: "Sphinx: Render docs"

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
    - uses: actions/checkout@v4
    - name: Build HTML
      uses: ammaraskar/sphinx-action@master
    - name: Upload artifacts
      uses: actions/upload-artifact@v4
      with:
        name: html-docs
        path: docs/build/html/
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      if: github.ref == 'refs/heads/main'
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: docs/build/html

This contains a GitHub Actions workflow with a single job of four steps:

1. Checkout the code.
2. Build the HTML documentation using Sphinx.
3. Attach the HTML output the artifacts to the GitHub Actions job, for easier inspection.
4. If the change happens on the default branch, take the contents of docs/build/html and push it to the gh-pages branch.

Next, you need to specify the dependencies for the make html step to be successful. For that, create a file docs/requirements.txt and add the following contents:

docs/requirements.txt

furo==2021.11.16

And finally, you are ready to enable GitHub Pages on your repository. 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.

GitLab Pages, on the other hand, requires you to publish your sources on GitLab. When you are ready, you can automate the process of running make html using GitLab CI.

After you have published your sources on GitLab, create a file named .gitlab-ci.yml in your repository with these contents:

.gitlab-ci.yml

stages:
  - deploy

pages:
  stage: deploy
  image: python:3.9-slim
  before_script:
    - apt-get update && apt-get install make --no-install-recommends -y
    - python -m pip install sphinx furo
  script:
    - cd docs && make html
  after_script:
    - mv docs/build/html/ ./public/
  artifacts:
    paths:
    - public
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

This contains a GitLab CI workflow with one job of several steps:

1.

Install the necessary dependencies.

2.

Build the HTML documentation using Sphinx.

3.

Move the output to a known artifacts location.

NOTE:

You will need to validate your account by entering a payment method (you will be charged a small amount that will then be reimbursed).

After that, if the pipeline is successful, you should be able to see your HTML at the designated URL.

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.

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 Writing Sphinx Extensions.

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.

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

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.

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

Line blocks (ref) 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, with caveats noted in Field Lists)
• option lists (ref)
• quoted literal blocks (ref)
• doctest blocks (ref)

Literal code blocks (ref) 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.

Doctest blocks (ref) 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

For grid tables (ref), 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) 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.

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:

You can also separate the link and the target definition (ref), like this:

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

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

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

Section headers (ref) are created by underlining (and optionally overlining) the section title with a punctuation character, at least as long as the text:

=================
This is a heading
=================

Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings.  However, this convention is used in Python Developer’s Guide for documenting 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.

Field lists (ref) 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.

A role or “custom interpreted text role” (ref) 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 – equivalent of *emphasis*
• strong – equivalent of **strong**
• literal – equivalent of ``literal``
• subscript – subscript text
• superscript – superscript text
• title-reference – for titles of books, periodicals, and other materials

Refer to Roles for roles added by Sphinx.

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

A directive (ref) 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, caution, danger, error, hint, important, note, tip, warning and the generic admonition.  (Most themes style only “note” and “warning” specially.)

• Images:

  • image (see also Images below)
  • figure (an image with caption and optional legend)

• Additional body elements:

  • contents (a local, i.e. for the current file only, table of contents)
  • container (a container with a custom class, useful to generate an outer <div> in HTML)
  • rubric (a heading without relation to the document sectioning)
  • topic, sidebar (special highlighted body elements)
  • parsed-literal (literal block that supports inline markup)
  • epigraph (a block quote with optional attribution line)
  • highlights, pull-quote (block quotes with their own class attribute)
  • compound (a compound paragraph)

• Special tables:

  • table (a table with title)
  • csv-table (a table generated from comma-separated values)
  • list-table (a table generated from a list of lists)

• Special directives:

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

  • class (assign a class attribute to the next element)

    NOTE:

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

• HTML specifics:

  • meta (generation of HTML <meta> tags, see also HTML Metadata below)
  • title (override document title)

• Influencing markup:

  • default-role (set a new default role)
  • role (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, header and footer.

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.

reST supports an image directive (ref), 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).

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

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

reST supports “substitutions” (ref), 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 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.

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

The meta directive allows specifying the HTML metadata element of a Sphinx documentation page.  For example, the directive:

.. meta::
   :description: The Sphinx documentation builder
   :keywords: Sphinx, documentation, builder

will generate the following HTML output:

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

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.

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 for the details.
• No nested inline markup: Something like *see :func:`foo`* is not possible.

Sphinx uses interpreted text roles to insert semantic markup into documents. They are written as :rolename:`content`.

NOTE:

See Domains for roles added by domains.

See Cross-referencing syntax.

Cross-reference roles include:

• any
• doc
• download
• envvar
• keyword
• numref
• option (and the deprecated cmdoption)
• ref
• term
• token

:code:

An inline code example.  When used directly, this role just displays the text without syntax highlighting, as a literal.

By default, inline code such as :code:`1 + 2` just displays without
highlighting.

Displays: By default, inline code such as 1 + 2 just displays without highlighting.

Unlike the code-block directive, this role does not respect the default language set by the highlight directive.

To enable syntax highlighting, you must first use the Docutils role directive to define a custom role associated with a specific language:

.. role:: python(code)
   :language: python

In Python, :python:`1 + 2` is equal to :python:`3`.

To display a multi-line code example, use the code-block directive instead.

:math:

Role for inline math.  Use like this:

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

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

:eq:

Same as math:numref.

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

:abbr:

An abbreviation.  If the role content contains a parenthesized explanation, it will be treated specially: it will be shown in a tool-tip in HTML, and output only once in LaTeX.

For example: :abbr:`LIFO (last-in, first-out)` displays LIFO.

Added in version 0.6.

:command:

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

For example: rm

:dfn:

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

For example: binary mode

:file:

The name of a file or directory.  Within the contents, you can use curly braces to indicate a “variable” part, for example:

... is installed in :file:`/usr/lib/python3.{x}/site-packages` ...

Displays: … is installed in /usr/lib/python3.x/site-packages …

In the built documentation, the x will be displayed differently to indicate that it is to be replaced by the Python minor version.

: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 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 (for example: :guilabel:`&Cancel` displays Cancel).  To include a literal ampersand, double it.

:kbd:

Mark a sequence of keystrokes.  What form the key sequence takes may depend on platform- or application-specific conventions.  When there are no relevant conventions, the names of modifier keys should be spelled out, to improve accessibility for new users and non-native speakers.  For example, an xemacs key sequence may be marked like :kbd:`C-x C-f`, but without reference to a specific application or platform, the same sequence should be marked as :kbd:`Control-x Control-f`, displaying C-x C-f and Control-x Control-f respectively.

:mailheader:

The name of an RFC 822-style mail header.  This markup does not imply that the header is being used in an email message, but can be used to refer to any header of the same “style.”  This is also used for headers defined by the various MIME specifications.  The header name should be entered in the same way it would normally be found in practice, with the camel-casing conventions being preferred where there is more than one common usage. For example: :mailheader:`Content-Type` displays Content-Type.

:makevar:

The name of a make variable.

For example: help

:manpage:

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

Changed in version 7.3: Allow specifying a target with <>, like hyperlinks. For example, :manpage:`blah <ls(1)>` displays blah.

:menuselection:

Menu selections should be marked using the menuselection role.  This is used to mark a complete sequence of menu selections, including selecting submenus and choosing a specific operation, or any subsequence of such a sequence.  The names of individual selections should be separated by -->.

For example, to mark the selection “Start > Programs”, use this markup:

:menuselection:`Start --> Programs`

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

:mimetype:

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

For example: text/plain

:newsgroup:

The name of a Usenet newsgroup.

For example: comp.lang.python

Is this not part of the standard domain?

:program:

The name of an executable program.  This may differ from the file name for the executable for some platforms.  In particular, the .exe (or other) extension should be omitted for Windows programs.

For example: curl

:regexp:

A regular expression. Quotes should not be included.

For example: ([abc])+

: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: print(1+variable)

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

Changed in version 1.8: Allowed to escape curly braces with double backslash.  For example, in :samp:`print(f"answer=\\{1+{variable}*2\\}")`, the part variable would be emphasized and the escaped curly braces would be displayed: print(f"answer={1+variable*2}")

There is also an index role to generate index entries.

The following roles generate external links:

:pep:

A reference to a Python Enhancement Proposal.  This generates appropriate index entries. The text “PEP number“ is generated; in the HTML output, this text is a hyperlink to an online copy of the specified PEP.  You can link to a specific section by saying :pep:`number#anchor`.

For example: PEP 8

:rfc:

A reference to an Internet Request for Comments.  This generates appropriate index entries. The text “RFC number“ is generated; in the HTML output, this text is a hyperlink to an online copy of the specified RFC.  You can link to a specific section by saying :rfc:`number#anchor`.

For example: RFC 2324

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

The documentation system provides some substitutions that are defined by default. They are set in the build configuration file.

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

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

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

|translation progress|

Replaced by the translation progress of the document. This substitution is intended for use by document translators as a marker for the translation progress of the document.

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:

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

NOTE:

To create table of contents for current document (.rst file), use the standard reST contents 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. [1]

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.) [2]

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.

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.

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

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

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

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

.. versionchanged:: version

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

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

.. versionremoved:: version

Similar to versionadded, but describes when the feature was removed. An explanation may be provided to inform the reader what to use instead, or why the feature was removed. Example:

.. versionremoved:: 4.0
   The :func:`spam` function is more flexible, and should be used instead.

Added in version 7.3.

.. 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 <https://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`

Added in version 0.5: The short form.

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

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

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

Added in version 0.6.

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

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.

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

: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

:force: (no value)

If given, minor errors on highlighting are ignored.

Added in version 2.1.

.. code-block:: [language]

.. sourcecode:: [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.  If it is not given, the setting of highlight directive will be used.  If not set, highlight_language will be used.  To display a code example inline within other text, rather than as a separate block, you can use the code role instead.

Changed in version 2.0: The language argument becomes optional.

options

:linenos: (no value)

Enable to generate line numbers for the code block:

.. code-block:: ruby
   :linenos:

   Some more Ruby code.

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

Added in version 1.3.

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

Added in version 1.1.

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

:caption: caption of code block (text)

Set a caption to the code block.

Added in version 1.3.

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

Added in version 1.3.

:class: class names (a list of class names separated by spaces)

The class name of the graph.

Added in version 1.4.

: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().  For example:

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

       some ruby code

Added in version 1.3.

Changed in version 3.5: Support automatic dedent.

:force: (no value)

If given, minor errors on highlighting are ignored.

Added in version 2.1.

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

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

When lines have been selected in any of the ways described above, the line numbers in emphasize-lines refer to those selected lines, counted consecutively starting at 1.

When specifying particular parts of a file to display, it can be useful to display the original line numbers. This can be done using the lineno-match option, which is however allowed only when the selection consists of contiguous lines.

You can prepend and/or append a line to the included code, using the prepend and append option, respectively.  This is useful e.g. for highlighting PHP code that doesn’t include the <?php/?> markers.

If you want to show the diff of the code, you can specify the old file by giving a diff option:

.. literalinclude:: example.py
   :diff: example.py.orig

This shows the diff between example.py and example.py.orig with unified diff format.

A force option can ignore minor errors on highlighting.

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.4: Added the class option.

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.

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

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

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

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

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.

.. index:: <entries>

This directive contains one or more index entries.  Each entry consists of a type and a value, separated by a colon.

For example:

.. index::
   single: execution; context
   pair: module; __main__
   pair: module; sys
   triple: module; search; path
   seealso: scope

The execution context
---------------------

...

This directive contains five entries, which will be converted to entries in the generated index which link to the exact location of the index statement (or, in case of offline media, the corresponding page number).

Since index directives generate cross-reference targets at their location in the source, it makes sense to put them before the thing they refer to – e.g. a heading, as in the example above.

The possible entry types are:

single

Creates a single index entry. Can be made a sub-entry by separating the sub-entry text with a semicolon (this notation is also used below to describe what entries are created). Examples:

.. index:: single: execution
           single: execution; context

• single: execution creates an index entry labelled execution.
• single: execution; context creates an sub-entry of execution labelled context.

pair

A shortcut to create two index entries. The pair of values must be separated by a semicolon. Example:

.. index:: pair: loop; statement

This would create two index entries; loop; statement and statement; loop.

triple

A shortcut to create three index entries. All three values must be separated by a semicolon. Example:

.. index:: triple: module; search; path

This would create three index entries; module; search path, search; path, module, and path; module search.

see

A shortcut to create an index entry that refers to another entry. Example:

.. index:: see: entry; other

This would create an index entry referring from entry to other (i.e. ‘entry’: See ‘other’).

seealso

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

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

These deprecated shortcuts all create two index entries. For example, module: hashlib creates the entries module; hashlib and hashlib; module.

Deprecated since version 1.0: These Python-specific entry types are deprecated.

Changed in version 7.1: Removal version set to Sphinx 9.0. Using these entry types will now emit warnings with the index category.

You can mark up “main” index entries by prefixing them with an exclamation mark.  The references to “main” entries are emphasized in the generated index.  For example, if two pages contain

.. index:: Python

and one page contains

.. index:: ! Python

then the backlink to the latter page is emphasized among the three backlinks.

For index directives containing only “single” entries, there is a shorthand notation:

.. index:: BNF, grammar, syntax, notation

This creates four index entries.

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

options

:name: a label for hyperlink (text)

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

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

Added in version 3.0.

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

Added in version 1.1.

.. 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 (latex or html) and draft) are supported.

The format and the name of the current builder (html, latex or text) are always set as a tag [4].  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 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.

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

Use reStructuredText tables, i.e. either

• grid table syntax (ref),
• simple table syntax (ref),
• csv-table syntax,
• or list-table syntax.

The table directive serves as optional wrapper of the grid and simple syntaxes.

They work fine in HTML output, but rendering tables to LaTeX is complex. Check the latex_table_style.

Changed in version 1.6: Merged cells (multi-row, multi-column, both) from grid tables containing complex contents such as multiple paragraphs, blockquotes, lists, literal blocks, will render correctly to LaTeX output.

.. tabularcolumns:: column spec

This directive influences only the LaTeX output for the next table in source.  The mandatory argument is a column specification (known as an “alignment preamble” in LaTeX idiom).  Please refer to a LaTeX documentation, such as the wiki page, for basics of such a column specification.

Added in version 0.3.

NOTE:

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

Sphinx will render tables with more than 30 rows with longtable. Besides the l, r, c and p{width} column specifiers, one can also use \X{a}{b} (new in version 1.5) which configures the column width to be a fraction a/b of the total line width and \Y{f} (new in version 1.6) where f is a decimal: for example \Y{0.2} means that the column will occupy 0.2 times the line width.

When this directive is used for a table with at most 30 rows, Sphinx will render it with tabulary.  One can then use specific column types L (left), R (right), C (centered) and J (justified).  They have the effect of a p{width} (i.e. each cell is a LaTeX \parbox) with the specified internal text alignment and an automatically computed width.

WARNING:

• Cells that contain list-like elements such as object descriptions, blockquotes or any kind of lists are not compatible with the LRCJ column types.  The column type must then be some p{width} with an explicit width (or \X{a}{b} or \Y{f}).
• Literal blocks do not work with tabulary at all.  Sphinx will fall back to tabular or longtable environments and generate a suitable column specification.

In absence of the tabularcolumns directive, and for a table with at most 30 rows and no problematic cells as described in the above warning, Sphinx uses tabulary and the J column-type for every column.

Changed in version 1.6: Formerly, the L column-type was used (text is flushed-left).  To revert to this, include \newcolumntype{T}{L} in the LaTeX preamble, as in fact Sphinx uses T and sets it by default to be an alias of J.

HINT:

A frequent issue with tabulary is that columns with little contents appear to be “squeezed”.  One can add to the LaTeX preamble for example \setlength{\tymin}{40pt} to ensure a minimal column width of 40pt, the tabulary default of 10pt being too small.

HINT:

To force usage of the LaTeX longtable environment pass longtable as a :class: option to table, csv-table, or list-table.  Use rst-class for other tables.

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

.. math::

Directive for displayed math (math that takes the whole line for itself).

The directive supports multiple equations, which should be separated by a blank line:

.. math::

   (a + b)^2 = a^2 + 2ab + b^2

   (a - b)^2 = a^2 - 2ab + b^2

In addition, each single equation is set within a split environment, which means that you can have multiple aligned lines in an equation, aligned at & and separated by \\:

.. math::

   (a + b)^2  &=  (a + b)(a + b) \\
              &=  a^2 + 2ab + b^2

For more details, look into the documentation of the AmSMath LaTeX package.

When the math is only one line of text, it can also be given as a directive argument:

.. math:: (a + b)^2 = a^2 + 2ab + b^2

Normally, equations are not numbered.  If you want your equation to get a number, use the label option.  When given, it selects an internal label for the equation, by which it can be cross-referenced, and causes an equation number to be issued.  See 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:

Math support for HTML outputs in Sphinx

Rendering options for math with HTML builders.

latex_engine

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

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:

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

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:

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:

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.

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

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

Added in version 3.0.

See Domains.

See The Python Domain.

See The C Domain.

See The C++ Domain.

See The Standard Domain.

See The JavaScript Domain.

See The reStructuredText Domain.

See The Mathematics Domain.

See Domains.

Markdown is a lightweight markup language with a simplistic plain text formatting syntax.  It exists in many syntactically different flavors.  To support Markdown-based documentation, Sphinx can use MyST-Parser. MyST-Parser is a Docutils bridge to markdown-it-py, a Python package for parsing the CommonMark Markdown flavor.

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.

Cross-references are generated by many semantic interpreted text roles. Basically, you only need to write :role:`target`, and a link will be created to the item named target of the type indicated by role.  The link’s text will be the same as target.

There are some additional facilities, however, that make cross-referencing roles more versatile:

• You may supply an explicit title and reference target, like in reST direct hyperlinks: :role:`title <target>` will refer to target, but the link text will be title.
• If you prefix the content with !, no reference/hyperlink will be created.

• If you prefix the content with ~, the link text will only be the last component of the target.  For example, :py:meth:`~Queue.Queue.get` will refer to Queue.Queue.get but only display get as the link text.  This does not work with all cross-reference roles, but is domain specific.

  In HTML output, the link’s title attribute (that is e.g. shown as a tool-tip on mouse-hover) will always be the full target name.

:any:

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

These roles are described with their respective domains:

• Python
• C
• C++
• JavaScript
• ReST

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

Added in version 0.6.

There is also a way to directly link to documents:

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

Added in version 0.6.

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

Added in version 1.3.

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

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

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

:envvar:

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

:token:

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

:keyword:

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

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

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

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 can be added to the configuration directory to adjust Docutils configuration if not otherwise overridden or set by Sphinx.

The configuration file is executed as Python code at build time (using importlib.import_module(), and with the current directory set to its containing directory), and therefore can execute arbitrarily complex code. Sphinx then reads simple names from the file’s namespace as its configuration.

Important points to note:

• If not otherwise documented, values must be strings, and their default is the empty string.
• The term “fully-qualified name” refers to a string that names an importable Python object inside a module; for example, the FQN "sphinx.builders.Builder" means the Builder class in the sphinx.builders module.
• Remember that document names use / as the path separator and don’t contain the file name extension.
• Since 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.

project

The documented project’s name.

author

The author name(s) of the document.  The default value is 'unknown'.

copyright

A copyright statement in the style '2008, Author Name'.

Changed in version 7.1: The value may now be a sequence of copyright statements in the above form, which will be displayed each to their own line.

project_copyright

An alias of copyright.

Added in version 3.5.

version

The major project version, used as the replacement for |version|.  For example, for the Python documentation, this may be something like 2.6.

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.

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

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

source_encoding

The encoding of all reST source files.  The recommended encoding, and the default value, is 'utf-8-sig'.

Added in version 0.5: Previously, Sphinx accepted only UTF-8 encoded sources.

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.

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

master_doc

Same as root_doc.

Changed in version 4.0: Renamed master_doc to root_doc.

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.

exclude_patterns

A list of glob-style patterns [1] that should be excluded when looking for source files. They are matched against the source file names relative to the source directory, using slashes as directory separators on all platforms.

Example patterns:

• 'library/xml.rst' – ignores the library/xml.rst file
• 'library/xml' – ignores the library/xml directory
• 'library/xml*' – ignores all files and directories starting with library/xml
• '**/.svn' – ignores all .svn directories

exclude_patterns is also consulted when looking for static files in html_static_path and html_extra_path.

Added in version 1.0.

include_patterns

A list of glob-style patterns [1] that are used to find source files. They are matched against the source file names relative to the source directory, using slashes as directory separators on all platforms. The default is **, meaning that all files are recursively included from the source directory. exclude_patterns has priority over include_patterns.

Example patterns:

• '**' – all files in the source directory and subdirectories, recursively
• 'library/xml' – just the library/xml directory
• 'library/xml*' – all files and directories starting with library/xml
• '**/doc' – all doc directories (this might be useful if documentation is co-located with source files)

Added in version 5.1.

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.

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

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

Added in version 0.6.

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

Added in version 1.0.

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

Added in version 1.0.

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.

Added in version 0.4.

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.

Added in version 0.5.

show_warning_types

If True, the type of each warning is added as a suffix to the warning message, e.g., WARNING: [...] [index] or WARNING: [...] [toc.circular]. The default is False.

Added in version 7.3.0.

suppress_warnings

A list of warning types to suppress arbitrary warning messages.

Sphinx core supports following warning types:

• app.add_node
• app.add_directive
• app.add_role
• app.add_generic_role
• app.add_source_parser
• config.cache
• download.not_readable
• epub.unknown_project_files
• epub.duplicated_toc_entry
• i18n.inconsistent_references
• index
• image.not_readable
• ref.term
• ref.ref
• ref.numref
• ref.keyword
• ref.option
• ref.citation
• ref.footnote
• ref.doc
• ref.python
• misc.highlighting_failure
• toc.circular
• toc.excluded
• toc.not_readable
• toc.secnum

Extensions can also define their own warning types. Those defined by the first-party sphinx.ext extensions are:

• autodoc
• autodoc.import_object
• autosectionlabel.<document name>
• autosummary
• intersphinx.external

You can choose from these types.  You can also give only the first component to exclude all warnings attached to it.

Added 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.<document name>

Changed in version 3.3.0: Added epub.duplicated_toc_entry

Changed in version 4.3: Added toc.excluded and toc.not_readable

Added in version 4.5: Added i18n.inconsistent_references

Added in version 7.1: Added index warning type.

Added in version 7.3: Added config.cache warning type.

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.

Added in version 1.0.

Changed in version 1.4: also accepts micro version string

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 Sphinx Extensions API for how to do that).

Added in version 1.3.

manpages_url

A URL to cross-reference manpage roles. 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.

Added in version 1.7.

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.

Added in version 1.0.

nitpick_ignore

A set or list of (type, target) tuples (by default empty) that should be ignored when generating warnings in “nitpicky mode”.  Note that type should include the domain name if present.  Example entries would be ('py:func', 'int') or ('envvar', 'LD_LIBRARY_PATH').

Added in version 1.1.

Changed in version 6.2: Changed allowable container types to a set, list, or tuple

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

Added in version 4.1.

Changed in version 6.2: Changed allowable container types to a set, list, or tuple

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.

Added in version 1.3.

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

Added in version 1.3.

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…

Added in version 1.3.

Changed in version 1.7: The LaTeX builder obeys this setting (if numfig is set to True).

smartquotes

If true, the Docutils Smart Quotes transform, originally based on SmartyPants (limited to English) and currently applying to many languages, will be used to convert quotes and dashes to typographically correct entities.  Default: True.

Added 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 file located in the configuration directory (or a global ~/.docutils file) is obeyed unconditionally if it deactivates smart quotes via the corresponding Docutils option.  But if it activates them, then smartquotes does prevail.

smartquotes_action

This string customizes the Smart Quotes transform.  See the file smartquotes.py at the Docutils repository for details.  The default 'qDe' educates normal quote characters ", ', em- and en-Dashes ---, --, and ellipses ....

Added in version 1.6.6.

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.

Added in version 1.6.6.

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

Added in version 2.3.

tls_verify

If true, Sphinx verifies server certifications.  Default is True.

Added in version 1.5.

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.

Added in version 1.5.

TIP:

Sphinx uses requests as a HTTP library internally. Therefore, Sphinx refers a certification file on the directory pointed REQUESTS_CA_BUNDLE environment variable if tls_cacerts not set.

today

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

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.

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

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.

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}

Added in version 1.3.

Changed in version 3.5: Allow to configure highlight options for multiple languages

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.

maximum_signature_line_length

If a signature’s length in characters exceeds the number set, each parameter within the signature will be displayed on an individual logical line.

When None (the default), there is no maximum length and the entire signature will be displayed on a single logical line.

A ‘logical line’ is similar to a hard line break—builders or themes may choose to ‘soft wrap’ a single logical line, and this setting does not affect that behaviour.

Domains may provide options to suppress any hard wrapping on an individual object directive, such as seen in the C, C++, and Python domains (e.g. py:function:single-line-parameter-list).

Added in version 7.1.

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.

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.

toc_object_entries

Create table of contents entries for domain objects (e.g. functions, classes, attributes, etc.). Default is True.

toc_object_entries_show_parents

A string that determines how domain objects (e.g. functions, classes, attributes, etc.) are displayed in their table of contents entry.

Use domain to allow the domain to determine the appropriate number of parents to show. For example, the Python domain would show Class.method() and function(), leaving out the module. level of parents. This is the default setting.

Use hide to only show the name of the element without any parents (i.e. method()).

Use all to show the fully-qualified name for the object (i.e. module.Class.method()),  displaying all parents.

Added in version 5.2.

show_authors

A boolean that decides whether codeauthor and sectionauthor directives produce any output in the built files.

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

Added in version 0.6.

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.

Added in version 0.6.

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.

Added in version 1.0.

Changed in version 1.1: Now also removes <BLANKLINE>.

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.

Added in version 3.0.

option_emphasise_placeholders

Default is False. When enabled, emphasise placeholders in option directives. To display literal braces, escape with a backslash (\{). For example, option_emphasise_placeholders=True and .. option:: -foption={TYPE} would render with TYPE emphasised.

Added in version 5.1.

These options influence Sphinx’s Native Language Support.  See the documentation on Internationalization for details.

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

Added in version 0.5.

Changed in version 1.4: Support figure substitution

Changed in version 5.0.

Currently supported languages by Sphinx are:

• ar – Arabic
• bg – Bulgarian
• bn – Bengali
• ca – Catalan
• cak – Kaqchikel
• cs – Czech
• cy – Welsh
• da – Danish
• de – German
• el – Greek
• en – English (default)
• eo – Esperanto
• es – Spanish
• et – Estonian
• eu – Basque
• fa – Iranian
• fi – Finnish
• fr – French
• he – Hebrew
• hi – Hindi
• hi_IN – Hindi (India)
• hr – Croatian
• hu – Hungarian
• id – Indonesian
• it – Italian
• ja – Japanese
• ko – Korean
• lt – Lithuanian
• lv – Latvian
• mk – Macedonian
• nb_NO – Norwegian Bokmal
• ne – Nepali
• nl – Dutch
• pl – Polish
• pt – Portuguese
• pt_BR – Brazilian Portuguese
• pt_PT – European Portuguese
• ro – Romanian
• ru – Russian
• si – Sinhala
• sk – Slovak
• sl – Slovenian
• sq – Albanian
• sr – Serbian
• sr@latin – Serbian (Latin)
• sr_RS – Serbian (Cyrillic)
• sv – Swedish
• ta – Tamil
• te – Telugu
• tr – Turkish
• uk_UA – Ukrainian
• ur – Urdu
• vi – Vietnamese
• zh_CN – Simplified Chinese
• zh_TW – Traditional Chinese

locale_dirs

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

gettext_allow_fuzzy_translations

If true, “fuzzy” messages in the message catalogs are used for translation. The default is False.

Added in version 4.3.

gettext_compact

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

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.

Added in version 1.3.

gettext_location

If true, Sphinx generates location information for messages in message catalogs.

The default is True.

Added in version 1.3.

gettext_auto_build

If true, Sphinx builds mo file for each translation catalog files.

The default is True.

Added in version 1.3.

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

Added in version 1.3.

Changed in version 4.0: The alt text for image is translated by default.

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.

Added in version 1.4.

Changed in version 1.5: Added {path} and {basename} tokens.

Changed in version 3.2: Added {docpath} token.

translation_progress_classes

Control which, if any, classes are added to indicate translation progress. This setting would likely only be used by translators of documentation, in order to quickly indicate translated and untranslated content.

• True: add translated and untranslated classes to all nodes with translatable content.
• translated: only add the translated class.
• untranslated: only add the untranslated class.
• False: do not add any classes to indicate translation progress.

Defaults to False.

Added in version 7.1.

These options influence Math notations.

math_number_all

Set this option to True if you want all displayed math to be numbered. The default is False.

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.

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.

Added in version 1.7.

These options influence HTML as well as HTML Help output, and other builders that use Sphinx’s HTMLWriter class.

html_theme

The “theme” that the HTML output should use.  See the section about theming.  The default is 'alabaster'.

Added in version 0.6.

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.

Added in version 0.6.

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.

Added in version 0.6.

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.

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

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.

Added in version 0.4.

html_baseurl

The base URL which points to the root of the HTML documentation.  It is used to indicate the location of document using The Canonical Link Relation. Default: ''.

Added in version 1.8.

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)

Added in version 3.2.

Changed in version 4.0: It defaults to 'inline'.

Deprecated since version 4.0.

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.

Added in version 0.5.

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.

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

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.

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

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 at an earlier or lazier step.  For more information, refer Sphinx.add_css_file().

Added in version 1.8.

Changed in version 3.5: Support priority attribute

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 JavaScript file at an earlier or lazier step.  For more information, refer Sphinx.add_js_file().

Added in version 1.8.

Changed in version 3.5: Support priority attribute

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.

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.

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

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

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.

html_permalinks

Add link anchors for each heading and description environment. Default: True.

Added in version 3.5.

html_permalinks_icon

Text for link anchors for each heading and description environment. HTML entities and Unicode are allowed.  Default: a paragraph sign; ¶

Added in version 3.5.

html_sidebars

Custom sidebar templates, must be a dictionary that maps document names to template names.

The keys can contain glob-style patterns [1], in which case all matching documents will get the specified sidebars.  (A warning is emitted when a more than one glob-style pattern matches for any document.)

The values can be either lists or single strings.

• If a value is a list, it specifies the complete list of sidebar templates to include.  If all or some of the default sidebars are to be included, they must be put into this list as well.

  The default sidebars (for documents that don’t match any pattern) are defined by theme itself.  Builtin themes are using these templates by default: ['localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'].

• If a value is a single string, it specifies a custom sidebar to be added between the 'sourcelink.html' and 'searchbox.html' entries.  This is for compatibility with Sphinx versions before 1.0.

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

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

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.

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

Added in version 1.0.

html_use_index

If true, add an index to the HTML documents.  Default is True.

Added in version 0.4.

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.

Added in version 0.4.

html_copy_source

If true, the reST sources are included in the HTML build as _sources/name.  The default is True.

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.

Added in version 0.6.

html_sourcelink_suffix

Suffix to be appended to source links (see html_show_sourcelink), unless they have this suffix already.  Default is '.txt'.

Added in version 1.5.

html_use_opensearch

If nonempty, an OpenSearch description file will be output, and all pages will contain a <link> tag referring to it.  Since OpenSearch doesn’t support relative URLs for its search page location, the value of this option must be the base URL from which these documents are served (without trailing slash), e.g. "https://docs.python.org".  The default is ''.

html_file_suffix

This is the file name suffix for generated HTML files, if set to a str value.  If left to the default None, the suffix will be ".html".

Added in version 0.4.

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

Added in version 0.6.

html_show_copyright

If true, “(C) Copyright …” is shown in the HTML footer. Default is True.

Added in version 1.0.

html_show_search_summary

If true, the text around the keyword is shown as summary of each search result. Default is True.

Added in version 4.5.

html_show_sphinx

If true, “Created using Sphinx” is shown in the HTML footer.  Default is True.

Added in version 0.4.

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.

Added in version 1.0.

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.

Added in version 1.0.

html_secnumber_suffix

Suffix for section numbers.  Default: ". ".  Set to " " to suppress the final dot on section numbers.

Added in version 1.0.

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 (en)
  • PyStemmer (all languages)

Added in version 1.1: With support for en and ja.

Changed in version 1.3: Added additional languages.

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

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

is the encoding for the MeCab algorithm.

dict

is the dictionary to use for the MeCab algorithm.

lib

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

is the user dictionary file path for Janome.

user_dic_enc

is the encoding for the user dictionary file specified by user_dic option. Default is ‘utf8’.

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

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.

The scorer must implement the following interface, and may optionally define the score() function for more granular control.

const Scorer = {
    // Implement the following function to further tweak the score for each result
    score: result => {
      const [docName, title, anchor, descr, score, filename] = result

      // ... calculate a new score ...
      return score
    },

    // query matches the full name of an object
    objNameMatch: 11,
    // or matches in the last dotted part of the object name
    objPartialMatch: 6,
    // Additive scores depending on the priority of the object
    objPrio: {
      0: 15, // used to be importantResults
      1: 5, // used to be objectResults
      2: -5, // used to be unimportantResults
    },
    //  Used when the priority is not in the mapping.
    objPrioDefault: 0,

    // query found in title
    title: 15,
    partialTitle: 7,

    // query found in terms
    term: 5,
    partialTerm: 2,
};

Added in version 1.2.

html_scaled_image_link

If true, image itself links to the original image if it doesn’t have ‘target’ option or scale related options: ‘scale’, ‘width’, ‘height’. The default is True.

Document authors can disable this feature manually with giving no-scaled-link class to the image:

.. image:: sphinx.png
   :scale: 50%
   :class: no-scaled-link

Added in version 1.3.

Changed in version 3.0: It is disabled for images having no-scaled-link class

html_math_renderer

The name of math_renderer extension for HTML output.  The default is 'mathjax'.

Added in version 1.8.

html_experimental_html5_writer

Output is processed with HTML5 writer.  Default is False.

Added in version 1.6.

Deprecated since version 2.0.

html4_writer

Output is processed with HTML4 writer.  Default is False.

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.

htmlhelp_basename

Output file base name for HTML help builder.  Default is 'pydoc'.

htmlhelp_file_suffix

This is the file name suffix for generated HTML help files.  The default is ".html".

Added in version 2.0.

htmlhelp_link_suffix

Suffix for generated links to HTML files.  The default is ".html".

Added in version 2.0.

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

applehelp_bundle_name

The basename for the Apple Help Book.  Defaults to the project name.

applehelp_bundle_id

The bundle ID for the help book bundle.

WARNING:

You must set this value in order to generate Apple Help.

applehelp_dev_region

The development region.  Defaults to 'en-us', which is Apple’s recommended setting.

applehelp_bundle_version

The bundle version (as a string).  Defaults to '1'.

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.

applehelp_kb_product

The product tag for use with applehelp_kb_url.  Defaults to '<project>-<release>'.

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.

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.

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.

applehelp_min_term_length

Controls the minimum term length for the help indexer.  Defaults to None, which means the default will be used.

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

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

applehelp_title

Specifies the help book title.  Defaults to '<project> Help'.

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.

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.

applehelp_indexer_path

The path to the hiutil program.  Defaults to '/usr/bin/hiutil'.

applehelp_codesign_path

The path to the codesign program.  Defaults to '/usr/bin/codesign'.

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.

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.

epub_basename

The basename for the epub file.  It defaults to the project name.

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.

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.

Added in version 1.2.

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.

epub_description

The description of the document. The default value is 'unknown'.

Added in version 1.4.

Changed in version 1.5: Renamed from epub3_description

epub_author

The author of the document.  This is put in the Dublin Core metadata.  It defaults to the author option.

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

Added in version 1.4.

Changed in version 1.5: Renamed from epub3_contributor

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.

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.

epub_copyright

The copyright of the document.  It defaults to the copyright option but can be set independently for epub creation.

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

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

epub_uid

A unique identifier for the document.  This is put in the Dublin Core metadata.  You may use a XML’s Name format string.  You can’t use hyphen, period, numbers as a first character.  The default value is 'unknown'.

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

Added in version 1.1.

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.

Added in version 1.8.

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 https://idpf.org/epub for details. If possible, default entries for the cover and toc types are automatically inserted. However, the types can be explicitly overwritten if the default entries are not appropriate. Example:

epub_guide = (('cover', 'cover.html', 'Cover Page'),)

The default value is ().

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

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

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

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.

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.

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

Added in version 1.2.

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.

Added in version 1.2.

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.

Added in version 1.2.

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.

Added in version 1.2.

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.

Added in version 1.2.

epub_writing_mode

It specifies writing direction. It can accept 'horizontal' (default) and 'vertical'

epub_writing_mode	'horizontal'	'vertical'
writing-mode [2]	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.

[2]

https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode

These options influence LaTeX output.

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.

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.

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

Added in version 0.3: The 6th item toctree_only.  Tuples with 5 items are still accepted.

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.

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

Added in version 1.4.

latex_appendices

A list of document names to append as an appendix to all manuals.

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.

Added in version 1.0.

latex_show_pagerefs

If true, add page references after internal references.  This is very useful for printed copies of the manual.  Default is False.

Added in version 1.0.

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

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

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.

Added in version 1.6.

latex_table_style

A list of styling classes (strings).  Currently supported:

• 'booktabs': no vertical lines, and only 2 or 3 horizontal lines (the latter if there is a header), using the booktabs package.
• 'borderless': no lines whatsoever.

• 'colorrows': the table rows are rendered with alternating background colours.  The interface to customize them is via dedicated keys of The sphinxsetup configuration setting.

  IMPORTANT:

  With the 'colorrows' style, the \rowcolors LaTeX command becomes a no-op (this command has limitations and has never correctly supported all types of tables Sphinx produces in LaTeX).  Please update your project to use instead the latex table color configuration keys.

Default: ['booktabs', 'colorrows']

Added in version 5.3.0.

Changed in version 6.0.0: Modify default from [] to ['booktabs', 'colorrows'].

Each table can override the global style via :class: option, or .. rst-class:: for no-directive tables (cf.  Tables). Currently recognized classes are booktabs, borderless, standard, colorrows, nocolorrows.  The latter two can be combined with any of the first three.  The standard class produces tables with both horizontal and vertical lines (as has been the default so far with Sphinx).

A single-row multi-column merged cell will obey the row colour, if it is set.  See also TableMergeColor{Header,Odd,Even} in the The sphinxsetup configuration setting section.

NOTE:

• It is hard-coded in LaTeX that a single cell will obey the row colour even if there is a column colour set via \columncolor from a column specification (see tabularcolumns).  Sphinx provides \sphinxnorowcolor which can be used like this:

  >{\columncolor{blue}\sphinxnorowcolor}

  in a table column specification.

• Sphinx also provides \sphinxcolorblend which however requires the xcolor package.  Here is an example:

  >{\sphinxcolorblend{!95!red}}

  It means that in this column, the row colours will be slightly tinted by red; refer to xcolor documentation for more on the syntax of its \blendcolors command (a \blendcolors in place of \sphinxcolorblend would modify colours of the cell contents, not of the cell background colour panel…).  You can find an example of usage in the Deprecated APIs section of this document in PDF format.

  HINT:

  If you want to use a special colour for the contents of the cells of a given column use >{\noindent\color{<color>}}, possibly in addition to the above.

• Multi-row merged cells, whether single column or multi-column currently ignore any set column, row, or cell colour.
• It is possible for a simple cell to set a custom colour via the raw directive and the \cellcolor LaTeX command used anywhere in the cell contents.  This currently is without effect in a merged cell, whatever its kind.

HINT:

In a document not using 'booktabs' globally, it is possible to style an individual table via the booktabs class, but it will be necessary to add r'\usepackage{booktabs}' to the LaTeX preamble.

On the other hand one can use colorrows class for individual tables with no extra package (as Sphinx since 5.3.0 always loads colortbl).

latex_use_xindy

If True, the PDF build from the LaTeX files created by Sphinx will use xindy (doc) 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.

Added in version 1.8.

latex_elements

Added in version 0.5.

Its documentation has moved to LaTeX customization.

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

Added in version 1.0.

Changed in version 1.5: In Japanese docs (language is 'ja'), by default 'jreport' is used for 'howto' and 'jsbook' for 'manual'.

latex_additional_files

A list of file names, relative to the configuration directory, to copy to the build directory when building LaTeX output.  This is useful to copy files that Sphinx doesn’t copy automatically, e.g. if they are referenced in custom LaTeX added in latex_elements.  Image files that are referenced in source files (e.g. via .. image::) are copied automatically.

You have to make sure yourself that the filenames don’t collide with those of any automatically copied files.

ATTENTION:

Filenames with extension .tex will automatically be handed over to the PDF build process triggered by sphinx-build -M latexpdf or by make latexpdf.  If the file was added only to be \input{} from a modified preamble, you must add a further suffix such as .txt to the filename and adjust accordingly the \input{} command added to the LaTeX document preamble.

Added in version 0.6.

Changed in version 1.2: This overrides the files which is provided from Sphinx such as sphinx.sty.

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

Added in version 3.0.

latex_theme_options

A dictionary of options that influence the look and feel of the selected theme.

Added in version 3.1.

latex_theme_path

A list of paths that contain custom LaTeX themes as subdirectories.  Relative paths are taken as relative to the configuration directory.

Added in version 3.0.

These options influence text output.

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

Added in version 1.1.

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 '*=-~"+`'.

Added in version 1.1.

text_add_secnumbers

A boolean that decides whether section numbers are included in text output. Default is True.

Added in version 1.7.

text_secnumber_suffix

Suffix for section numbers in text output.  Default: ". ". Set to " " to suppress the final dot on section numbers.

Added in version 1.7.

These options influence manual page output.

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.

Added in version 1.0.

man_show_urls

If true, add URL addresses after links.  Default is False.

Added in version 1.1.

man_make_section_directory

If true, make a section directory on build man page.  Default is True.

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

These options influence Texinfo output.

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.

Added in version 1.1.

texinfo_appendices

A list of document names to append as an appendix to all manuals.

Added in version 1.1.

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.

Added in version 1.1.

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

Added in version 1.1.

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.

Added in version 1.2.

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'

Added in version 1.1.

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.

Added in version 4.4.

These options influence qthelp output.  As this builder derives from the HTML builder, the HTML options also apply where appropriate.

qthelp_basename

The basename for the qthelp file.  It defaults to the project name.

qthelp_namespace

The namespace for the qthelp file.  It defaults to org.sphinx.<project_name>.<project_version>.

qthelp_theme

The HTML theme for the qthelp output. This defaults to 'nonav'.

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.

linkcheck_ignore

A list of regular expressions that match URIs that should not be checked when doing a linkcheck build.  Example:

linkcheck_ignore = [r'https://localhost:\d+/']

Added in version 1.1.

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.

Added in version 4.1.

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

Added in version 3.1.

linkcheck_retries

The number of times the linkcheck builder will attempt to check a URL before declaring it broken. Defaults to 1 attempt.

Added in version 1.4.

linkcheck_timeout

The duration, in seconds, that the linkcheck builder will wait for a response after each hyperlink request.  Defaults to 30 seconds.

Added in version 1.1.

linkcheck_workers

The number of worker threads to use when checking links.  Default is 5 threads.

Added in version 1.1.

linkcheck_anchors

If true, check the validity of #anchors in links. Since this requires downloading the whole document, it’s considerably slower when enabled. Default is True.

Added in version 1.2.

linkcheck_anchors_ignore

A list of regular expressions that match anchors Sphinx should skip when checking the validity of anchors in links. This allows skipping anchors that a website’s JavaScript adds to control dynamic pages or when triggering an internal REST request. Default is ["^!"].

TIP:

Use linkcheck_anchors_ignore_for_url to check a URL, but skip verifying that the anchors exist.

NOTE:

If you want to ignore anchors of a specific page or of pages that match a specific pattern (but still check occurrences of the same page(s) that don’t have anchors), use linkcheck_ignore instead, for example as follows:

linkcheck_ignore = [
   'https://www.sphinx-doc.org/en/1.7/intro.html#',
]

Added in version 1.5.

linkcheck_anchors_ignore_for_url

A list or tuple of regular expressions matching URLs for which Sphinx should not check the validity of anchors. This allows skipping anchor checks on a per-page basis while still checking the validity of the page itself. Default is an empty tuple ().

Added in version 7.1.

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 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(...)),
]

Added in version 2.3.

linkcheck_rate_limit_timeout

The linkcheck builder may issue a large number of requests to the same site over a short period of time. This setting controls the builder behavior when servers indicate that requests are rate-limited.

If a server indicates when to retry (using the Retry-After header), linkcheck always follows the server indication.

Otherwise, linkcheck waits for a minute before to retry and keeps doubling the wait time between attempts until it succeeds or exceeds the linkcheck_rate_limit_timeout. By default, the timeout is 300 seconds and custom timeouts should be given in seconds.

Added in version 3.4.

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/.*']

Added in version 4.4.

linkcheck_allow_unauthorized

When a webserver responds with an HTTP 401 (unauthorized) response, the current default behaviour of Sphinx is to treat the link as “working”.  To change that behaviour, set this option to False.

The default value for this option will be changed in Sphinx 8.0; from that version onwards, HTTP 401 responses to checked hyperlinks will be treated as “broken” by default.

Added in version 7.3.

linkcheck_report_timeouts_as_broken

When an HTTP response is not received from a webserver before the configured linkcheck_timeout expires, the current default behaviour of Sphinx is to treat the link as ‘broken’. To report timeouts using a distinct report code of timeout, set linkcheck_report_timeouts_as_broken to False.

From Sphinx 8.0 onwards, timeouts that occur while checking hyperlinks will be reported using the new ‘timeout’ status code.

Added in version 7.3.

xml_pretty

If true, pretty-print the XML.  Default is True.

Added in version 1.2.

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.

Added in version 3.0.

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.

Added in version 3.0.

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

Added in version 4.0.3.

c_maximum_signature_line_length

If a signature’s length in characters exceeds the number set, each parameter will be displayed on an individual logical line. This is a domain-specific setting, overriding maximum_signature_line_length.

Added in version 7.1.

cpp_index_common_prefix

A list of prefixes that will be ignored when sorting C++ objects in the global index.  For example ['awesome_lib::'].

Added in version 1.5.

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.

Added in version 1.5.

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.

Added in version 1.5.

cpp_maximum_signature_line_length

If a signature’s length in characters exceeds the number set, each parameter will be displayed on an individual logical line. This is a domain-specific setting, overriding maximum_signature_line_length.

Added in version 7.1.

python_display_short_literal_types

This value controls how Literal types are displayed. The setting is a boolean, default False.

The examples below use the following py:function directive:

.. py:function:: serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None

When False, Literal types display as per standard Python syntax, i.e.:

serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None

When True, Literal types display with a short, PEP 604-inspired syntax, i.e.:

serve_food(item: "egg" | "spam" | "lobster thermidor") -> None

Added in version 6.2.

python_use_unqualified_type_names

If true, suppress the module name of the python reference if it can be resolved.  The default is False.

Added in version 4.0.

NOTE:

This configuration is still in experimental

python_maximum_signature_line_length

If a signature’s length in characters exceeds the number set, each argument or type parameter will be displayed on an individual logical line. This is a domain-specific setting, overriding maximum_signature_line_length.

For the Python domain, the signature length depends on whether the type parameters or the list of arguments are being formatted. For the former, the signature length ignores the length of the arguments list; for the latter, the signature length ignores the length of the type parameters list.

For instance, with python_maximum_signature_line_length = 20, only the list of type parameters will be wrapped while the arguments list will be rendered on a single line

.. py:function:: add[T: VERY_LONG_SUPER_TYPE, U: VERY_LONG_SUPER_TYPE](a: T, b: U)

Added in version 7.1.

javascript_maximum_signature_line_length

If a signature’s length in characters exceeds the number set, each parameter will be displayed on an individual logical line. This is a domain-specific setting, overriding maximum_signature_line_length.

Added in version 7.1.

# test documentation build configuration file, created by
# sphinx-quickstart on Sun Jun 26 00:00:43 2016.
#
# This file is executed through importlib.import_module with 
# the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

# -- General configuration ------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'

# The encoding of source files.
#
# source_encoding = 'utf-8-sig'

# The master toctree document.
root_doc = 'index'

# General information about the project.
project = 'test'
copyright = '2016, test'
author = 'test'

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = 'test'
# The full version, including alpha/beta/rc tags.
release = 'test'

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None

# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#
# today = ''
#
# Else, today_fmt is used as the format for a strftime call.
#
# today_fmt = '%B %d, %Y'

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# These patterns also affect html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# The reST default role (used for this markup: `text`) to use for all
# documents.
#
# default_role = None

# If true, '()' will be appended to :func: etc. cross-reference text.
#
# add_function_parentheses = True

# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#
# add_module_names = True

# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#
# show_authors = False

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []

# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False

# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False


# -- Options for HTML output ----------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'

# Theme options are theme-specific and customize the look and feel of a theme
# further.  For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}

# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = []

# The name for this set of Sphinx documents.
# "<project> v<release> documentation" by default.
#
# html_title = 'test vtest'

# A shorter title for the navigation bar.  Default is the same as html_title.
#
# html_short_title = None

# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#
# html_logo = None

# The name of an image file (relative to this directory) to use as a favicon of
# the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#
# html_favicon = None

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#
# html_extra_path = []

# If not None, a 'Last updated on:' timestamp is inserted at every page
# bottom, using the given strftime format.
# The empty string is equivalent to '%b %d, %Y'.
#
# html_last_updated_fmt = None

# Custom sidebar templates, maps document names to template names.
#
# html_sidebars = {}

# Additional templates that should be rendered to pages, maps page names to
# template names.
#
# html_additional_pages = {}

# If false, no module index is generated.
#
# html_domain_indices = True

# If false, no index is generated.
#
# html_use_index = True

# If true, the index is split into individual pages for each letter.
#
# html_split_index = False

# If true, links to the reST sources are added to the pages.
#
# html_show_sourcelink = True

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#
# html_show_sphinx = True

# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#
# html_show_copyright = True

# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it.  The value of this option must be the
# base URL from which the finished HTML is served.
#
# html_use_opensearch = ''

# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None

# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
#
# html_search_language = 'en'

# A dictionary with options for the search language support, empty by default.
# 'ja' uses this config value.
# 'zh' user can custom change `jieba` dictionary path.
#
# html_search_options = {'type': 'default'}

# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#
# html_search_scorer = 'scorer.js'

# Output file base name for HTML help builder.
htmlhelp_basename = 'testdoc'

# -- Options for LaTeX output ---------------------------------------------

latex_elements = {
    # The paper size ('letterpaper' or 'a4paper').
    #
    # 'papersize': 'letterpaper',

    # The font size ('10pt', '11pt' or '12pt').
    #
    # 'pointsize': '10pt',

    # Additional stuff for the LaTeX preamble.
    #
    # 'preamble': '',

    # Latex figure (float) alignment
    #
    # 'figure_align': 'htbp',
}

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
#  author, documentclass [howto, manual, or own class]).
latex_documents = [
    (root_doc, 'test.tex', 'test Documentation',
     'test', 'manual'),
]

# The name of an image file (relative to this directory) to place at the top of
# the title page.
#
# latex_logo = None

# If true, show page references after internal links.
#
# latex_show_pagerefs = False

# If true, show URL addresses after external links.
#
# latex_show_urls = False

# Documents to append as an appendix to all manuals.
#
# latex_appendices = []

# If false, no module index is generated.
#
# latex_domain_indices = True


# -- Options for manual page output ---------------------------------------

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
    (root_doc, 'test', 'test Documentation',
     [author], 1)
]

# If true, show URL addresses after external links.
#
# man_show_urls = False


# -- Options for Texinfo output -------------------------------------------

# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
#  dir menu entry, description, category)
texinfo_documents = [
    (root_doc, 'test', 'test Documentation',
     author, 'test', 'One line description of project.',
     'Miscellaneous'),
]

# Documents to append as an appendix to all manuals.
#
# texinfo_appendices = []

# If false, no module index is generated.
#
# texinfo_domain_indices = True

# How to display URL addresses: 'footnote', 'no', or 'inline'.
#
# texinfo_show_urls = 'footnote'

# If true, do not generate a @detailmenu in the "Top" node's menu.
#
# texinfo_no_detailmenu = False

# If false, do not generate in manual @ref nodes.
#
# texinfo_cross_references = False

# -- A random example -----------------------------------------------------

import sys, os
sys.path.insert(0, os.path.abspath('.'))
exclude_patterns = ['zzz']

numfig = True
#language = 'ja'

extensions.append('sphinx.ext.todo')
extensions.append('sphinx.ext.autodoc')
#extensions.append('sphinx.ext.autosummary')
extensions.append('sphinx.ext.intersphinx')
extensions.append('sphinx.ext.mathjax')
extensions.append('sphinx.ext.viewcode')
extensions.append('sphinx.ext.graphviz')


autosummary_generate = True
html_theme = 'default'
#source_suffix = ['.rst', '.txt']

These are the built-in Sphinx builders.  More builders can be added by extensions.

The builder's "name" must be given to the -M or -b command-line options of sphinx-build to select 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.

----

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.

name = 'html'

The builder's name, for the -b command line option.

format = 'html'

The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = ['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/.

name = 'dirhtml'

The builder's name, for the -b command line option.

format = 'html'

The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = ['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.

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

name = 'singlehtml'

The builder's name, for the -b command line option.

format = 'html'

The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = ['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.

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

name = 'htmlhelp'

The builder's name, for the -b command line option.

format = 'html'

The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = ['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 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.

name = 'qthelp'

The builder's name, for the -b command line option.

format = 'html'

The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = ['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.

Added 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 support file that allows the GNOME Devhelp reader to view them.

name = 'devhelp'

The builder's name, for the -b command line option.

format = 'html'

The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = ['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 https://idpf.org/epub or https://en.wikipedia.org/wiki/EPUB. The builder creates EPUB 3 files.

name = 'epub'

The builder's name, for the -b command line option.

format = 'html'

The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = ['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.

Added in version 1.4.

Changed in version 1.5: Since Sphinx 1.5, the epub3 builder is used as the default epub builder.

class sphinx.builders.latex.LaTeXBuilder

This builder produces LaTeX source files in the output directory.  The actual PDF builds happen inside this output directory and need to be triggered in a second step.  This can be done via make all-pdf there. To combine the two steps into only one, use sphinx-build -M (i.e. -M latexpdf not -b latexpdf) or make latexpdf at the project root.

See latex_documents and the chapter Options for LaTeX output for available options.

PDF builds need a sufficiently complete LaTeX installation. The testing is currently (since 5.3.0) done on Ubuntu 22.04LTS, whose LaTeX distribution matches upstream TeXLive 2021 as of 2022/02/04, but PDF builds can be successfully done on much older LaTeX installations.

At any rate, on Ubuntu for example, following packages must all be present:

• texlive-latex-recommended
• texlive-fonts-recommended
• tex-gyre (if latex_engine left to default)
• texlive-latex-extra
• latexmk

Changed in version 4.0.0: TeX Gyre fonts now required for 'pdflatex' engine (default).

Additional packages are needed in some circumstances:

• texlive-lang-cyrillic for Cyrillic (and also then cm-super if using the default fonts),
• texlive-lang-greek for Greek (and also then cm-super if using the default fonts),
• texlive-xetex if latex_engine is 'xelatex',
• texlive-luatex if latex_engine is 'lualatex',
• fonts-freefont-otf if latex_engine is either 'xelatex' or 'lualatex'.

NOTE:

Since 1.6, make latexpdf uses on GNU/Linux and macOS latexmk, as it makes sure the needed number of runs is automatically executed. On Windows the PDF builds execute a fix number of LaTeX runs (three, then makeindex, then two more).

One can pass to latexmk options via the LATEXMKOPTS Makefile variable. For example:

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"

name = 'latex'

The builder's name, for the -b command line option.

format = 'latex'

The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = ['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. The builder's name is rinoh. Refer to the rinohtype manual 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.

name = 'text'

The builder's name, for the -b command line option.

format = 'text'

The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

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

name = 'man'

The builder's name, for the -b command line option.

format = 'man'

The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

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

name = 'texinfo'

The builder's name, for the -b command line option.

format = 'texinfo'

The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = ['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.

Added 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 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'

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.

out_suffix

The suffix for all regular files.

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.

searchindex_filename

The filename for the search index Sphinx generates.

See Serialization builder details for details about the output format.

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

name = 'pickle'

The builder's name, for the -b command line option.

The old name web still works as well.

format = 'html'

The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = ['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.

name = 'json'

The builder's name, for the -b command line option.

format = 'html'

The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = ['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.

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

name = 'gettext'

The builder's name, for the -b command line option.

format = ''

The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Added in version 1.1.

class sphinx.builders.changes.ChangesBuilder

This builder produces an HTML overview of all versionadded, versionchanged, deprecated and versionremoved directives for the current version.  This is useful to generate a changelog file, for example.

name = 'changes'

The builder's name, for the -b command line option.

format = ''

The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = []

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.

name = 'dummy'

The builder's name, for the -b command line option.

supported_image_types: list[str] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

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

name = 'linkcheck'

The builder's name, for the -b command line option.

format = ''

The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = []

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

name = 'xml'

The builder's name, for the -b command line option.

format = 'xml'

The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

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

name = 'pseudoxml'

The builder's name, for the -b command line option.

format = 'pseudoxml'

The builder's output format, or '' if no document output is produced.

supported_image_types: list[str] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

Added in version 1.2.

Built-in Sphinx extensions that offer more builders are:

• doctest
• coverage

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

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.

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.

Document common members.

Unlike the other pickle files this pickle file requires that the sphinx package is available on unpickling.

Added 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 directives and roles) to describe and link to objects 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.

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 :no-index-entry:. If you want to exclude the object description from the table of contents, you can give the directive option flag :no-contents-entry:. If you want to typeset an object description, without even making it available for cross-referencing, you can give the directive option flag :no-index: (which implies :no-index-entry:). If you do not want to typeset anything, you can give the directive option flag :no-typesetting:.  This can for example be used to create only a target and index entry for later reference. Though, note that not every directive in every domain may support these options.

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

Added in version 5.2.3: The directive option :nocontentsentry: in the Python, C, C++, Javascript, and reStructuredText domains.

Added in version 7.2: The directive option no-typesetting in the Python, C, C++, Javascript, and reStructuredText domains.

Changed in version 7.2:

• The directive option :noindex: was renamed to :no-index:.
• The directive option :noindexentry: was renamed to :no-index-entry:.
• The directive option :nocontentsentry: was renamed to :no-contents-entry:.

The previous names are retained as aliases, but will be deprecated and removed in a future version of Sphinx.

An example using a Python domain directive:

.. py:function:: spam(eggs)
                 ham(eggs)

   Spam or ham the foo.

This describes the two Python functions spam and ham.  (Note that when signatures become too long, you can break them if you add a backslash to lines that are continued in the next line.  Example:

.. py:function:: filterwarnings(action, message='', category=Warning, \
                                module='', lineno=0, append=False)
   :no-index:

(This example also shows how to use the :no-index: flag.)

The domains also provide roles that link back to these object descriptions. For example, to link to one of the functions described in the example above, you could say

The function :py:func:`spam` does a similar thing.

As you can see, both directive and role names contain the domain name and the directive name.

The directive option :no-typesetting: can be used to create a target (and index entry) which can later be referenced by the roles provided by the domain. This is particularly useful for literate programming:

.. py:function:: spam(eggs)
   :no-typesetting:

.. code::

   def spam(eggs):
       pass

The function :py:func:`spam` does nothing.

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:

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

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.

The following domains are included within Sphinx:

Added in version 1.0.

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:

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

Changed in version 5.3: One can cross-reference including an option value: :option:`--module=foobar`, ,``:option:–module[=foobar]`` or :option:`--module foobar`.

Use option_emphasise_placeholders for parsing of “variable part” of a literal text (similarly to the samp role).

cmdoption directive is a deprecated alias for the option directive.

.. envvar:: name

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

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

Added in version 0.5.

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

.. describe:: text

.. object:: text

This directive produces the same formatting as the specific ones provided by domains, but does not create index entries or cross-referencing targets. Example:

.. describe:: PAPER

   You can set this variable to select a paper size.

Added in version 1.0.

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

.. c:member:: declaration

.. c:var:: declaration

Describes a C struct member or variable. Example signature:

.. c:member:: PyObject *PyTypeObject.tp_bases

The difference between the two directives is only cosmetic.

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

Added 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

PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

No-contents-entry

No-index-entry

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.

:single-line-parameter-list: (no value)

Ensures that the function’s parameters will be emitted on a single logical line, overriding c_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.1.

.. c:macro:: name

.. c:macro:: name(arg list)

Describes a C macro, i.e., a C-language #define, without the replacement text.

In the description of a macro you can use the same info fields as for the c:function directive.

Added in version 3.0: The function style variant.

:single-line-parameter-list: (no value)

Ensures that the macro’s parameters will be emitted on a single logical line, overriding c_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.1.

.. c:struct:: name

Describes a C struct.

Added in version 3.0.

.. c:union:: name

Describes a C union.

Added in version 3.0.

.. c:enum:: name

Describes a C enum.

Added in version 3.0.

.. c:enumerator:: name

Describes a C enumerator.

Added in version 3.0.

.. c:type:: typedef-like declaration

.. c:type:: name

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

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

:c:member:

:c:data:

:c:var:

:c:func:

:c:macro:

:c:struct:

:c:union:

:c:enum:

:c:enumerator:

:c:type:

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

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

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:

struct Data

union [anonymous]

int a

double b

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

Added in version 3.0.

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.

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

int data

int f(double k)

int data

int f(double k)

Added in version 3.2.

Options

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

Added in version 3.3.

:noroot:

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

Added in version 3.5.

:c:expr:

:c:texpr:

Insert a C expression or type either as inline code (cpp:expr) or inline text (cpp:texpr). For example:

.. c:var:: int a = 42

.. c:function:: int f(int i)

An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`).

A type: :c:expr:`const Data*`
(or as text :c:texpr:`const Data*`).

will be rendered as follows:

int a = 42

int f(int i)

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

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

Added in version 3.0.

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

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

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

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

See Options for the C domain.

Added in version 1.0.

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

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

.. cpp:class:: class specifier

.. cpp:struct:: class specifier

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

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

The difference between 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>

Added in version 2.0: The cpp:struct 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)

:single-line-parameter-list: (no value)

Ensures that the function’s parameters will be emitted on a single logical line, overriding cpp_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.1.

.. cpp:member:: (member) variable declaration

.. cpp:var:: (member) variable declaration

Describe a variable or member variable, e.g.,:

.. cpp:member:: std::string MyClass::myMember

.. cpp:var:: std::string MyClass::myOtherMember[N][M]

.. cpp:member:: int a = 42

Variable templates can also be described:

.. cpp:member:: template<class T> \
                constexpr T pi = T(3.1415926535897932385)

.. cpp:type:: typedef declaration

.. cpp:type:: name

.. cpp:type:: type alias declaration

Describe a type as in a typedef declaration, a type alias declaration, or simply the name of a type with unspecified type, e.g.,:

.. cpp:type:: std::vector<int> MyList

   A typedef-like declaration of a type.

.. cpp:type:: MyContainer::const_iterator

   Declaration of a type alias with unspecified type.

.. cpp:type:: MyType = std::unordered_map<int, std::string>

   Declaration of a type alias.

A type alias can also be templated:

.. cpp:type:: template<typename T> \
              MyContainer = std::vector<T>

The example are rendered as follows.

typedef std::vector<int> MyList

A typedef-like declaration of a type.

type MyContainer::const_iterator

Declaration of a type alias with unspecified type.

using MyType = std::unordered_map<int, std::string>

Declaration of a type alias.

template<typename T> using MyContainer = std::vector<T>

.. cpp:enum:: unscoped enum declaration

.. cpp:enum-struct:: scoped enum declaration

.. cpp:enum-class:: scoped enum declaration

Describe a (scoped) enum, possibly with the underlying type specified.  Any enumerators declared inside an unscoped enum will be declared both in the enum scope and in the parent scope.  Examples:

.. cpp:enum:: MyEnum

   An unscoped enum.

.. cpp:enum:: MySpecificEnum : long

   An unscoped enum with specified underlying type.

.. cpp:enum-class:: MyScopedEnum

   A scoped enum.

.. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type

   A scoped enum with non-default visibility, and with a specified
   underlying type.

.. cpp:enumerator:: name

.. cpp:enumerator:: name = constant

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

.. cpp:enumerator:: MyEnum::myEnumerator

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

.. cpp:union:: name

Describe a union.

Added in version 1.8.

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

template<typename It> concept std::Iterator

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

Notation

It r

An lvalue.

Valid Expressions

• *r, when r is dereferenceable.
• ++r, with return type It&, when r is incrementable.

Added in version 1.5.

Some directives support options:

• :no-index-entry: and :no-contents-entry:, see Basic Markup.

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

  Added in version 1.6.

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:

class Data

union [anonymous]

int a

double b

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

Added in version 1.8.

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.

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

int a

void f(double d) const

void f(double d)

void f(int i)

void f()

whereas:

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

becomes

void f(double d) const

void f(double d)

Added in version 2.0.

Options

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

Added in version 3.5.

:noroot:

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

Added in version 3.5.

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.

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.

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.

std::Iterator{It} void advance(It &it)

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

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

:cpp:expr:

:cpp:texpr:

Insert a C++ expression or type either as inline code (cpp:expr) or inline text (cpp:texpr). For example:

.. cpp:var:: int a = 42

.. cpp:function:: int f(int i)

An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`).

A type: :cpp:expr:`const MySortedContainer<int>&`
(or as text :cpp:texpr:`const MySortedContainer<int>&`).

will be rendered as follows:

int a = 42

int f(int i)

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

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

Added in version 1.7: The cpp:expr role.

Added in version 1.8: The cpp:texpr role.

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.

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

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

Added in version 1.4.

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

Added in version 1.4.

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.

Added in version 4.3: The retval field type.

These roles link to the given declaration types:

:cpp:any:

:cpp:class:

:cpp:struct:

:cpp:func:

:cpp:member:

:cpp:var:

:cpp:type:

:cpp:concept:

:cpp:enum:

:cpp:enumerator:

Reference a C++ declaration by name (see below for details).  The name must be properly qualified relative to the position of the link.

Added 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, cpp:expr and cpp:texpr, where angle brackets do not need escaping.

For linking to non-templated declarations the name must be a nested name, e.g., f or MyClass::f.

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:

class C

void f(double d) const

void f(double d)

void f(int i)

void f()

References using the cpp:func role:

• Arbitrary overload: C::f, C::f()
• Also arbitrary overload: C::f(), C::f()
• Specific overload: void C::f(), void C::f()
• Specific overload: void C::f(int), void C::f(int)
• Specific overload: void C::f(double), void C::f(double)
• Specific overload: void C::f(double) const, void C::f(double) const

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

Assume the following declarations.

class Wrapper

template<typename TOuter> class Outer

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 (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 (Wrapper::Outer)
• Wrapper::Outer::Inner (Wrapper::Outer::Inner)
• template\<typename TInner> Wrapper::Outer::Inner (template<typename TInner> Wrapper::Outer::Inner)

Assume the following declarations.

template<typename TOuter> class Outer

template<typename TInner> class Inner

template<> class Outer<int>

template<typename TInner> class Inner

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

Assume the following declaration.

template<typename T> class Outer<T*>

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

See Options for the C++ domain.

Added in version 1.0.

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

.. 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 no-index option is specified.  If this option is specified, the directive will only update the current module name.

Added in version 1.6.

Changed in version 5.2: Module directives support body content.

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

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

:single-line-parameter-list: (no value)

Ensures that the function’s parameters will be emitted on a single logical line, overriding javascript_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.1.

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

Added in version 1.6.

:single-line-parameter-list: (no value)

Ensures that the function’s parameters will be emitted on a single logical line, overriding javascript_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.1.

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

class MyAnimal(name[, age])

Arguments

• name (string()) – The name of the animal
• age (number()) – an optional age for the animal

:single-line-parameter-list: (no value)

Ensures that the function’s parameters will be emitted on a single logical line, overriding javascript_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.1.

.. js:data:: name

Describes a global variable or constant.

.. js:attribute:: object.name

Describes the attribute name of object.