sphinx-all - Man Page

Sphinx is a Python application. It can be installed in one of the ways described below.

• PyPI package
• Conda package

• OS-specific package manager

  • Linux
  • macOS
  • Windows
• Docker
• Installation of the latest development release
• Installation from source

After installation, you can check that Sphinx is available by running

$ sphinx-build --version

This should print out the Sphinx version number.

TIP:

Sphinx packages are published on the Python Package Index (PyPI).  The preferred tool for installing packages from PyPI is pip, which is included in all modern versions of Python.

Run the following command:

$ pip install -U sphinx

TIP:

To avoid issues when rebuilding your environment, it is advisable to pin sphinx and third-party extension versions in a requirements.txt file:

$ pip install -r requirements.txt

Or, if writing documentation for a Python package, place the dependencies in the pyproject.toml file:

$ pip install .[docs]

To work with conda, you need a conda-based Python distribution such as anaconda, miniconda, miniforge or micromamba.

Sphinx is available both via the anaconda main channel (maintained by Anaconda Inc.)

$ conda install sphinx

as well as via the conda-forge community channel

$ conda install -c conda-forge sphinx

You may install a global version of Sphinx into your system using OS-specific package managers. However, be aware that this is less flexible and you may run into compatibility issues if you want to work across different projects.

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.

$ brew install sphinx-doc

For more information, refer to the package overview.

Install either python3x-sphinx using port:

$ sudo port install py312-sphinx

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

$ sudo port select --set python python312
$ sudo port select --set sphinx py312-sphinx

For more information, refer to the package overview.

Sphinx can be install using Chocolatey.

$ choco install sphinx

You would need to install Chocolatey before running this.

For more information, refer to the chocolatey page.

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 the latest development from PyPI using the --pre flag:

$ pip install -U --pre sphinx

WARNING:

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.

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.

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.

reStructuredText directives

toctree is a reStructuredText directive, a very versatile piece of markup.  Directives can have arguments, options and content.

Arguments are given directly after the double colon following the directive’s name.  Each directive decides whether it can have arguments, and how many.

Options are given after the arguments, in form of a “field list”.  The maxdepth is such an option for the toctree directive.

Content follows the options or arguments after a blank line.  Each directive decides whether to allow content, and what to do with it.

A common gotcha with directives is that the first line of the content must be indented to the same level as the options are.

The toctree directive initially is empty, and looks like so:

.. toctree::
   :maxdepth: 2

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

.. toctree::
   :maxdepth: 2

   usage/installation
   usage/quickstart
   ...

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

SEE ALSO:

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.

SEE ALSO:

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.

SEE ALSO:

You can also build a live version of the documentation that you can preview in the browser. It will detect changes and reload the page any time you make edits. To do so, use sphinx-autobuild to run the following command:

$ sphinx-autobuild source-dir output-dir

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.

SEE ALSO:

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.

SEE ALSO:

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.

SEE ALSO:

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.

SEE ALSO:

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

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 PyPI package.  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 reStructuredText 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:Creating a Read the Docs account. 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.12-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 Extending Sphinx.

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 reStructuredText. For the authoritative 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 reStructuredText 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 reStructuredText document. Paragraphs are simply chunks of text separated by one or more blank lines. As in Python, indentation is significant in reStructuredText, so all lines of the same paragraph must be left-aligned to the same level of indentation.

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

    TIP:

    If you want to add a class to a directive, you may consider the :class: option instead, which is supported by most directives and allows for a more compact notation.

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

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

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

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:

:cve:

A reference to a Common Vulnerabilities and Exposures record. This generates appropriate index entries. The text “CVE number“ is generated; with a link to an online copy of the specified CVE. You can link to a specific section by using :cve:`number#anchor`.

For example: CVE 2020-10735

Added in version 8.1.

:cwe:

A reference to a Common Weakness Enumeration. This generates appropriate index entries. The text “CWE number“ is generated; in the HTML output, with a link to an online copy of the specified CWE. You can link to a specific section by using :cwe:`number#anchor`.

For example: CWE 787

Added in version 8.1.

: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 reStructuredText 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 reStructuredText 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 reStructuredText 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 (e.g. HTML) treat it as a collection of hyperlinks.  On the other hand, the builders that output a single file (e.g. 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 reStructuredText 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.

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.

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.6: Added support for external links and “self” references.

Options

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

Assign class attributes. This is a common option. For example:

.. toctree::
   :class: custom-toc

Added in version 7.4.

:name: label (text)

An implicit target name that can be referenced using ref. This is a common option. For example:

.. toctree::
   :name: mastertoc

   foo

Added in version 1.3.

:caption: (text)

Add a caption to the toctree. For example:

.. toctree::
   :caption: Table of Contents

    foo

Added in version 1.3.

:numbered:

:numbered: depth

If you want to have section numbers even in HTML output, add the :numbered: option to the top-level toctree. For example:

.. toctree::
   :numbered:

   foo
   bar

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

Added in version 0.6.

Changed in version 1.1: Added the numeric depth argument.

:titlesonly:

Only list document titles, not other headings of the same level. For example:

.. toctree::
   :titlesonly:

   foo
   bar

Added in version 1.0.

:glob:

Parse glob wildcards in toctree entries. All entries are matched against the list of available documents, and matches are inserted into the list alphabetically. For 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]

Added in version 0.3.

:reversed:

Reverse the order of the entries in the list. This is particularly useful when using the :glob: option.

Added in version 1.5.

:hidden:

A hidden toctree only defines the document hierarchy. It will not insert links into the document at the location of the directive.

This makes sense if you have other means of navigation, e.g. through manual links, HTML sidebar navigation, or if you use the :includehidden: option on the top-level toctree.

Added in version 0.6.

:includehidden:

If you want one global table of contents showing the complete document structure, you can add the :includehidden: option to the top-level toctree directive. All other toctrees on child pages can then be made invisible with the :hidden: option. The top-level toctree with :includehidden: will then include their entries.

Added in version 1.2.

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

  This is used for the general index, which is populated with entries from index directives and all index-generating object descriptions. For example, see Sphinx’s Index.

• modindex

  This is used for the Python module index, which contains one entry per py:module directive. For example, see Sphinx’s Python Module Index.

• search

  This is used for the search page, which contains a form that uses the generated JSON search index and JavaScript to full-text search the generated documents for search words; it works on every major browser. For example, see Sphinx’s Search Page.

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

The admonition directives create ‘admonition’ elements, a standardised system of communicating different types of information, from a helpful tip to matters of paramount danger. These directives can be used anywhere an ordinary body element can, and can contain arbitrary body elements. There are nine specific named admonitions and the generic admonition directive.

.. attention::

Information that requires the reader’s attention. The content of the directive should be written in complete sentences and include all appropriate punctuation.

Example:

ATTENTION:

Please may I have your attention.

.. caution::

Information with regard to which the reader should exercise care. The content of the directive should be written in complete sentences and include all appropriate punctuation.

Example:

CAUTION:

Exercise due caution.

.. danger::

Information which may lead to near and present danger if not heeded. The content of the directive should be written in complete sentences and include all appropriate punctuation.

Example:

DANGER:

Let none think to fly the danger for soon or late love is his own avenger.

.. error::

Information relating to failure modes of some description. The content of the directive should be written in complete sentences and include all appropriate punctuation.

Example:

ERROR:

ERROR 418: I’m a teapot.

.. hint::

Information that is helpful to the reader. The content of the directive should be written in complete sentences and include all appropriate punctuation.

Example:

HINT:

Look under the flowerpot.

.. important::

Information that is of paramount importance and which the reader must not ignore. The content of the directive should be written in complete sentences and include all appropriate punctuation.

Example:

IMPORTANT:

This is a statement of paramount importance.

.. note::

An especially important bit of information that the reader should know. 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 tins of spam.

.. tip::

Some useful tidbit of information for the reader. The content of the directive should be written in complete sentences and include all appropriate punctuation.

Example:

TIP:

Remember your sun cream!

.. warning::

An important bit of information that the reader should be very aware of. The content of the directive should be written in complete sentences and include all appropriate punctuation.

Example:

WARNING:

Beware of the dog.

.. admonition:: title

A generic admonition, with an optional title. The content of the directive should be written in complete sentences and include all appropriate punctuation.

Example:

This is a title

This is the content of the admonition.

.. 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. The content of the seealso directive should be either a single line or a reStructuredText definition list.

Example:

.. seealso::

   Python's :py:mod:`zipfile` module
      Documentation of Python's standard :py:mod:`zipfile` module.

   `GNU tar manual, Basic Tar Format <https://example.org>`_
      Documentation for tar archive files, including GNU tar extensions.

SEE ALSO:

Module zipfile

Documentation of the zipfile standard module.

GNU tar manual, Basic Tar Format

Documentation for tar archive files, including GNU tar extensions.

.. versionadded:: version [brief explanation]

This directive documents the version of the project which added the described feature. When this applies to an entire module or component, it should be placed at the top of the relevant 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.

ATTENTION:

There must be no blank line between the directive head and the explanation; this is to make these blocks visually continuous in the markup.

Example:

.. versionadded:: 2.5
   The *spam* parameter.

Added in version 2.5: The spam parameter.

.. versionchanged:: version [brief explanation]

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

Example:

.. versionchanged:: 2.8
   The *spam* parameter is now of type *boson*.

Changed in version 2.8: The spam parameter is now of type boson.

.. deprecated:: version [brief explanation]

Similar to versionadded, but describes when the feature was deprecated. A brief explanation can also be given, for example to tell the reader what to use instead.

Example:

.. deprecated:: 3.1
   Use :py:func:`spam` instead.

Deprecated since version 3.1: Use spam() instead.

.. versionremoved:: version [brief explanation]

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

Added in version 7.3.

Example:

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

Removed in version 4.0: The spam() function is more flexible, and should be used instead.

.. rubric:: title

A rubric is like an informal heading that doesn’t correspond to the document’s structure, i.e. it does not 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.

Options

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

Assign class attributes. This is a common option.

:name: label (text)

An implicit target name that can be referenced using ref. This is a common option.

:heading-level: n (number from 1 to 6)

Added in version 7.4.1.

Use this option to specify the heading level of the rubric. In this case the rubric will be rendered as <h1> to <h6> for HTML output, or as the corresponding non-numbered sectioning command for LaTeX (see latex_toplevel_sectioning).

.. centered::

This directive creates a centered boldfaced line of text.

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.

Options

:columns: n (int)

The number of columns; defaults to 2. For 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 reStructuredText doctest blocks;
• using reStructuredText 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]

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

:force: (no value)

Ignore minor errors on highlighting.

Added in version 2.1.

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

Assign class attributes. This is a common option.

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.

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

General options

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

Assign class attributes. This is a common option.

Added in version 1.4.

:name: label (text)

An implicit target name that can be referenced using ref. This is a common option.

Added in version 1.3.

:caption: caption (text)

Add a caption above the included content. If no argument is given, the filename is used as the caption.

Added in version 1.3.

Options for formatting

:dedent: number (number or no value)

Strip indentation characters from the included content. When a number is given, the leading N characters are removed. When no argument given, all common leading indentation is removed (using textwrap.dedent()).

Added in version 1.3.

Changed in version 3.5: Support automatic dedent.

:tab-width: N (number)

Expand tabs to N spaces.

Added in version 1.0.

:encoding: (text)

Explicitly specify the encoding of the file. This overwrites the default encoding (source_encoding). For example:

.. literalinclude:: example.txt
   :encoding: latin-1

Added in version 0.4.3.

:linenos: (no value)

Show line numbers alongside the included content. By default, line numbers are counted from 1. This can be changed by the options :lineno-start: and :lineno-match:.

:lineno-start: number (number)

Set line number for the first line to show. If given, this automatically activates :linenos:.

:lineno-match:

When including only parts of a file and show the original line numbers. This is only allowed only when the selection consists of contiguous lines.

Added in version 1.3.

:emphasize-lines: line numbers (comma separated numbers)

Emphasise particular lines of the included content. For example:

.. literalinclude:: example.txt
   :emphasize-lines: 1,2,4-6

:language: language (text)

Select a highlighting language (Pygments lexer) different from the current file’s standard language (set by highlight or highlight_language).

:force: (no value)

Ignore minor errors in highlighting.

Added in version 2.1.

Options for selecting the content to include

:pyobject: object (text)

For Python files, only include the specified class, function or method:

.. literalinclude:: example.py
   :pyobject: Timer.start

Added in version 0.6.

:lines: line numbers (comma separated numbers)

Specify exactly which lines to include:

.. literalinclude:: example.py
   :lines: 1,3,5-10,20-

This includes line 1, line 3, lines 5 to 10, and line 20 to the end.

Added in version 0.6.

:start-at: text

:start-after: text

:end-before: text

:end-at: text

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 the option string (start-at will keep the line). Then end-before/end-at filter lines after the line that contains the option string (end-at will keep the line and end-before skip the first line).

Added in version 0.6: Added the start-after and end-before options.

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

TIP:

To only select [second-section] of an INI file such as the following, 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

These options can be useful when working with tag comments. Using :start-after: [initialise] and :end-before: [initialised] keeps the lines between between the two comments below:

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

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

:prepend: line (text)

Prepend a line before the included code. This can be useful for example when highlighting PHP code that doesn’t include the <?php or ?> markers.

Added in version 1.0.

:append: line (text)

Append a line after the included code. This can be useful for example when highlighting PHP code that doesn’t include the <?php or ?> markers.

Added in version 1.0.

:diff: filename

Show the diff of two files. For example:

.. literalinclude:: example.txt
   :diff: example.txt.orig

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

Added in version 1.3.

Changed in version 0.6: Added support for absolute filenames.

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.

.. glossary::

This directive must contain a reStructuredText 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.

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.

Options

:sorted:

Sort the entries alphabetically.

Added in version 0.6.

Changed in version 4.4: In internationalized documentation, sort 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 reStructuredText :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 are true (tags can be defined via the --tag command-line option or within conf.py, see here). Boolean expressions (like (latex or html) and draft) are supported and may use parentheses.

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

Options

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

Assign class attributes. This is a common option.

:name: label (text)

An implicit target name that can be referenced using ref. This is a common option.

:label: label (text)

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.

:nowrap:

Prevent 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 reStructuredText 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 affects the depth of the local toctree.  But it does not affect the depth of the global toctree.  So this does not change the sidebar of themes that use the global toctree.

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.

One of Sphinx’s most useful features is creating automatic cross-references through semantic cross-referencing roles. A cross reference to an object description, such as :func:`spam`, will create a link to the place where spam() is documented, appropriate to each output format (HTML, PDF, ePUB, etc.).

Sphinx supports various cross-referencing roles to create links to other elements in the documentation. In general, writing :role:`target` creates a link to the object called target of the type indicated by role. The link’s text depends the role but is often the same as or similar to target.

The behavior can be modified in the following ways:

• Custom link text: You can specify the link text explicitly using the same notation as in reStructuredText external links: :role:`custom text <target>` will refer to target and display custom text as the text of the link.

• Suppressed link: Prefixing with an exclamation mark (!) prevents the creation of a link but otherwise keeps the visual output of the role.

  For example, writing :py:func:`!target` displays target(), with no link generated.

  This is helpful for cases in which the link target does not exist; e.g. changelog entries that describe removed functionality, or third-party libraries that don’t support intersphinx. Suppressing the link prevents warnings in nitpicky mode.

• Modified domain reference: When referencing domain objects, a tilde ~ prefix shortens the link text to 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.

  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.

These roles are described with their respective domains:

• C
• C++
• JavaScript
• reStructuredText
• Python

:ref:

To support cross-referencing to arbitrary locations in any document, the standard reStructuredText 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 reStructuredText 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 reStructuredText 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:

:confval:

A configuration value or setting. Index entries are generated. Also generates a link to the matching confval directive, if it exists.

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

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

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 customise Sphinx input and output behaviour.

An optional file docutils.conf can be added to the configuration directory to adjust Docutils configuration if not otherwise overridden or set by Sphinx.

Important points to note:

• If not otherwise documented, values must be strings, and their default is the empty string.
• The term “fully-qualified name” (FQN) refers to a string that names an importable Python object inside a module; for example, the fully-qualified name "sphinx.builders.Builder" means the Builder class in the sphinx.builders module.
• Document names use / as the path separator and do not contain the file name extension.
• Where glob-style patterns are permitted, you can use the standard shell constructs (*, ?, [...], and [!...]) with the feature that none of these will match slashes (/). A double star ** can be used to match any sequence of characters including slashes.

TIP:

The configuration file is executed as Python code at build time (using importlib.import_module(), with the current directory set to the configuration directory), and therefore can execute arbitrarily complex code.

Sphinx then reads simple names from the file’s namespace as its configuration. In general, configuration values should be simple strings, numbers, or lists or dictionaries of simple values.

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 deleting imported modules is not needed.

There is a special object named tags available in the config file, which exposes the project tags. Tags are defined either via the --tag command-line option or tags.add('tag'). Note that the builder’s name and format tags are not available in conf.py.

It can be used to query and change the defined tags as follows:

• To query whether a tag is set, use 'tag' in tags.
• To add a tag, use tags.add('tag').
• To remove a tag, use tags.remove('tag').

project

Type

str.TP Default 'Project name not set'.UNINDENT

The documented project’s name. Example:

project = 'Thermidor'

author

Type

str.TP Default 'Author name not set'.UNINDENT

The project’s author(s). Example:

author = 'Joe Bloggs'

copyright

project_copyright

Type

str | Sequence[str].TP Default ''.UNINDENT

A copyright statement. Permitted styles are as follows, where ‘YYYY’ represents a four-digit year.

• copyright = 'YYYY'
• copyright = 'YYYY, Author Name'
• copyright = 'YYYY Author Name'
• copyright = 'YYYY-YYYY, Author Name'
• copyright = 'YYYY-YYYY Author Name'

If the string '%Y' appears in a copyright line, it will be replaced with the current four-digit year. For example:

• copyright = '%Y'
• copyright = '%Y, Author Name'
• copyright = 'YYYY-%Y, Author Name'

Added in version 3.5: The project_copyright alias.

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.

Changed in version 8.1: Copyright statements support the '%Y' placeholder.

version

Type

str.TP Default ''.UNINDENT

The major project version, used as the replacement for the |version| default substitution.

This may be something like version = '4.2'. The full project version is defined in release.

If your project does not draw a meaningful distinction between between a ‘full’ and ‘major’ version, set both version and release to the same value.

release

Type

str.TP Default ''.UNINDENT

The full project version, used as the replacement for the |release| default substitution, and e.g. in the HTML templates.

This may be something like release = '4.2.1b0'. The major (short) project version is defined in version.

If your project does not draw a meaningful distinction between between a ‘full’ and ‘major’ version, set both version and release to the same value.

needs_sphinx

Type

str.TP Default ''.UNINDENT

Set a minimum supported version of Sphinx required to build the project. The format should be a 'major.minor' version string like '1.1' Sphinx will compare it with its version and refuse to build the project if the running version of Sphinx is too old. By default, there is no minimum version.

Added in version 1.0.

Changed in version 1.4: Allow a 'major.minor.micro' version string.

extensions

Type

list[str].TP Default [].UNINDENT

A list of strings that are module names of Sphinx extensions. These can be extensions bundled with Sphinx (named sphinx.ext.*) or custom first-party or third-party extensions.

To use a third-party extension, you must ensure that it is installed and include it in the extensions list, like so:

extensions = [
    ...
    'numpydoc',
]

There are two options for first-party extensions. The configuration file itself can be an extension; for that, you only need to provide a setup() function in it. Otherwise, you must ensure that your custom extension is importable, and located in a directory that is in the Python path.

Ensure that absolute paths are used when modifying sys.path. If your custom extensions live in a directory that is relative to the configuration directory, use os.path.abspath() like so:

import os, sys; sys.path.append(os.path.abspath('sphinxext'))

extensions = [
   ...
   'extname',
]

The directory structure illustrated above would look like this:

<project directory>/
├── conf.py
└── sphinxext/
    └── extname.py

needs_extensions

Type

dict[str, str].TP Default {}.UNINDENT

If set, this value must be a dictionary specifying version requirements for extensions in extensions. The version strings should be in the 'major.minor' form. Requirements do not have to be specified for all extensions, only for those you want to check. Example:

needs_extensions = {
    'sphinxcontrib.something': '1.5',
}

This requires that the extension declares its version in the setup() function. See Sphinx API for further details.

Added in version 1.3.

manpages_url

Type

str.TP Default ''.UNINDENT

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.

# To use manpages.debian.org:
manpages_url = 'https://manpages.debian.org/{path}'
# To use man7.org:
manpages_url = 'https://man7.org/linux/man-pages/man{section}/{page}.{section}.html'
# To use linux.die.net:
manpages_url = 'https://linux.die.net/man/{section}/{page}'
# To use helpmanual.io:
manpages_url = 'https://helpmanual.io/man{section}/{page}'

Added in version 1.7.

today

today_fmt

These values determine how to format the current date, used as the replacement for the |today| default substitution.

The default for today is '', and the default for today_fmt is '%b %d, %Y' (or, if translation is enabled with language, an equivalent format for the selected locale).

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

numfig

Type

bool.TP Default False.UNINDENT

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.

NOTE:

The LaTeX builder always assigns numbers whether this option is enabled or not.

Added in version 1.3.

numfig_format

Type

dict[str, str].TP Default {}.UNINDENT

A dictionary mapping 'figure', 'table', 'code-block' and 'section' to strings that are used for format of figure numbers. The marker %s will be replaced with the figure number.

The defaults are:

numfig_format = {
    'code-block': 'Listing %s',
    'figure': 'Fig. %s',
    'section': 'Section',
    'table': 'Table %s',
}

Added in version 1.3.

numfig_secnum_depth

Type

int.TP Default 1.UNINDENT

• If set to 0, figures, tables, and code-blocks are continuously numbered starting at 1.
• If 1, the numbering will be x.1, x.2, … with x representing the section number. (If there is no top-level section, the prefix will not be added ). This naturally applies only if section numbering has been activated via the :numbered: option of the toctree directive.
• If 2, the numbering will be x.y.1, x.y.2, … with x representing the section number and y the sub-section number. If located directly under a section, there will be no y. prefix, and if there is no top-level section, the prefix will not be added.
• Any other positive integer can be used, following the rules above.

Added in version 1.3.

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

highlight_language

Type

str.TP Default 'default'.UNINDENT

The default language to highlight source code in. The default is 'default', which suppresses warnings if highlighting as Python code fails.

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

highlight_options

Type

dict[str, dict[str, Any]].TP Default {}.UNINDENT

A dictionary that maps Pygments lexer names to their options. These are lexer-specific; for the options understood by each, see the Pygments documentation.

Example:

highlight_options = {
  'default': {'stripall': True},
  'php': {'startinline': True},
}

Added in version 1.3.

Changed in version 3.5: Allow configuring highlight options for multiple lexers.

pygments_style

Type

str.TP Default 'sphinx'.UNINDENT

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.

tls_verify

Type

bool.TP Default True.UNINDENT

If True, Sphinx verifies server certificates.

Added in version 1.5.

tls_cacerts

Type

str | dict[str, str].TP Default ''.UNINDENT

A path to a certification file of CA or a path to directory which contains the certificates. This also allows a dictionary mapping hostnames to the certificate file path. The certificates are used to verify server certifications.

Added in version 1.5.

TIP:

Sphinx uses requests as a HTTP library internally. If tls_cacerts is not set, Sphinx falls back to requests’ default behaviour. See requests:verification for further details.

user_agent

Type

str.TP Default 'Mozilla/5.0 (X11; Linux x86_64; rv:100.0) Gecko/20100101 Firefox/100.0 Sphinx/X.Y.Z'.UNINDENT

Set the User-Agent used by Sphinx for HTTP requests.

Added in version 2.3.

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

language

Type

str.TP Default 'en'.UNINDENT

The code for the language the documents 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.

Added in version 0.5.

Changed in version 1.4: Support figure substitution

Changed in version 5.0: The default is now 'en' (previously None).

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

Type

list[str].TP Default ['locale'].UNINDENT

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

NOTE:

The -v option to sphinx-build is useful to check the locale_dirs setting is working as expected. If the message catalog directory not found, debug messages are emitted.

Added in version 0.5.

Changed in version 1.5: Use locales directory as a default value

gettext_allow_fuzzy_translations

Type

bool.TP Default False.UNINDENT

If True, “fuzzy” messages in the message catalogs are used for translation.

Added in version 4.3.

gettext_compact

Type

bool | str.TP Default True.UNINDENT

• 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 False, a document’s text domain is the docname, in full.
• If set to a string, every document’s text domain is set to this string, making all documents use single text domain.

With gettext_compact = True, the document markup/code.rst ends up in the markup text domain. With this option set to False, it is markup/code. With this option set to 'sample', it is sample.

Added in version 1.1.

Changed in version 3.3: Allow string values.

gettext_uuid

Type

bool.TP Default False.UNINDENT

If True, Sphinx generates UUID information for version tracking in message catalogs. It is used to:

• Add a UUID line for each msgid in .pot files.
• Calculate similarity between new msgids and previously saved old msgids. (This calculation can take a long time.)

TIP:

If you want to accelerate the calculation, you can use a third-party package (Levenshtein) by running pip install levenshtein.

Added in version 1.3.

gettext_location

Type

bool.TP Default True.UNINDENT

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

Added in version 1.3.

gettext_auto_build

Type

bool.TP Default True.UNINDENT

If True, Sphinx builds a .mo file for each translation catalog file.

Added in version 1.3.

gettext_additional_targets

Type

set[str] | Sequence[str].TP Default [].UNINDENT

Enable gettext translation for certain element types. Example:

gettext_additional_targets = {'literal-block', 'image'}

The following element types are supported:

• 'index' – index terms
• 'literal-block' – literal blocks (:: annotation and code-block directive)
• 'doctest-block' – doctest block
• 'raw' – raw content
• 'image' – image/figure uri

Added in version 1.3.

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

Changed in version 7.4: Permit and prefer a set type.

figure_language_filename

Type

str.TP Default '{root}.{language}{ext}'.UNINDENT

The filename format for language-specific figures. The available format tokens are:

• {root}: the filename, including any path component, without the file extension. For example: images/filename.
• {path}: the directory path component of the filename, with a trailing slash if non-empty. For example: images/.
• {basename}: the filename without the directory path or file extension components. For example: filename.
• {ext}: the file extension. For example: .png.
• {language}: the translation language. For example: en.
• {docpath}: the directory path component for the current document, with a trailing slash if non-empty. For example: dirname/.

By default, an image directive .. image:: images/filename.png, using an image at images/filename.png, will use the language-specific figure filename images/filename.en.png.

If figure_language_filename is set as below, the language-specific figure filename will be images/en/filename.png instead.

figure_language_filename = '{path}{language}/{basename}{ext}'

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

Type

bool | 'translated' | 'untranslated'.TP Default False.UNINDENT

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.

Added in version 7.1.

default_role

Type

str.TP Default None.UNINDENT

The name of a reStructuredText 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 role can always be set within individual documents using the standard reStructuredText default-role directive.

Added in version 0.4.

keep_warnings

Type

bool.TP Default False.UNINDENT

Keep warnings as “system message” paragraphs in the rendered documents. Warnings are always written to the standard error stream when sphinx-build is run, regardless of this setting.

Added in version 0.5.

option_emphasise_placeholders

Type

bool.TP Default False.UNINDENT

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.

primary_domain

Type

str.TP Default 'py'.UNINDENT

The name of the default domain. Can also be None to disable a default domain. The default is 'py', for the Python domain.

Those objects in other domain (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”). Example:

primary_domain = 'cpp'

Added in version 1.0.

rst_epilog

Type

str.TP Default ''.UNINDENT

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

rst_epilog = """
.. |psf| replace:: Python Software Foundation
"""

Added in version 0.6.

rst_prolog

Type

str.TP Default ''.UNINDENT

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

rst_prolog = """
.. |psf| replace:: Python Software Foundation
"""

Added in version 1.0.

show_authors

Type

bool.TP Default False.UNINDENT

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

trim_footnote_reference_space

Type

bool.TP Default False.UNINDENT

Trim spaces before footnote references that are necessary for the  reStructuredText parser to recognise the footnote, but do not look too nice in the output.

Added in version 0.6.

These options control maths markup and notation.

math_eqref_format

Type

str.TP Default '({number})'.UNINDENT

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.

Added in version 1.7.

math_number_all

Type

bool.TP Default False.UNINDENT

Force all displayed equations to be numbered. Example:

math_number_all = True

Added in version 1.4.

math_numfig

Type

bool.TP Default True.UNINDENT

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.

Added in version 1.7.

math_numsep

Type

str.TP Default '.'.UNINDENT

A string that defines the separator between section numbers and the equation number when numfig is enabled and numfig_secnum_depth is positive.

Example: '-' gets rendered as 1.2-3.

Added in version 7.4.

nitpicky

Type

bool.TP Default False.UNINDENT

Enables nitpicky mode if True. In nitpicky mode, Sphinx will warn about all references where the target cannot be found. This is recommended for new projects as it ensures that all references are to valid targets.

You can activate this mode temporarily using the --nitpicky command-line option. See nitpick_ignore for a way to mark missing references as “known missing”.

nitpicky = True

Added in version 1.0.

nitpick_ignore

Type

set[tuple[str, str]] | Sequence[tuple[str, str]].TP Default ().UNINDENT

A set or list of (warning_type, target) tuples that should be ignored when generating warnings in "nitpicky mode". Note that warning_type should include the domain name if present. Example:

nitpick_ignore = {
    ('py:func', 'int'),
    ('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

Type

set[tuple[str, str]] | Sequence[tuple[str, str]].TP Default ().UNINDENT

An extended version of nitpick_ignore, which instead interprets the warning_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

add_function_parentheses

Type

bool.TP Default True.UNINDENT

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.

maximum_signature_line_length

Type

int | None.TP Default None.UNINDENT

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

strip_signature_backslash

Type

bool.TP Default False.UNINDENT

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.

toc_object_entries

Type

bool.TP Default True.UNINDENT

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

Added in version 5.2.

toc_object_entries_show_parents

Type

'domain' | 'hide' | 'all'.TP Default 'domain'.UNINDENT

A string that determines how domain objects (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.

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.

exclude_patterns

Type

Sequence[str].TP Default ().UNINDENT

A list of glob-style patterns 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. exclude_patterns has priority over include_patterns.

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
• '**/.git' – ignores all .git directories
• 'Thumbs.db' – ignores all Thumbs.db files

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

Type

Sequence[str].TP Default ('**',).UNINDENT

A list of glob-style patterns 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. By default, 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.

master_doc

root_doc

Type

str.TP Default 'index'.UNINDENT

Sphinx builds a tree of documents based on the toctree directives contained within the source files. This sets the name of the document containing the master toctree directive, and hence the root of the entire tree. Example:

master_doc = 'contents'

Changed in version 2.0: Default is 'index' (previously 'contents').

Added in version 4.0: The root_doc alias.

source_encoding

Type

str.TP Default 'utf-8-sig'.UNINDENT

The file encoding of all source files. The recommended encoding is 'utf-8-sig'.

Added in version 0.5.

source_suffix

Type

dict[str, str] | Sequence[str] | str.TP Default {'.rst': 'restructuredtext'}.UNINDENT

A dictionary mapping the file extensions (suffixes) of source files to their file types. Sphinx considers all files files with suffixes in source_suffix to be source files. Example:

source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'restructuredtext',
    '.md': 'markdown',
}

By default, Sphinx only supports the 'restructuredtext' file type. Further file types can be added with extensions that register different source file parsers, such as MyST-Parser. Refer to the extension’s documentation to see which file types it supports.

If the value is a string or sequence of strings, Sphinx will consider that they are all 'restructuredtext' files.

NOTE:

File extensions must begin with a dot ('.').

Changed in version 1.3: Support a list of file extensions.

Changed in version 1.8: Change to a map of file extensions to file types.

smartquotes

Type

bool.TP Default True.UNINDENT

If True, the Smart Quotes transform will be used to convert quotation marks and dashes to typographically correct entities.

Added in version 1.6.6: Replaces the now-removed html_use_smartypants. It applies by default to all builders except man and text (see smartquotes_excludes.)

NOTE:

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

Type

str.TP Default 'qDe'.UNINDENT

Customise the Smart Quotes transform. See below for the permitted codes. The default 'qDe' educates normal quote characters ", ', em- and en-Dashes ---, --, and ellipses .....

'q'

Convert quotation marks

'b'

Convert backtick quotation marks (“double” only)

'B'

Convert backtick quotation marks (“double” and `single')

'd'

Convert dashes (convert -- to em-dashes and --- to en-dashes)

'D'

Convert dashes (old school) (convert -- to en-dashes and --- to em-dashes)

'i'

Convert dashes (inverted old school) (convert -- to em-dashes and --- to en-dashes)

'e'

Convert ellipses ...

'w'

Convert '&quot;' entities to '"'

Added in version 1.6.6.

smartquotes_excludes

Type

dict[str, list[str]].TP Default {'languages': ['ja'], 'builders': ['man', 'text']}.UNINDENT

Control when the Smart Quotes transform is disabled. Permitted keys are 'builders' and 'languages', and The values are lists of strings.

Each entry gives a sufficient condition to ignore the smartquotes setting and deactivate the Smart Quotes transform. Example:

smartquotes_excludes = {
    'languages': ['ja'],
    'builders': ['man', 'text'],
}

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 SPHINXOPTS="-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 customise) the smart quotes for a given builder, for example latex, is to use make this way:

make latex SPHINXOPTS="-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.

template_bridge

Type

str.TP Default ''.UNINDENT

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

template_bridge = 'module.CustomTemplateBridge'

templates_path

Type

Sequence[str].TP Default ().UNINDENT

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

templates_path = ['.templates']

Changed in version 1.3: As these files are not meant to be built, they are automatically excluded when discovering source files.

show_warning_types

Type

bool.TP Default True.UNINDENT

Add the type of each warning as a suffix to the warning message. For example, WARNING: [...] [index] or WARNING: [...] [toc.circular]. This setting can be useful for determining which warnings types to include in a suppress_warnings list.

Added in version 7.3.0.

Changed in version 8.0.0: The default is now True.

suppress_warnings

Type

Sequence[str].TP Default ().UNINDENT

A list of warning codes to suppress arbitrary warning messages.

By default, Sphinx supports the following warning codes:

• app.add_node
• app.add_directive
• app.add_role
• app.add_generic_role
• app.add_source_parser
• config.cache
• docutils
• 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.copy_overwrite
• misc.highlighting_failure
• toc.circular
• toc.excluded
• toc.no_title
• 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
• autosummary.import_cycle
• 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.

Added in version 7.3: Added config.cache.

Added in version 7.3: Added toc.no_title.

Added in version 8.0: Added misc.copy_overwrite.

These options influence HTML output. Various other builders are derived from the HTML output, and also make use of these options.

html_theme

Type

str.TP Default 'alabaster'.UNINDENT

The theme for HTML output. See the HTML theming section.

Added in version 0.6.

Changed in version 1.3: The default theme is now 'alabaster'.

html_theme_options

Type

dict[str, Any].TP Default {}.UNINDENT

A dictionary of options that influence the look and feel of the selected theme. These are theme-specific. The options understood by the builtin themes are described here.

Added in version 0.6.

html_theme_path

Type

list[str].TP Default [].UNINDENT

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

Type

Sequence[str] | str.TP Default ().UNINDENT

Stylesheets to use for HTML pages. The stylesheet given by the selected theme is used by default 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. If you only want to add or override a few things from the theme, use CSS @import to import the theme’s stylesheet.

Changed in version 5.1: The value can be a iterable of strings.

html_title

Type

str.TP Default 'project release documentation'.UNINDENT

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.

html_short_title

Type

str.TP Default The value of html_title.UNINDENT

A shorter “title” for HTML documentation. This is used for links in the header and in the HTML Help documentation.

Added in version 0.4.

html_baseurl

Type

str.TP Default ''.UNINDENT

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.

Added in version 1.8.

html_codeblock_linenos_style

Type

'inline' | 'table'.TP Default 'inline'.UNINDENT

The style of line numbers for code-blocks.

'table'

Display line numbers using <table> tag

'inline'

Display line numbers using <span> tag

Added in version 3.2.

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

Deprecated since version 4.0.

html_context

Type

dict[str, Any].TP Default {}.UNINDENT

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 sphinx-build’s --html-define command-line option.

Added in version 0.5.

html_logo

Type

str.TP Default ''.UNINDENT

If given, this must be the name of an image file (path relative to the configuration directory) that is the logo of the documentation, or a 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.

Added in version 0.4.1: The image file will be copied to the _static directory, but only if the file does not already exist there.

Changed in version 4.0: Also accepts a URL.

html_favicon

Type

str.TP Default ''.UNINDENT

If given, this must be the name of an image file (path relative to the configuration directory) that is the favicon of the documentation, or a URL that points an image file for the favicon. Browsers use this as the icon for tabs, windows and bookmarks. It should be a 16-by-16 pixel icon in the PNG, SVG, GIF, or ICO file formats.

Example:

html_favicon = 'static/favicon.png'

Added in version 0.4: The image file will be copied to the _static, 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

Type

Sequence[str | tuple[str, dict[str, str]]].TP Default [].UNINDENT

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 dictionary is used for the <link> tag’s attributes.

Example:

html_css_files = [
    'custom.css',
    'https://example.com/css/custom.css',
    ('print.css', {'media': 'print'}),
]

The special attribute priority can be set as an integer to load the CSS file at an earlier or later step. For more information, refer to Sphinx.add_css_file().

Added in version 1.8.

Changed in version 3.5: Support the priority attribute

html_js_files

Type

Sequence[str | tuple[str, dict[str, str]]].TP Default [].UNINDENT

A list of JavaScript 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/script.js'. The attributes dictionary is used for the <script> tag’s attributes.

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 later step. For more information, refer to Sphinx.add_js_file().

Added in version 1.8.

Changed in version 3.5: Support the priority attribute

html_static_path

Type

list[str].TP Default [].UNINDENT

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, explicitly add each file to this setting:

html_static_path = ['_static', '_static/.htaccess']

An alternative approach is to use html_extra_path, which allows copying 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

Type

list[str].TP Default [].UNINDENT

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

Type

str.TP Default None.UNINDENT

If set, a ‘Last updated on:’ timestamp is inserted into the page footer using the given strftime() format. The empty string is equivalent to '%b %d, %Y' (or a locale-dependent equivalent).

html_last_updated_use_utc

Type

bool.TP Default False.UNINDENT

Use GMT/UTC (+00:00) instead of the system’s local time zone for the time supplied to html_last_updated_fmt. This is most useful when the format used includes the time.

html_permalinks

Type

bool.TP Default True.UNINDENT

Add link anchors for each heading and description environment.

Added in version 3.5.

html_permalinks_icon

Type

str.TP Default '¶' (the paragraph sign).UNINDENT

Text for link anchors for each heading and description environment. HTML entities and Unicode are allowed.

Added in version 3.5.

html_sidebars

Type

dict[str, Sequence[str]].TP Default {}.UNINDENT

A dictionary defining custom sidebar templates, mapping document names to template names.

The keys can contain glob-style patterns, 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.)

Each value must be a list of strings which 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. The builtin themes use these templates by default: 'localtoc.html', 'relations.html', 'sourcelink.html', and 'searchbox.html'.

The bundled first-party 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': ['windows-sidebar.html', 'searchbox.html'],
}

This will render the custom template windows-sidebar.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).

Note that this value only has no effect if the chosen theme does not possess a sidebar, like the builtin scrolls and haiku themes.

Added in version 1.0: The ability to use globbing keys and to specify multiple sidebars.

Deprecated since version 1.7: A single string value for html_sidebars will be removed.

Changed in version 2.0: html_sidebars must be a list of strings, and no longer accepts a single string value.

html_additional_pages

Type

dict[str, str].TP Default {}.UNINDENT

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': 'custom-download.html.jinja',
}

This will render the template custom-download.html.jinja as the page download.html.

html_domain_indices

Type

bool | Sequence[str].TP Default True.UNINDENT

If True, generate domain-specific indices in addition to the general index. For e.g. the Python domain, this is the global module index.

This value can be a Boolean 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'.

Example:

html_domain_indices = {
    'py-modindex',
}

Added in version 1.0.

Changed in version 7.4: Permit and prefer a set type.

html_use_index

Type

bool.TP Default True.UNINDENT

Controls if an index is added to the HTML documents.

Added in version 0.4.

html_split_index

Type

bool.TP Default False.UNINDENT

Generates two versions of the index: once as a single page with all the entries, and once as one page per starting letter.

Added in version 0.4.

html_copy_source

Type

bool.TP Default True.UNINDENT

If True, the  reStructuredText sources are included in the HTML build as _sources/docname.

html_show_sourcelink

Type

bool.TP Default True.UNINDENT

If True (and html_copy_source is true as well), links to the reStructuredText sources will be added to the sidebar.

Added in version 0.6.

html_sourcelink_suffix

Type

str.TP Default '.txt'.UNINDENT

The suffix to append to source links (see html_show_sourcelink), unless files they have this suffix already.

Added in version 1.5.

html_use_opensearch

Type

str.TP Default ''.UNINDENT

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

Added in version 0.2.

html_file_suffix

Type

str.TP Default '.html'.UNINDENT

The file name suffix (file extension) for generated HTML files.

Added in version 0.4.

html_link_suffix

Type

str.TP Default The value of html_file_suffix.UNINDENT

The suffix for generated links to HTML files. Intended to support more esoteric server setups.

Added in version 0.6.

html_show_copyright

Type

bool.TP Default True.UNINDENT

If True, “© Copyright …” is shown in the HTML footer, with the value or values from copyright.

Added in version 1.0.

html_show_search_summary

Type

bool.TP Default True.UNINDENT

Show a summary of the search result, i.e., the text around the keyword.

Added in version 4.5.

html_show_sphinx

Type

bool.TP Default True.UNINDENT

Add “Created using Sphinx” to the HTML footer.

Added in version 0.4.

html_output_encoding

Type

str.TP Default 'utf-8'.UNINDENT

Encoding of HTML output files. 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

Type

bool.TP Default True.UNINDENT

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 behaviour. Default: True.

Added in version 1.0.

html_secnumber_suffix

Type

str.TP Default '. '.UNINDENT

Suffix for section numbers in HTML output. Set to ' ' to suppress the final dot on section numbers.

Added in version 1.0.

html_search_language

Type

str.TP Default The value of language.UNINDENT

Language to be used for generating the HTML full-text search index. This defaults to the global language selected with language. English ('en') is used as a fall-back option if there is no support for this language.

Support exists for the following 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

TIP:

Accelerating build speed

Each language (except Japanese) provides its own stemming algorithm. Sphinx uses a Python implementation by default. If you want to accelerate building the index file, you can use a third-party package (PyStemmer) by running pip install PyStemmer.

Added in version 1.1: Support English (en) and Japanese (ja).

Changed in version 1.3: Added additional languages.

html_search_options

Type

dict[str, str].TP Default {}.UNINDENT

A dictionary with options for the search language support. The meaning of these options depends on the language selected. Currently, only Japanese and Chinese support options.

Japanese

type – the type of the splitter to use.

The other options depend on the splitter used.

'sphinx.search.ja.DefaultSplitter'

The TinySegmenter algorithm, used by default.

'sphinx.search.ja.MecabSplitter':

The MeCab binding To use this splitter, the ‘mecab’ python binding or dynamic link library (‘libmecab.so’ for Linux, ‘libmecab.dll’ for Windows) is required.

'sphinx.search.ja.JanomeSplitter':

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

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

Chinese

dict

The jieba dictionary path for using a custom dictionary.

Added in version 1.1.

Changed in version 1.4: Allow any custom splitter in the type setting for Japanese.

html_search_scorer

Type

str.TP Default ''.UNINDENT

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

Type

bool.TP Default True.UNINDENT

Link images that have been resized with a scale option (scale, width, or height) to their original full-resolution image. This will not overwrite any link given by the target option on the the image directive, if present.

TIP:

To disable this feature on a per-image basis, add the no-scaled-link class to the image directive:

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

Added in version 1.3.

Changed in version 3.0: Images with the no-scaled-link class will not be linked.

html_math_renderer

Type

str.TP Default 'mathjax'.UNINDENT

The maths renderer to use for HTML output. The bundled renders are mathjax and imgmath. You must also load the relevant extension in extensions.

Added in version 1.8.

These options influence Single HTML output. This builder derives from the HTML builder, so the HTML options also apply where appropriate.

singlehtml_sidebars

Type

dict[str, Sequence[str]].TP Default The value of html_sidebars.UNINDENT

A dictionary defining custom sidebar templates, mapping document names to template names.

This has the same effect as html_sidebars, but the only permitted key is 'index', and all other keys are ignored.

These options influence HTML help output. This builder derives from the HTML builder, so the HTML options also apply where appropriate.

htmlhelp_basename

Type

str.TP Default '{project}doc'.UNINDENT

Output file base name for HTML help builder. The default is the project name with spaces removed and doc appended.

htmlhelp_file_suffix

Type

str.TP Default '.html'.UNINDENT

This is the file name suffix for generated HTML help files.

Added in version 2.0.

htmlhelp_link_suffix

Type

str.TP Default The value of htmlhelp_file_suffix.UNINDENT

Suffix for generated links to HTML files.

Added in version 2.0.

Added in version 1.3.

These options influence 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 directories within the bundle.

applehelp_bundle_name

Type

str.TP Default The value of project.UNINDENT

The basename for the Apple Help Book. The default is the project name with spaces removed.

applehelp_bundle_id

Type

str.TP Default None.UNINDENT

The bundle ID for the help book bundle.

WARNING:

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

applehelp_bundle_version

Type

str.TP Default '1'.UNINDENT

The bundle version, as a string.

applehelp_dev_region

Type

str.TP Default 'en-us'.UNINDENT

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

applehelp_icon

Type

str.TP Default None.UNINDENT

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

Type

str.TP Default 'project-release'.UNINDENT

The product tag for use with applehelp_kb_url.

applehelp_kb_url

Type

str.TP Default None.UNINDENT

The URL for your knowledgebase server, e.g. https://example.com/kbsearch.py?p='product'&q='query'&l='lang'. At runtime, Help Viewer will replace 'product' with the contents of applehelp_kb_product, 'query' with the text entered by the user in the search box, and 'lang' with the user’s system language.

Set this to to None to disable remote search.

applehelp_remote_url

Type

str.TP Default None.UNINDENT

The URL for remote content. You can place a copy of your Help Book’s Resources directory at this location and Help Viewer will attempt to use it to fetch updated content.

For example, 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.

Set this to to None for no remote content.

applehelp_index_anchors

Type

bool.TP Default False.UNINDENT

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

Type

str.TP Default None.UNINDENT

Controls the minimum term length for the help indexer. If None, use the default length.

applehelp_stopwords

Type

str.TP Default The value of language.UNINDENT

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:

• German (de)
• English (en)
• Spanish (es)
• French (fr)
• Hungarian (hu)
• Italian (it)
• Swedish (sv)

applehelp_locale

Type

str.TP Default The value of language.UNINDENT

Specifies the locale to generate help for. This is used to determine the name of the .lproj directory inside the Help Book’s Resources, and is passed to the help indexer.

applehelp_title

Type

str.TP Default 'project Help'.UNINDENT

Specifies the help book title.

applehelp_codesign_identity

Type

str.TP Default The value of CODE_SIGN_IDENTITY.UNINDENT

Specifies the identity to use for code signing. Use None if code signing is not to be performed.

Defaults to the value of the CODE_SIGN_IDENTITY environment variable, which is set by Xcode for script build phases, or None if that variable is not set.

applehelp_codesign_flags

Type

list[str].TP Default The value of OTHER_CODE_SIGN_FLAGS.UNINDENT

A list of additional arguments to pass to codesign when signing the help book.

Defaults to a list based on the value of the OTHER_CODE_SIGN_FLAGS environment variable, which is set by Xcode for script build phases, or the empty list if that variable is not set.

applehelp_codesign_path

Type

str.TP Default '/usr/bin/codesign'.UNINDENT

The path to the codesign program.

applehelp_indexer_path

Type

str.TP Default '/usr/bin/hiutil'.UNINDENT

The path to the hiutil program.

applehelp_disable_external_tools

Type

bool.TP Default False.UNINDENT

Do 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-macOS platform and then complete the final steps on a Mac for some reason.

These options influence EPUB output. This builder derives from the HTML builder, so the HTML options also apply where appropriate.

NOTE:

The actual value for some of these options is not important, but they are required for the Dublin Core metadata.

epub_basename

Type

str.TP Default The value of project.UNINDENT

The basename for the EPUB file.

epub_theme

Type

str.TP Default 'epub'.UNINDENT

The HTML theme for the EPUB output.  Since the default themes are not optimised 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

Type

dict[str, Any].TP Default {}.UNINDENT

A dictionary of options that influence the look and feel of the selected theme. These are theme-specific. The options understood by the builtin themes are described here.

Added in version 1.2.

epub_title

Type

str.TP Default The value of project.UNINDENT

The title of the document.

Changed in version 2.0: It defaults to the project option (previously html_title).

epub_description

Type

str.TP Default 'unknown'.UNINDENT

The description of the document.

Added in version 1.4.

Changed in version 1.5: Renamed from epub3_description

epub_author

Type

str.TP Default The value of author.UNINDENT

The author of the document. This is put in the Dublin Core metadata.

epub_contributor

Type

str.TP Default 'unknown'.UNINDENT

The name of a person, organisation, etc. that played a secondary role in the creation of the content of an EPUB Publication.

Added in version 1.4.

Changed in version 1.5: Renamed from epub3_contributor

epub_language

Type

str.TP Default The value of language.UNINDENT

The language of the document. This is put in the Dublin Core metadata.

epub_publisher

Type

str.TP Default The value of author.UNINDENT

The publisher of the document. This is put in the Dublin Core metadata. You may use any sensible string, e.g. the project homepage.

epub_copyright

Type

str.TP Default The value of copyright.UNINDENT

The copyright of the document. See copyright for permitted formats.

epub_identifier

Type

str.TP Default 'unknown'.UNINDENT

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.

epub_scheme

Type

str.TP Default 'unknown'.UNINDENT

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.

epub_uid

Type

str.TP Default 'unknown'.UNINDENT

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.

epub_cover

Type

tuple[str, str].TP Default ().UNINDENT

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

Added in version 1.1.

epub_css_files

Type

Sequence[str | tuple[str, dict[str, str]]].TP Default [].UNINDENT

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 dictionary is used for the <link> tag’s attributes. For more information, see html_css_files.

Added in version 1.8.

epub_guide

Type

Sequence[tuple[str, str, str]].TP Default ().UNINDENT

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

Type

Sequence[tuple[str, str]].TP Default ().UNINDENT

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'),
]

epub_post_files

Type

Sequence[tuple[str, str]].TP Default ().UNINDENT

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.

Example:

epub_post_files = [
    ('appendix.xhtml', 'Appendix'),
]

epub_exclude_files

Type

Sequence[str].TP Default [].UNINDENT

A sequence of files that are generated/copied in the build directory but should not be included in the EPUB file.

epub_tocdepth

Type

int.TP Default 3.UNINDENT

The depth of the table of contents in the file toc.ncx. It should be an integer greater than zero.

TIP:

A deeply nested table of contents may be difficult to navigate.

epub_tocdup

Type

bool.TP Default True.UNINDENT

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.

epub_tocscope

Type

'default' | 'includehidden'.TP Default 'default'.UNINDENT

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

'includehidden'

Include all ToC entries

Added in version 1.2.

epub_fix_images

Type

bool.TP Default False.UNINDENT

Try and fix image formats that are not supported by some EPUB readers. At the moment palette images with a small colour table are upgraded. This is disabled by default because the automatic conversion may lose information. You need the Python Image Library (Pillow) installed to use this option.

Added in version 1.2.

epub_max_image_width

Type

int.TP Default 0.UNINDENT

This option specifies the maximum width of images. If it is set to a valuevgreater than zero, images with a width larger than the given value are scaled accordingly. If it is zero, no scaling is performed. You need the Python Image Library (Pillow) installed to use this option.

Added in version 1.2.

epub_show_urls

Type

'footnote' | 'no' | 'inline'.TP Default 'footnote'.UNINDENT

Control how to display URL addresses. This is very useful for readers that have no other means to display the linked URL. The setting can have the following values:

'inline'

Display URLs inline in parentheses.

'footnote'

Display URLs in footnotes.

'no'

Do not display URLs.

The display of inline URLs can be customised by adding CSS rules for the class link-target.

Added in version 1.2.

epub_use_index

Type

bool.TP Default The value of html_use_index.UNINDENT

Add an index to the EPUB document.

Added in version 1.2.

epub_writing_mode

Type

'horizontal' | 'vertical'.TP Default 'horizontal'.UNINDENT

It specifies writing direction. It can accept 'horizontal' and 'vertical'

epub_writing_mode	'horizontal'	'vertical'
writing-mode	horizontal-tb	vertical-rl
page progression	left to right	right to left
iBook’s Scroll Theme support	scroll-axis is vertical.	scroll-axis is horizontal.

These options influence LaTeX output.

latex_engine

Type

'pdflatex' | 'xelatex' | 'lualatex' | 'platex' | 'uplatex'.TP Default 'pdflatex'.UNINDENT

The LaTeX engine to build the documentation. The setting can have the following values:

• 'pdflatex' – PDFLaTeX (default)
• 'xelatex' – XeLaTeX (default if language is one of el, zh_CN, or zh_TW)
• 'lualatex' – LuaLaTeX
• 'platex' – pLaTeX
• 'uplatex' – upLaTeX (default if language is 'ja')

IMPORTANT:

'pdflatex'‘s support for Unicode characters is limited. 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 typeface is GNU FreeFont, which has good coverage of Latin, Cyrillic, and Greek glyphs.

NOTE:

Sphinx 2.0 adds support for occasional Cyrillic and Greek letters or words in documents using a Latin language and 'pdflatex'.  To enable this, the 'fontenc' key of latex_elements must be used appropriately.

NOTE:

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 'preamble' key of latex_elements). You may prefer r'\usepackage[math-style=literal]{unicode-math}' to keep a Unicode literal such as α (U+03B1) as-is in output, rather than being rendered as \alpha.

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: Use 'uplatex' by default for Japanese documents.

latex_documents

Type

Sequence[tuple[str, str, str, str, str, bool]].TP Default The default LaTeX documents.UNINDENT

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 master document for your LaTeX build, provide your master_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 0.3: The 6th item toctree_only. Tuples with 5 items are still accepted.

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.

latex_logo

Type

str.TP Default ''.UNINDENT

If given, this must be the name of an image file (path relative to the configuration directory) that is the logo of the documentation. It is placed at the top of the title page.

latex_toplevel_sectioning

Type

'part' | 'chapter' | 'section'.TP Default None.UNINDENT

This value determines the topmost sectioning unit.  The default setting is 'section' if latex_theme is 'howto', and 'chapter' if it is 'manual'.  The alternative in both cases is to specify 'part', which means that LaTeX document will use the \part command.

In that case the numbering of sectioning units one level deep gets off-sync with HTML numbering, as by default LaTeX does not reset \chapter numbering (or \section for 'howto' theme) when encountering \part command.

Added in version 1.4.

latex_appendices

Type

Sequence[str].TP Default ().UNINDENT

A list of document names to append as an appendix to all manuals. This is ignored if latex_theme is set to 'howto'.

latex_domain_indices

Type

bool | Sequence[str].TP Default True.UNINDENT

If True, generate domain-specific indices in addition to the general index. For e.g. the Python domain, this is the global module index.

This value can be a Boolean 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'.

Example:

latex_domain_indices = {
    'py-modindex',
}

Added in version 1.0.

Changed in version 7.4: Permit and prefer a set type.

latex_show_pagerefs

Type

bool.TP Default False.UNINDENT

Add page references after internal references. This is very useful for printed copies of the manual.

Added in version 1.0.

latex_show_urls

Type

'no' | 'footnote' | 'inline'.TP Default 'no'.UNINDENT

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

'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

Type

bool.TP Default False.UNINDENT

Use standard LaTeX’s \multicolumn for merged cells in tables.

False

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.

True

Use LaTeX’s standard \multicolumn; this is incompatible with literal blocks in horizontally merged cells, and also with multiple paragraphs in such cells if the table is rendered using tabulary.

Added in version 1.6.

latex_table_style

Type

list[str].TP Default ['booktabs', 'colorrows'].UNINDENT

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 customise 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 the latex table color configuration keys instead.

To customise the styles for a table, use the :class: option if the table is defined using a directive, or otherwise insert a rst-class directive before the table (cf. Tables).

Currently recognised 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 in a table column specification like this:

  >{\columncolor{blue}\sphinxnorowcolor}

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

Added in version 5.3.0.

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

latex_use_xindy

Type

bool.TP Default True if latex_engine in {'xelatex', 'lualatex'} else False.UNINDENT

Use Xindy to prepare the index of general terms. By default, the LaTeX builder uses makeindex for preparing the index of general terms . Using Xindy means that words with UTF-8 characters will be 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 creates .ind files containing invalid bytes for the UTF-8 encoding if any indexed term starts with a non-ASCII character. 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 some dedicated support to the xindy base distribution for using 'pdflatex' engine with Cyrillic scripts. With both 'pdflatex' and Unicode engines, Cyrillic documents handle the indexing of Latin names correctly, even those having diacritics.

Added in version 1.8.

latex_elements

Type

dict[str, str].TP Default {}.UNINDENT

Added in version 0.5.

See the full documentation for latex_elements.

latex_docclass

Type

dict[str, str].TP Default {}.UNINDENT

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 documentation (language is 'ja'), by default 'jreport' is used for 'howto' and 'jsbook' for 'manual'.

latex_additional_files

Type

Sequence[str].TP Default ().UNINDENT

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, or to overwrite Sphinx LaTeX support files with custom versions. Image files that are referenced in source files (e.g. via .. image::) are copied automatically and should not be listed there.

ATTENTION:

Filenames with the .tex extension will be automatically 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 the \input{} macro accordingly.

Added in version 0.6.

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

latex_theme

Type

str.TP Default 'manual'.UNINDENT

The “theme” that the LaTeX output should use. It is a collection of settings for LaTeX output (e.g. document class, top level sectioning unit and so on).

The bundled first-party LaTeX themes are manual and howto:

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). latex_appendices is only available for this theme.

Added in version 3.0.

latex_theme_options

Type

dict[str, Any].TP Default {}.UNINDENT

A dictionary of options that influence the look and feel of the selected theme. These are theme-specific.

Added in version 3.1.

latex_theme_path

Type

list[str].TP Default [].UNINDENT

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_add_secnumbers

Type

bool.TP Default True.UNINDENT

Include section numbers in text output.

Added in version 1.7.

text_newlines

Type

'unix' | 'windows' | 'native'.TP Default 'unix'.UNINDENT

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.

Added in version 1.1.

text_secnumber_suffix

Type

str.TP Default '. '.UNINDENT

Suffix for section numbers in text output. Set to ' ' to suppress the final dot on section numbers.

Added in version 1.7.

text_sectionchars

Type

str.TP Default '*=-~"+`'.UNINDENT

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.

Added in version 1.1.

These options influence manual page output.

man_pages

Type

Sequence[tuple[str, str, str, str, str]].TP Default The default manual pages.UNINDENT

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 page. (If you want to use the default master document for your manual pages build, provide your master_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

Type

bool.TP Default False.UNINDENT

Add URL addresses after links.

Added in version 1.1.

man_make_section_directory

Type

bool.TP Default True.UNINDENT

Make a section directory on build man page.

Added in version 3.3.

Changed in version 4.0: The default is now False (previously True).

Changed in version 4.0.2: Revert the change in the default.

These options influence Texinfo output.

texinfo_documents

Type

Sequence[tuple[str, str, str, str, str, str, str, bool]].TP Default The default Texinfo documents.UNINDENT

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

Type

Sequence[str].TP Default [].UNINDENT

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

Added in version 1.1.

texinfo_cross_references

Type

bool.TP Default True.UNINDENT

Generate inline references in a document. Disabling inline references can make an info file more readable with a stand-alone reader (info).

Added in version 4.4.

texinfo_domain_indices

Type

bool | Sequence[str].TP Default True.UNINDENT

If True, generate domain-specific indices in addition to the general index. For e.g. the Python domain, this is the global module index.

This value can be a Boolean 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'.

Example:

texinfo_domain_indices = {
    'py-modindex',
}

Added in version 1.1.

Changed in version 7.4: Permit and prefer a set type.

texinfo_elements

Type

dict[str, Any].TP Default {}.UNINDENT

A dictionary that contains Texinfo snippets that override those that 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', and 'title'.

Added in version 1.1.

texinfo_no_detailmenu

Type

bool.TP Default False.UNINDENT

Do not generate a @detailmenu in the “Top” node’s menu containing entries for each sub-node in the document.

Added in version 1.2.

texinfo_show_urls

Type

'footnote' | 'no' | 'inline'.TP Default 'footnote'.UNINDENT

Control how to display URL addresses. The setting can have the following values:

'footnote'

Display URLs in footnotes.

'no'

Do not display URLs.

'inline'

Display URLs inline in parentheses.

Added in version 1.1.

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

qthelp_basename

Type

str.TP Default The value of project.UNINDENT

The basename for the qthelp file.

qthelp_namespace

Type

str.TP Default 'org.sphinx.{project_name}.{project_version}'.UNINDENT

The namespace for the qthelp file.

qthelp_theme

Type

str.TP Default 'nonav'.UNINDENT

The HTML theme for the qthelp output.

qthelp_theme_options

Type

dict[str, Any].TP Default {}.UNINDENT

A dictionary of options that influence the look and feel of the selected theme. These are theme-specific. The options understood by the builtin themes are described here.

xml_pretty

Type

bool.TP Default True.UNINDENT

Pretty-print the XML.

Added in version 1.2.

These options control which links the linkcheck builder checks, and which failures and redirects it ignores.

linkcheck_allowed_redirects

Type

dict[str, str].TP Default {}.UNINDENT

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.

The linkcheck builder will emit a warning when it finds redirected links that don’t meet the rules above. It can be useful to detect unexpected redirects when using the fail-on-warnings mode.

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

Added in version 4.1.

linkcheck_anchors

Type

bool.TP Default True.UNINDENT

Check the validity of #anchors in links. Since this requires downloading the whole document, it is considerably slower when enabled.

Added in version 1.2.

linkcheck_anchors_ignore

Type

Sequence[str].TP Default ["^!"].UNINDENT

A list of regular expressions that match anchors that the linkcheck builder should skip when checking the validity of anchors in links. For example, this allows skipping anchors added by a website’s JavaScript.

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

Type

Sequence[str].TP Default ().UNINDENT

A list or tuple of regular expressions matching URLs for which the linkcheck builder 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.

Added in version 7.1.

linkcheck_exclude_documents

Type

Sequence[str].TP Default ().UNINDENT

A list of regular expressions that match documents in which the linkcheck builder 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 subdirectory named 'legacy'
linkcheck_exclude_documents = [r'.*/legacy/.*']

Added in version 4.4.

linkcheck_ignore

Type

Sequence[str].TP Default ().UNINDENT

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.

These options control how the linkcheck builder makes HTTP requests, including how it handles redirects and authentication, and the number of workers to use.

linkcheck_auth

Type

Sequence[tuple[str, Any]].TP Default [].UNINDENT

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_allow_unauthorized

Type

bool.TP Default False.UNINDENT

When a webserver responds with an HTTP 401 (unauthorised) response, the current default behaviour of the linkcheck builder is to treat the link as “broken”. To change that behaviour, set this option to True.

Changed in version 8.0: The default value for this option changed to False, meaning HTTP 401 responses to checked hyperlinks are treated as “broken” by default.

Added in version 7.3.

linkcheck_rate_limit_timeout

Type

int.TP Default 300.UNINDENT

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 behaviour when servers indicate that requests are rate-limited, by setting the maximum duration (in seconds) that the builder will wait for between each attempt before recording a failure.

The linkcheck builder always respects a server’s direction of when to retry (using the Retry-After header). 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 (in seconds). Custom timeouts should be given as a number of seconds.

Added in version 3.4.

linkcheck_report_timeouts_as_broken

Type

bool.TP Default False.UNINDENT

If linkcheck_timeout expires while waiting for a response from a hyperlink, the linkcheck builder will report the link as a timeout by default.  To report timeouts as broken instead, you can set linkcheck_report_timeouts_as_broken to True.

Changed in version 8.0: The default value for this option changed to False, meaning timeouts that occur while checking hyperlinks will be reported using the new ‘timeout’ status code.

Added in version 7.3.

linkcheck_request_headers

Type

dict[str, dict[str, str]].TP Default {}.UNINDENT

A dictionary that maps URL (without paths) 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

Type

int.TP Default 1.UNINDENT

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

Added in version 1.4.

linkcheck_timeout

Type

int.TP Default 30.UNINDENT

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

Added in version 1.1.

linkcheck_workers

Type

int.TP Default 5.UNINDENT

The number of worker threads to use when checking links.

Added in version 1.1.