Scroll to navigation

SPHINX-ALL(1) Sphinx SPHINX-ALL(1)

NAME

sphinx-all - Sphinx documentation generator system manual

Sphinx makes it easy to create intelligent and beautiful documentation.


Here are some of Sphinx's major features:

  • Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text
  • Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information
  • Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children
  • Automatic indices: general index as well as a language-specific module indices
  • Code handling: automatic highlighting using the Pygments highlighter
  • Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules (API docs) via built-in extensions, and much more functionality via third-party extensions.
  • Themes: modify the look and feel of outputs via creating themes, and reuse many third-party themes.
  • Contributed extensions: dozens of extensions contributed by users; most of them installable from PyPI.

Sphinx uses the reStructuredText markup language by default, and can read MyST markdown via third-party extensions. Both of these are powerful and straightforward to use, and have functionality for complex documentation and publishing workflows. They both build upon Docutils to parse and write documents.

See below for how to navigate Sphinx's documentation.

SEE ALSO:

The Sphinx documentation Table of Contents has a full list of this site's pages.


GET STARTED

These sections cover the basics of getting started with Sphinx, including creating and building your own documentation from scratch.

Getting Started

Sphinx is a documentation generator or a tool that translates a set of plain text source files into various output formats, automatically producing cross-references, indices, etc. That is, if you have a directory containing a bunch of reStructuredText or Markdown documents, Sphinx can generate a series of HTML files, a PDF file (via LaTeX), man pages and much more.

Sphinx focuses on documentation, in particular handwritten documentation, however, Sphinx can also be used to generate blogs, homepages and even books. Much of Sphinx's power comes from the richness of its default plain-text markup format, 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.

Setting up the documentation sources

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

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

$ sphinx-quickstart


Defining document structure

Let's assume you've run sphinx-quickstart. It created a source directory with conf.py and a root document, index.rst. The main function of the root document is to serve as a welcome page, and to contain the root of the "table of contents tree" (or toctree). This is one of the main things that Sphinx adds to reStructuredText, a way to connect multiple files to a single hierarchy of documents.

reStructuredText directives

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

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

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

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

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

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

.. toctree::

:maxdepth: 2


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

.. toctree::

:maxdepth: 2
usage/installation
usage/quickstart
...


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

[image: more info] [image]
Read more about the toctree directive.

You can now create the files you listed in the toctree and add content, and their section titles will be inserted (up to the maxdepth level) at the place where the toctree directive is placed. Also, Sphinx now knows about the order and hierarchy of your documents. (They may contain toctree directives themselves, which means you can create deeply nested hierarchies if necessary.)

Adding content

In Sphinx source files, you can use most features of standard reStructuredText. There are also several features added by Sphinx. For example, you can add cross-file references in a portable way (which works for all output types) using the ref role.

For an example, if you are viewing the HTML version, you can look at the source for this document -- use the "Show Source" link in the sidebar.

Todo

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



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

Running the build

Now that you have added some files and content, let's make a first build of the docs. A build is started with the sphinx-build program:

$ sphinx-build -M html sourcedir outputdir


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

[image: more info] [image]
Refer to the sphinx-build man page for all options that sphinx-build supports.

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

$ make html


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

make latexpdf runs the LaTeX builder and readily invokes the pdfTeX toolchain for you.



Todo

Move this whole section into a guide on rST or directives



Documenting objects

One of Sphinx's main objectives is easy documentation of objects (in a very general sense) in any domain. A domain is a collection of object types that belong together, complete with markup to create and reference descriptions of these objects.

The most prominent domain is the Python domain. For example, to document Python's built-in function enumerate(), you would add this to one of your source files.

.. py:function:: enumerate(sequence[, start=0])

Return an iterator that yields tuples of an index and an item of the
*sequence*. (And so on.)


This is rendered like this:

Return an iterator that yields tuples of an index and an item of the sequence. (And so on.)

The argument of the directive is the signature of the object you describe, the content is the documentation for it. Multiple signatures can be given, each in its own line.

The Python domain also happens to be the default domain, so you don't need to prefix the markup with the domain name.

.. function:: enumerate(sequence[, start=0])

...


does the same job if you keep the default setting for the default domain.

There are several more directives for documenting other types of Python objects, for example py:class or py:method. There is also a cross-referencing role for each of these object types. This markup will create a link to the documentation of enumerate().

The :py:func:`enumerate` function can be used for ...


And here is the proof: A link to enumerate().

Again, the py: can be left out if the Python domain is the default one. It doesn't matter which file contains the actual documentation for enumerate(); Sphinx will find it and create a link to it.

Each domain will have special rules for how the signatures can look like, and make the formatted output look pretty, or add specific features like links to parameter types, e.g. in the C/C++ domains.

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

Basic configuration

Earlier we mentioned that the conf.py file controls how Sphinx processes your documents. In that file, which is executed as a Python source file, you assign configuration values. For advanced users: since it is executed by Sphinx, you can do non-trivial tasks in it, like extending sys.path or importing a module to find out the version you are documenting.

The config values that you probably want to change are already put into the conf.py by sphinx-quickstart and initially commented out (with standard Python syntax: a # comments the rest of the line). To change the default value, remove the hash sign and modify the value. To customize a config value that is not automatically added by sphinx-quickstart, just add an additional assignment.

Keep in mind that the file uses Python syntax for strings, numbers, lists and so on. The file is saved in UTF-8 by default, as indicated by the encoding declaration in the first line.

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

Todo

Move this entire doc to a different section



Autodoc

When documenting Python code, it is common to put a lot of documentation in the source files, in documentation strings. Sphinx supports the inclusion of docstrings from your modules with an extension (an extension is a Python module that provides additional features for Sphinx projects) called autodoc.

In order to use autodoc, you need to activate it in conf.py by putting the string 'sphinx.ext.autodoc' into the list assigned to the extensions config value:

extensions = ['sphinx.ext.autodoc']


Then, you have a few additional directives at your disposal. For example, to document the function io.open(), reading its signature and docstring from the source file, you'd write this:

.. autofunction:: io.open


You can also document whole classes or even modules automatically, using member options for the auto directives, like

.. automodule:: io

:members:


autodoc needs to import your modules in order to extract the docstrings. Therefore, you must add the appropriate path to sys.path in your conf.py.

WARNING:

autodoc imports the modules to be documented. If any modules have side effects on import, these will be executed by autodoc when sphinx-build is run.

If you document scripts (as opposed to library modules), make sure their main routine is protected by a if __name__ == '__main__' condition.



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

Todo

Move this doc to another section



Intersphinx

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

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

For example, to link to io.open() in the Python library manual, you need to setup your intersphinx_mapping like:

intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}


And now, you can write a cross-reference like :py:func:`io.open`. Any cross-reference that has no matching target in the current documentation set, will be looked up in the documentation sets configured in intersphinx_mapping (this needs access to the URL in order to download the list of valid targets). Intersphinx also works for some other domain's roles including :ref:, however it doesn't work for :doc: as that is non-domain role.

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

More topics to be covered

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

FOOTNOTES

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

Installing Sphinx

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

Overview

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

Linux

Debian/Ubuntu

Install either python3-sphinx using apt-get:

$ apt-get install python3-sphinx


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

RHEL, CentOS

Install python-sphinx using yum:

$ yum install python-sphinx


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

Other distributions

Most Linux distributions have Sphinx in their package repositories. Usually the package is called python3-sphinx, python-sphinx or sphinx. Be aware that there are at least two other packages with sphinx in their name: a speech recognition toolkit (CMU Sphinx) and a full-text search database (Sphinx search).

macOS

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

Homebrew

$ brew install sphinx-doc


For more information, refer to the package overview.

MacPorts

Install either python3x-sphinx using port:

$ sudo port install py39-sphinx


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

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


For more information, refer to the package overview.

Anaconda

$ conda install sphinx


Windows

Sphinx can be install using Chocolatey or installed manually.

Chocolatey

$ choco install sphinx


You would need to install Chocolatey before running this.

For more information, refer to the chocolatey page.

Other Methods

Most Windows users do not have Python installed by default, so we begin with the installation of Python itself. To check if you already have Python installed, open the Command Prompt (⊞Win-r and type cmd). Once the command prompt is open, type python --version and press Enter. If Python is installed, you will see the version of Python printed to the screen. If you do not have Python installed, refer to the Hitchhikers Guide to Python's Python on Windows installation guides. You must install Python 3.

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

Installation from PyPI

Sphinx packages are published on the Python Package Index. The preferred tool for installing packages from PyPI is pip. This tool is provided with all modern versions of Python.

On Linux or MacOS, you should open your terminal and run the following command.

$ pip install -U sphinx


On Windows, you should open Command Prompt (⊞Win-r and type cmd) and run the same command.

C:\> pip install -U sphinx


After installation, type sphinx-build --version on the command prompt. If everything worked fine, you will see the version number for the Sphinx package you just installed.

Installation from PyPI also allows you to install the latest development release. You will not generally need (or want) to do this, but it can be useful if you see a possible bug in the latest stable release. To do this, use the --pre flag.

$ pip install -U --pre sphinx


Using virtual environments

When installing Sphinx using pip, it is highly recommended to use virtual environments, which isolate the installed packages from the system packages, thus removing the need to use administrator privileges. To create a virtual environment in the .venv directory, use the following command.

$ python -m venv .venv


SEE ALSO:

venv -- creating virtual environments


WARNING:

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

$ apt-get install python3-venv




Docker

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.

Installation from source

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

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



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.

Tutorial: Build your first project

In this tutorial you will build a simple documentation project using Sphinx, and view it in your browser as HTML. The project will include narrative, handwritten documentation, as well as autogenerated API documentation.

The tutorial is aimed towards Sphinx newcomers willing to learn the fundamentals of how projects are created and structured. You will create a fictional software library to generate random food recipes that will serve as a guide throughout the process, with the objective of properly documenting it.

To showcase Sphinx capabilities for code documentation you will use Python, which also supports automatic documentation generation.

NOTE:

Several other languages are natively supported in Sphinx for manual code documentation, however they require extensions for automatic code documentation, like Breathe.


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.

Getting started

Setting up your project and development environment

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

README.rst

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


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

$ python -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install sphinx


NOTE:

The installation method used above is described in more detail in Installation from PyPI. For the rest of this tutorial, the instructions will assume a Python virtual environment.


If you executed these instructions correctly, you should have the Sphinx command line tools available. You can do a basic verification running this command:

(.venv) $ sphinx-build --version
sphinx-build 4.0.2


If you see a similar output, you are on the right path!

Creating the documentation layout

Then from the command line, run the following command:

(.venv) $ sphinx-quickstart docs


This will present to you a series of questions required to create the basic directory and configuration layout for your project inside the docs folder. To proceed, answer each question as follows:

  • > Separate source and build directories (y/n) [n]: Write "y" (without quotes) and press Enter.
  • > Project name: Write "Lumache" (without quotes) and press Enter.
  • > Author name(s): Write "Graziella" (without quotes) and press Enter.
  • > Project release []: Write "0.1" (without quotes) and press Enter.
  • > Project language [en]: Leave it empty (the default, English) and press Enter.

After the last question, you will see the new docs directory with the following content.

docs
├── build
├── make.bat
├── Makefile
└── source

├── conf.py
├── index.rst
├── _static
└── _templates


The purpose of each of these files is:

An empty directory (for now) that will hold the rendered documentation.
Convenience scripts to simplify some common Sphinx operations, such as rendering the content.
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.
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:

[image: Freshly created documentation of Lumache] [image] Freshly created documentation of Lumache.UNINDENT

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

First steps to document your project using Sphinx

Building your HTML documentation

The index.rst file that sphinx-quickstart created has some content already, and it gets rendered as the front page of your HTML documentation. It is written in reStructuredText, a powerful markup language.

Modify the file as follows:

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!

Building your documentation in other formats

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:

To quickly display a complete list of possible output formats, plus some extra useful commands, you can run make help.


Each output format has some specific configuration options that you can tune, including EPUB. For instance, the default value of epub_show_urls is inline, which means that, by default, URLs are shown right after the corresponding link, in parentheses. You can change that behavior by adding the following code at the end of your conf.py:

# EPUB options
epub_show_urls = 'footnote'


With this configuration value, and after running make epub again, you will notice that URLs appear now as footnotes, which avoids cluttering the text. Sweet! Read on to explore other ways to customize Sphinx.

NOTE:

Generating a PDF using Sphinx can be done running make latexpdf, provided that the system has a working LaTeX installation, as explained in the documentation of sphinx.builders.latex.LaTeXBuilder. Although this is perfectly feasible, such installations are often big, and in general LaTeX requires careful configuration in some cases, so PDF generation is out of scope for this tutorial.


More Sphinx customization

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

Enabling a built-in extension

In addition to these configuration values, you can customize Sphinx even more by using 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


Using a third-party HTML theme

Themes, on the other hand, are a way to customize the appearance of your documentation. Sphinx has several builtin themes, and there are also third-party ones.

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:

[image: HTML documentation of Lumache with the Furo theme] [image] HTML documentation of Lumache with the Furo theme.UNINDENT

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

Narrative documentation in Sphinx

Structuring your documentation across multiple pages

The file index.rst created by sphinx-quickstart is the root document, whose main function is to serve as a welcome page and to contain the root of the "table of contents tree" (or toctree). Sphinx allows you to assemble a project from different files, which is helpful when the project grows.

As an example, create a new file docs/source/usage.rst (next to index.rst) with these contents:

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:

Documents outside a toctree will result in WARNING: document isn't included in any toctree messages during the build process, and will be unreachable for users.


Adding cross-references

One powerful feature of Sphinx is the ability to seamlessly add 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!

Describing code in Sphinx

In the previous sections of the tutorial you can read how to write narrative or prose documentation in Sphinx. In this section you will describe code objects instead.

Sphinx supports documenting code objects in several languages, namely Python, C, C++, JavaScript, and reStructuredText. Each of them can be documented using a series of directives and roles grouped by domain. For the remainder of the tutorial you will use the Python domain, but all the concepts seen in this section apply for the other domains as well.

Python

Documenting Python objects

Sphinx offers several roles and directives to document Python objects, all grouped together in the Python domain. For example, you can use the py:function directive to document a Python function, as follows:

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:

[image: HTML result of documenting a Python function in Sphinx] [image] The rendered result of documenting a Python function in Sphinx.UNINDENT

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.


Cross-referencing Python objects

By default, most of these directives generate entities that can be cross-referenced from any part of the documentation by using a corresponding role. For the case of functions, you can use py:func for that, as follows:

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:

[image: HTML result of documenting a Python function in Sphinx with cross-references] [image] HTML result of documenting a Python function in Sphinx with cross-references.UNINDENT

Beautiful, isn't it?

Including doctests in your documentation

Since you are now describing code from a Python library, it will become useful to keep both the documentation and the code as synchronized as possible. One of the ways to do that in Sphinx is to include code snippets in the documentation, called doctests, that are executed when the documentation is built.

To demonstrate doctests and other Sphinx features covered in this tutorial, Sphinx will need to be able to import the code. To achieve that, write this at the beginning of conf.py:

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.

Other languages (C, C++, others)

Documenting and cross-referencing objects

Sphinx also supports documenting and cross-referencing objects written in other programming languages. There are four additional built-in domains: C, C++, JavaScript, and reStructuredText. Third-party extensions may define domains for more languages, such as

  • Fortran,
  • 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:

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.

Automatic documentation generation from code

In the previous section of the tutorial you manually documented a Python function in Sphinx. However, the description was out of sync with the code itself, since the function signature was not the same. Besides, it would be nice to reuse Python docstrings in the documentation, rather than having to write the information in two places.

Fortunately, the autodoc extension provides this functionality.

Reusing signatures and docstrings with autodoc

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.

Generating comprehensive API references

While using sphinx.ext.autodoc makes keeping the code and the documentation in sync much easier, it still requires you to write an auto* directive for every object you want to document. Sphinx provides yet another level of automation: the autosummary extension.

The autosummary directive generates documents that contain all the necessary autodoc directives. To use it, first enable the autosummary extension:

docs/source/conf.py

extensions = [

'sphinx.ext.duration',
'sphinx.ext.doctest',
'sphinx.ext.autodoc',
'sphinx.ext.autosummary', ]


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

docs/source/api.rst

API
===
.. autosummary::

:toctree: generated
lumache


Remember to include the new document in the root toctree:

docs/source/index.rst

Contents
--------
.. toctree::

usage
api


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

  • api.html, corresponding to docs/source/api.rst and containing a table with the objects you included in the autosummary directive (in this case, only one).
  • generated/lumache.html, corresponding to a newly created reST file generated/lumache.rst and containing a summary of members of the module, in this case one function and one exception.

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

Each of the links in the summary page will take you to the places where you originally used the corresponding autodoc directive, in this case in the usage.rst document.

NOTE:

The generated files are based on Jinja2 templates that can be customized, but that is out of scope for this tutorial.


Appendix: Deploying a Sphinx project online

When you are ready to show your documentation project to the world, there are many options available to do so. Since the HTML generated by Sphinx is static, you can decouple the process of building your HTML documentation from hosting such files in the platform of your choice. You will not need a sophisticated server running Python: virtually every web hosting service will suffice.

Therefore, the challenge is less how or where to serve the static HTML, but rather how to pick a workflow that automatically updates the deployed documentation every time there is a change in the source files.

The following sections describe some of the available options to deploy your online documentation, and give some background information. If you want to go directly to the practical part, you can skip to Publishing your documentation sources.

Sphinx-friendly deployment options

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

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

Embracing the "Docs as Code" philosophy

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

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

Publishing your documentation sources

GitHub

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

GitLab

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

1.
Sign up for a GitLab account.
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.

Publishing your HTML documentation

Read the Docs

Read the Docs offers integration with both GitHub and GitLab. The quickest way of getting started is to follow 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 Sign up for Read the Docs. If you choose GitLab instead, the process is similar.

GitHub Pages

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

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

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

.gitlab-ci.yml

stages:

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


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

1.
Install the necessary dependencies.
2.
Build the HTML documentation using Sphinx.
3.
Move the output to a known artifacts location.

NOTE:

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


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

Where to go from here

This tutorial covered the very first steps to create a documentation project with Sphinx. To continue learning more about Sphinx, check out the rest of the documentation.

USER GUIDES

These sections cover various topics in using and extending Sphinx for various use-cases. They are a comprehensive guide to using Sphinx in many contexts and assume more knowledge of Sphinx. If you are new to Sphinx, we recommend starting with Get started.

Using Sphinx

This guide serves to demonstrate how one can get started with Sphinx and covers everything from installing Sphinx and configuring your first Sphinx project to using some of the advanced features Sphinx provides out-of-the-box. If you are looking for guidance on extending Sphinx, refer to Writing Sphinx Extensions.

reStructuredText

reStructuredText (reST) is the default plaintext markup language used by both Docutils and Sphinx. Docutils provides the basic reStructuredText syntax, while Sphinx extends this to support additional functionality.

The below guides go through the most important aspects of reST. For the authoritative reStructuredText reference, refer to the docutils documentation.

reStructuredText Primer

reStructuredText is the default plaintext markup language used by Sphinx. This section is a brief introduction to reStructuredText (reST) concepts and syntax, intended to provide authors with enough information to author documents productively. Since reST was designed to be a simple, unobtrusive markup language, this will not take too long.

SEE ALSO:

The authoritative reStructuredText User Documentation. The "ref" links in this document link to the description of the individual constructs in the reST reference.


Paragraphs

The paragraph (ref) is the most basic block in a reST document. Paragraphs are simply chunks of text separated by one or more blank lines. As in Python, indentation is significant in reST, so all lines of the same paragraph must be left-aligned to the same level of indentation.

Inline markup

The standard reST inline markup is quite simple: use

  • one asterisk: *text* for emphasis (italics),
  • two asterisks: **text** for strong emphasis (boldface), and
  • backquotes: ``text`` for code samples.

If asterisks or backquotes appear in running text and could be confused with inline markup delimiters, they have to be escaped with a backslash.

Be aware of some restrictions of this markup:

  • it may not be nested,
  • content may not start or end with whitespace: * text* is wrong,
  • it must be separated from surrounding text by non-word characters. Use a backslash escaped space to work around that: thisis\ *one*\ word.

These restrictions may be lifted in future versions of the docutils.

It is also possible to replace or expand upon some of this inline markup with roles. Refer to Roles for more information.

Lists and Quote-like blocks

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 blocks

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

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


Tables

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:

There must be a space between the link text and the opening < for the URL.


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

This is a paragraph that contains `a link`_.
.. _a link: https://domain.invalid/


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

Sections

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

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


Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, this convention is used in Python Developer's Guide for documenting which you may follow:

  • # with overline, for parts
  • * with overline, for chapters
  • = for sections
  • - for subsections
  • ^ for subsubsections
  • " for paragraphs

Of course, you are free to use your own marker characters (see the reST documentation), and use a deeper nesting level, but keep in mind that most target formats (HTML, LaTeX) have a limited supported nesting depth.

Field Lists

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.

Roles

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

"Explicit markup" (ref) is used in reST for most constructs that need special handling, such as footnotes, specially-highlighted paragraphs, comments, and generic directives.

An explicit markup block begins with a line starting with .. followed by whitespace and is terminated by the next paragraph at the same level of indentation. (There needs to be a blank line between explicit markup and normal paragraphs. This may all sound a bit complicated, but it is intuitive enough when you write it.)

Directives

A directive (ref) is a generic block of explicit markup. Along with roles, it is one of the extension mechanisms of reST, and Sphinx makes heavy use of it.

Docutils supports the following directives:

  • Admonitions: attention, caution, danger, error, hint, important, note, tip, warning and the generic admonition. (Most themes style only "note" and "warning" specially.)
  • Images:
  • image (see also Images below)
  • figure (an image with caption and optional legend)

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

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

Special directives:
  • raw (include raw target-format markup)
  • include (include reStructuredText from another file) -- in Sphinx, when given an absolute include file path, this directive takes it as relative to the source directory
  • class (assign a class attribute to the next element)

    NOTE:

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



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

Influencing markup:
  • default-role (set a new default role)
  • role (create a new role)

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


WARNING:

Do not use the directives sectnum, header and footer.


Directives added by Sphinx are described in Directives.

Basically, a directive consists of a name, arguments, options and content. (Keep this terminology in mind, it is used in the next chapter describing custom directives.) Looking at this example,

.. function:: foo(x)

foo(y, z)
:module: some.module.name
Return a line of text input from the user.


function is the directive name. It is given two arguments here, the remainder of the first line and the second line, as well as one option module (as you can see, options are given in the lines immediately following the arguments and indicated by the colons). Options must be indented to the same level as the directive content.

The directive content follows after a blank line and is indented relative to the directive start or if options are present, by the same amount as the options.

Be careful as the indent is not a fixed number of whitespace, e.g. three, but any number whitespace. This can be surprising when a fixed indent is used throughout the document and can make a difference for directives which are sensitive to whitespace. Compare:

.. code-block::

:caption: A cool example
The output of this line starts with four spaces. .. code-block::
The output of this line has no spaces at the beginning.


In the first code block, the indent for the content was fixated by the option line to three spaces, consequently the content starts with four spaces. In the latter the indent was fixed by the content itself to seven spaces, thus it does not start with a space.

Images

reST supports an image directive (ref), used like so:

.. image:: gnu.png

(options)


When used within Sphinx, the file name given (here gnu.png) must either be relative to the source file, or absolute which means that they are relative to the top source directory. For example, the file sketch/spam.rst could refer to the image images/spam.png as ../images/spam.png or /images/spam.png.

Sphinx will automatically copy image files over to a subdirectory of the output directory on building (e.g. the _static directory for HTML output.)

Interpretation of image size options (width and height) is as follows: if the size has no unit or the unit is pixels, the given size will only be respected for output channels that support pixels. Other units (like pt for points) will be used for HTML and LaTeX output (the latter replaces pt by bp as this is the TeX unit such that 72bp=1in).

Sphinx extends the standard docutils behavior by allowing an asterisk for the extension:

.. image:: gnu.*


Sphinx then searches for all images matching the provided pattern and determines their type. Each builder then chooses the best image out of these candidates. For instance, if the file name gnu.* was given and two files gnu.pdf and gnu.png existed in the source tree, the LaTeX builder would choose the former, while the HTML builder would prefer the latter. Supported image types and choosing priority are defined at Builders.

Note that image file names should not contain spaces.

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

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

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

Footnotes

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 ([#]_).

Citations

Standard reST citations (ref) are supported, with the additional feature that they are "global", i.e. all citations can be referenced from all files. Use them like so:

Lorem ipsum [Ref]_ dolor sit amet.
.. [Ref] Book or article reference, URL or whatever.


Citation usage is similar to footnote usage, but with a label that is not numeric or begins with #.

Substitutions

reST supports "substitutions" (ref), which are pieces of text and/or markup referred to in the text by |name|. They are defined like footnotes with explicit markup blocks, like this:

.. |name| replace:: replacement *text*


or this:

.. |caution| image:: warning.png

:alt: Warning!


See the reST reference for substitutions for details.

If you want to use some substitutions for all documents, put them into rst_prolog or rst_epilog or put them into a separate file and include it into all documents you want to use them in, using the include directive. (Be sure to give the include file a file name extension differing from that of other source files, to avoid Sphinx finding it as a standalone document.)

Sphinx defines some default substitutions, see Substitutions.

Comments

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.


HTML Metadata

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.

Source encoding

Since the easiest way to include special characters like em dashes or copyright signs in reST is to directly write them as Unicode characters, one has to specify an encoding. Sphinx assumes source files to be encoded in UTF-8 by default; you can change this with the source_encoding config value.

Gotchas

There are some problems one commonly runs into while authoring reST documents:

  • Separation of inline markup: As said above, inline markup spans must be separated from the surrounding text by non-word characters, you have to use a backslash-escaped space to get around that. See the reference for the details.
  • No nested inline markup: Something like *see :func:`foo`* is not possible.

Roles

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

NOTE:

The default role (`content`) has no special meaning by default. You are free to use it for anything you like, e.g. variable names; use the default_role config value to set it to a known role -- the any role to find anything or the py:obj role to find Python objects are very useful for this.


See Domains for roles added by domains.

Cross-referencing syntax

See Cross-referencing syntax.

Cross-reference roles include:

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

Inline code highlighting

: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

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

Other semantic markup

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


Todo

Is this not part of the standard domain?



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

For example: curl


:regexp:
A regular expression. Quotes should not be included.

For example: ([abc])+


:samp:
A piece of literal text, such as code. Within the contents, you can use curly braces to indicate a "variable" part, as in file. For example, in :samp:`print(1+{variable})`, the part variable would be emphasized: print(1+variable)

If you don't need the "variable part" indication, use the standard code role instead.

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


There is also an index role to generate index entries.

The following roles generate external links:

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

For example: PEP 8


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

For example: RFC 2324


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

Substitutions

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.

Directives

As previously discussed, a directive is a generic block of explicit markup. While Docutils provides a number of directives, Sphinx provides many more and uses directives as one of the primary extension mechanisms.

See Domains for roles added by domains.

SEE ALSO:

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


Table of contents

Since reST does not have facilities to interconnect several documents, or split documents into multiple output files, Sphinx uses a custom directive to add relations between the single files the documentation is made of, as well as tables of contents. The toctree directive is the central element.

NOTE:

Simple "inclusion" of one file in another can be done with the include directive.


NOTE:

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


.. toctree::
This directive inserts a "TOC tree" at the current location, using the individual TOCs (including "sub-TOC trees") of the documents given in the directive body. Relative document names (not beginning with a slash) are relative to the document the directive occurs in, absolute names are relative to the source directory. A numeric maxdepth option may be given to indicate the depth of the tree; by default, all levels are included. [1]

The representation of "TOC tree" is changed in each output format. The builders that output multiple files (ex. HTML) treat it as a collection of hyperlinks. On the other hand, the builders that output a single file (ex. LaTeX, man page, etc.) replace it with the content of the documents on the TOC tree.

Consider this example (taken from the Python docs' library reference index):

.. toctree::

:maxdepth: 2
intro
strings
datatypes
numeric
(many more documents listed here)


This accomplishes two things:

  • Tables of contents from all those documents are inserted, with a maximum depth of two, that means one nested heading. toctree directives in those documents are also taken into account.
  • Sphinx knows the relative order of the documents intro, strings and so forth, and it knows that they are children of the shown document, the library index. From this information it generates "next chapter", "previous chapter" and "parent chapter" links.

Entries

Document titles in the toctree will be automatically read from the title of the referenced document. If that isn't what you want, you can specify an explicit title and target using a similar syntax to reST hyperlinks (and Sphinx's cross-referencing syntax). This looks like:

.. toctree::

intro
All about strings <strings>
datatypes


The second line above will link to the strings document, but will use the title "All about strings" instead of the title of the strings document.

You can also add external links, by giving an HTTP URL instead of a document name.

Section numbering

If you want to have section numbers even in HTML output, give the toplevel toctree a numbered option. For example:

.. toctree::

:numbered:
foo
bar


Numbering then starts at the heading of foo. Sub-toctrees are automatically numbered (don't give the numbered flag to those).

Numbering up to a specific depth is also possible, by giving the depth as a numeric argument to numbered.

Additional options

You can use the caption option to provide a toctree caption and you can use the name option to provide an implicit target name that can be referenced by using ref:

.. toctree::

:caption: Table of Contents
:name: mastertoc
foo


If you want only the titles of documents in the tree to show up, not other headings of the same level, you can use the titlesonly option:

.. toctree::

:titlesonly:
foo
bar


You can use "globbing" in toctree directives, by giving the glob flag option. All entries are then matched against the list of available documents, and matches are inserted into the list alphabetically. Example:

.. toctree::

:glob:
intro*
recipe/*
*


This includes first all documents whose names start with intro, then all documents in the recipe folder, then all remaining documents (except the one containing the directive, of course.) [2]

The special entry name self stands for the document containing the toctree directive. This is useful if you want to generate a "sitemap" from the toctree.

You can use the reversed flag option to reverse the order of the entries in the list. This can be useful when using the glob flag option to reverse the ordering of the files. Example:

.. toctree::

:glob:
:reversed:
recipe/*


You can also give a "hidden" option to the directive, like this:

.. toctree::

:hidden:
doc_1
doc_2


This will still notify Sphinx of the document hierarchy, but not insert links into the document at the location of the directive -- this makes sense if you intend to insert these links yourself, in a different style, or in the HTML sidebar.

In cases where you want to have only one top-level toctree and hide all other lower level toctrees you can add the "includehidden" option to the top-level toctree entry:

.. toctree::

:includehidden:
doc_1
doc_2


All other toctree entries can then be eliminated by the "hidden" option.

In the end, all documents in the source directory (or subdirectories) must occur in some toctree directive; Sphinx will emit a warning if it finds a file that is not included, because that means that this file will not be reachable through standard navigation.

Use exclude_patterns to explicitly exclude documents or directories from building completely. Use the "orphan" metadata to let a document be built, but notify Sphinx that it is not reachable via a toctree.

The "root document" (selected by root_doc) is the "root" of the TOC tree hierarchy. It can be used as the documentation's main page, or as a "full table of contents" if you don't give a maxdepth option.

Changed in version 0.3: Added "globbing" option.

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

Changed in version 1.0: Added "titlesonly" option.

Changed in version 1.1: Added numeric argument to "numbered".

Changed in version 1.2: Added "includehidden" option.

Changed in version 1.3: Added "caption" and "name" option.


Special names

Sphinx reserves some document names for its own use; you should not try to create documents with these names -- it will cause problems.

The special document names (and pages generated for them) are:

  • genindex, modindex, search

    These are used for the general index, the Python module index, and the search page, respectively.

    The general index is populated with entries from modules, all index-generating object descriptions, and from index directives.

    The Python module index contains one entry per py:module directive.

    The search page contains a form that uses the generated JSON search index and JavaScript to full-text search the generated documents for search words; it should work on every major browser that supports modern JavaScript.

  • every name beginning with _

    Though few such names are currently used by Sphinx, you should not create documents or document-containing directories with such names. (Using _ as a prefix for a custom template directory is fine.)


WARNING:

Be careful with unusual characters in filenames. Some formats may interpret these characters in unexpected ways:
  • Do not use the colon : for HTML based formats. Links to other parts may not work.
  • Do not use the plus + for the ePub format. Some resources may not be found.



Paragraph-level markup

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

.. note::
An especially important bit of information about an API that a user should be aware of when using whatever bit of API the note pertains to. The content of the directive should be written in complete sentences and include all appropriate punctuation.

Example:

.. note::

This function is not suitable for sending spam e-mails.



.. warning::
An important bit of information about an API that a user should be very aware of when using whatever bit of API the warning pertains to. The content of the directive should be written in complete sentences and include all appropriate punctuation. This differs from note in that it is recommended over note for information regarding security.

.. versionadded:: version
This directive documents the version of the project which added the described feature to the library or C API. When this applies to an entire module, it should be placed at the top of the module section before any prose.

The first argument must be given and is the version in question; you can add a second argument consisting of a brief explanation of the change.

Example:

.. versionadded:: 2.5

The *spam* parameter.


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


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

.. deprecated:: version
Similar to versionchanged, but describes when the feature was deprecated. An explanation can also be given, for example to inform the reader what should be used instead. Example:

.. deprecated:: 3.1

Use :func:`spam` instead.



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

.. versionremoved:: 4.0

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


Added in version 7.3.


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

The seealso directive is typically placed in a section just before any subsections. For the HTML output, it is shown boxed off from the main flow of the text.

The content of the seealso directive should be a reST definition list. Example:

.. seealso::

Module :py:mod:`zipfile`
Documentation of the :py:mod:`zipfile` standard module.
`GNU tar manual, Basic Tar Format <https://link>`_
Documentation for tar archive files, including GNU tar extensions.


There's also a "short form" allowed that looks like this:

.. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`


Added in version 0.5: The short form.


.. rubric:: title
This directive creates a paragraph heading that is not used to create a table of contents node.

NOTE:

If the title of the rubric is "Footnotes" (or the selected language's equivalent), this rubric is ignored by the LaTeX writer, since it is assumed to only contain footnote definitions and therefore would create an empty heading.



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

.. centered:: LICENSE AGREEMENT


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


.. hlist::
This directive must contain a bullet list. It will transform it into a more compact list by either distributing more than one item horizontally, or reducing spacing between items, depending on the builder.

For builders that support the horizontal distribution, there is a columns option that specifies the number of columns; it defaults to 2. Example:

.. hlist::

:columns: 3
* A list of
* short items
* that should be
* displayed
* horizontally


Added in version 0.6.


Showing code examples

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

  • using reST doctest blocks;
  • using reST literal blocks, optionally in combination with the highlight directive;
  • using the code-block directive;
  • and using the literalinclude directive.

Doctest blocks can only be used to show interactive Python sessions, while the remaining three can be used for other languages. Of these three, literal blocks are useful when an entire document, or at least large sections of it, use code blocks with the same syntax and which should be styled in the same manner. On the other hand, the code-block directive makes more sense when you want more fine-tuned control over the styling of each block or when you have a document containing code blocks using multiple varied syntaxes. Finally, the literalinclude directive is useful for including entire code files in your documentation.

In all cases, Syntax highlighting is provided by Pygments. When using literal blocks, this is configured using any highlight directives in the source file. When a highlight directive is encountered, it is used until the next highlight directive is encountered. If there is no highlight directive in the file, the global highlighting language is used. This defaults to python but can be configured using the highlight_language config value. The following values are supported:

  • none (no highlighting)
  • default (similar to python3 but with a fallback to none without warning highlighting fails; the default when highlight_language isn't set)
  • guess (let Pygments guess the lexer based on contents, only works with certain well-recognizable languages)
  • python
  • rest
  • c
  • ... and any other lexer alias that Pygments supports

If highlighting with the selected language fails (i.e. Pygments emits an "Error" token), the block is not highlighted in any way.

IMPORTANT:

The list of lexer aliases supported is tied to the Pygment version. If you want to ensure consistent highlighting, you should fix your version of Pygments.


.. highlight:: language
Example:

.. highlight:: c


This language is used until the next highlight directive is encountered. As discussed previously, language can be any lexer alias supported by Pygments.

options

:linenothreshold: threshold (number (optional))
Enable to generate line numbers for code blocks.

This option takes an optional number as threshold parameter. If any threshold given, the directive will produce line numbers only for the code blocks longer than N lines. If not given, line numbers will be produced for all of code blocks.

Example:

.. highlight:: python

:linenothreshold: 5



:force: (no value)
If given, minor errors on highlighting are ignored.

Added in version 2.1.



.. code-block:: [language]
.. sourcecode:: [language]
Example:

.. code-block:: ruby

Some Ruby code.


The directive's alias name sourcecode works as well. This directive takes a language name as an argument. It can be any lexer alias supported by Pygments. If it is not given, the setting of highlight directive will be used. If not set, highlight_language will be used. To display a code example inline within other text, rather than as a separate block, you can use the code role instead.

Changed in version 2.0: The language argument becomes optional.

options

:linenos: (no value)
Enable to generate line numbers for the code block:

.. code-block:: ruby

:linenos:
Some more Ruby code.



:lineno-start: number (number)
Set the first line number of the code block. If present, linenos option is also automatically activated:

.. code-block:: ruby

:lineno-start: 10
Some more Ruby code, with line numbering starting at 10.


Added in version 1.3.


:emphasize-lines: line numbers (comma separated numbers)
Emphasize particular lines of the code block:

.. code-block:: python

:emphasize-lines: 3,5
def some_function():
interesting = False
print('This line is highlighted.')
print('This one is not...')
print('...but this one is.')


Added in version 1.1.

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


:caption: caption of code block (text)
Set a caption to the code block.

Added in version 1.3.


:name: a label for hyperlink (text)
Define implicit target name that can be referenced by using ref. For example:

.. code-block:: python

:caption: this.py
:name: this-py
print('Explicit is better than implicit.')


In order to cross-reference a code-block using either the ref or the numref role, it is necessary that both name and caption be defined. The argument of name can then be given to numref to generate the cross-reference. Example:

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


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

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


Added in version 1.3.


:class: class names (a list of class names separated by spaces)
The class name of the graph.

Added in version 1.4.


:dedent: number (number or no value)
Strip indentation characters from the code block. When number given, leading N characters are removed. When no argument given, leading spaces are removed via textwrap.dedent(). For example:

.. code-block:: ruby

:linenos:
:dedent: 4
some ruby code


Added in version 1.3.

Changed in version 3.5: Support automatic dedent.


:force: (no value)
If given, minor errors on highlighting are ignored.

Added in version 2.1.



.. literalinclude:: filename
Longer displays of verbatim text may be included by storing the example text in an external file containing only plain text. The file may be included using the literalinclude directive. [3] For example, to include the Python source file example.py, use:

.. literalinclude:: example.py


The file name is usually relative to the current file's path. However, if it is absolute (starting with /), it is relative to the top source directory.

Additional options

Like code-block, the directive supports the linenos flag option to switch on line numbers, the lineno-start option to select the first line number, the emphasize-lines option to emphasize particular lines, the name option to provide an implicit target name, the dedent option to strip indentation characters for the code block, and a language option to select a language different from the current file's standard language. In addition, it supports the caption option; however, this can be provided with no argument to use the filename as the caption. Example with options:

.. literalinclude:: example.rb

:language: ruby
:emphasize-lines: 12,15-18
:linenos:


Tabs in the input are expanded if you give a tab-width option with the desired tab width.

Include files are assumed to be encoded in the source_encoding. If the file has a different encoding, you can specify it with the encoding option:

.. literalinclude:: example.py

:encoding: latin-1


The directive also supports including only parts of the file. If it is a Python module, you can select a class, function or method to include using the pyobject option:

.. literalinclude:: example.py

:pyobject: Timer.start


This would only include the code lines belonging to the start() method in the Timer class within the file.

Alternately, you can specify exactly which lines to include by giving a lines option:

.. literalinclude:: example.py

:lines: 1,3,5-10,20-


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

Another way to control which part of the file is included is to use the start-after and end-before options (or only one of them). If start-after is given as a string option, only lines that follow the first line containing that string are included. If end-before is given as a string option, only lines that precede the first lines containing that string are included. The start-at and end-at options behave in a similar way, but the lines containing the matched string are included.

start-after/start-at and end-before/end-at can have same string. start-after/start-at filter lines before the line that contains option string (start-at will keep the line). Then end-before/end-at filter lines after the line that contains option string (end-at will keep the line and end-before skip the first line).

NOTE:

If you want to select only [second-section] of ini file like the following, you can use :start-at: [second-section] and :end-before: [third-section]:

[first-section]
var_in_first=true
[second-section]
var_in_second=true
[third-section]
var_in_third=true


Useful cases of these option is working with tag comments. :start-after: [initialize] and :end-before: [initialized] options keep lines between comments:

if __name__ == "__main__":

# [initialize]
app.start(":8000")
# [initialized]




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

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

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

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

.. literalinclude:: example.py

:diff: example.py.orig


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

A force option can ignore minor errors on highlighting.

Changed in version 0.4.3: Added the encoding option.

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

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

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

Changed in version 1.4: Added the class option.

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

Changed in version 1.6: With both start-after and lines in use, the first line as per start-after is considered to be with line number 1 for lines.

Changed in version 2.1: Added the force option.

Changed in version 3.5: Support automatic dedent.


Glossary

.. glossary::
This directive must contain a reST definition-list-like markup with terms and definitions. The definitions will then be referenceable with the term role. Example:

.. glossary::

environment
A structure where information about all documents under the root is
saved, and used for cross-referencing. The environment is pickled
after the parsing stage, so that successive runs only need to read
and parse new and changed documents.
source directory
The directory which, including its subdirectories, contains all
source files for one Sphinx project.


In contrast to regular definition lists, multiple terms per entry are allowed, and inline markup is allowed in terms. You can link to all of the terms. For example:

.. glossary::

term 1
term 2
Definition of both terms.


(When the glossary is sorted, the first term determines the sort order.)

If you want to specify "grouping key" for general index entries, you can put a "key" as "term : key". For example:

.. glossary::

term 1 : A
term 2 : B
Definition of both terms.


Note that "key" is used for grouping key as is. The "key" isn't normalized; key "A" and "a" become different groups. The whole characters in "key" is used instead of a first character; it is used for "Combining Character Sequence" and "Surrogate Pairs" grouping key.

In i18n situation, you can specify "localized term : key" even if original text only have "term" part. In this case, translated "localized term" will be categorized in "key" group.

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

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

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

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


Meta-information markup

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

Index-generating markup

Sphinx automatically creates index entries from all object descriptions (like functions, classes or attributes) like discussed in Domains.

However, there is also explicit markup available, to make the index more comprehensive and enable index entries in documents where information is not mainly contained in information units, such as the language reference.

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

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.

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.

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.

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

Like see, but inserts 'see also' instead of 'see'.
These deprecated shortcuts all create two index entries. For example, module: hashlib creates the entries module; hashlib and hashlib; module.

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

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


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

.. index:: Python


and one page contains

.. index:: ! Python


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

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

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


This creates four index entries.

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

options

:name: a label for hyperlink (text)
Define implicit target name that can be referenced by using ref. For example:

.. index:: Python

:name: py-index



Added in version 3.0.


:index:
While the index directive is a block-level markup and links to the beginning of the next paragraph, there is also a corresponding role that sets the link target directly where it is used.

The content of the role can be a simple phrase, which is then kept in the text and used as an index entry. It can also be a combination of text and index entry, styled like with explicit targets of cross-references. In that case, the "target" part can be a full entry as described for the directive above. For example:

This is a normal reST :index:`paragraph` that contains several
:index:`index entries <pair: index; entry>`.


Added in version 1.1.


Including content based on tags

.. only:: <expression>
Include the content of the directive only if the expression is true. The expression should consist of tags, like this:

.. only:: html and draft


Undefined tags are false, defined tags (via the -t command-line option or within conf.py, see here) are true. Boolean expressions, also using parentheses (like (latex or html) and draft) are supported.

The format and the name of the current builder (html, latex or text) are always set as a tag [4]. To make the distinction between format and name explicit, they are also added with the prefix format_ and builder_, e.g. the epub builder defines the tags html, epub, format_html and builder_epub.

These standard tags are set after the configuration file is read, so they are not available there.

All tags must follow the standard Python identifier syntax as set out in the Identifiers and keywords documentation. That is, a tag expression may only consist of tags that conform to the syntax of Python variables. In ASCII, this consists of the uppercase and lowercase letters A through Z, the underscore _ and, except for the first character, the digits 0 through 9.

Added in version 0.6.

Changed in version 1.2: Added the name of the builder and the prefixes.

WARNING:

This directive is designed to control only content of document. It could not control sections, labels and so on.



Tables

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.


Math

The input language for mathematics is LaTeX markup. This is the de-facto standard for plain-text math notation and has the added advantage that no further translation is necessary when building LaTeX output.

Keep in mind that when you put math markup in Python docstrings read by autodoc, you either have to double all backslashes, or use Python raw strings (r"raw").

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

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

.. math::

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


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

.. math::

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


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

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

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


Normally, equations are not numbered. If you want your equation to get a number, use the label option. When given, it selects an internal label for the equation, by which it can be cross-referenced, and causes an equation number to be issued. See eq for an example. The numbering style depends on the output format.

There is also an option nowrap that prevents any wrapping of the given math in a math environment. When you give this option, you must make sure yourself that the math is properly set up. For example:

.. math::

:nowrap:
\begin{eqnarray}
y & = & ax^2 + bx + c \\
f(x) & = & x^2 + 2xy + y^2
\end{eqnarray}



SEE ALSO:

Math support for HTML outputs in Sphinx
Rendering options for math with HTML builders.
latex_engine
Explains how to configure LaTeX builder to support Unicode literals in math mark-up.



Grammar production displays

Special markup is available for displaying the productions of a formal grammar. The markup is simple and does not attempt to model all aspects of BNF (or any derived forms), but provides enough to allow context-free grammars to be displayed in a way that causes uses of a symbol to be rendered as hyperlinks to the definition of the symbol. There is this directive:

.. productionlist:: [productionGroup]
This directive is used to enclose a group of productions. Each production is given on a single line and consists of a name, separated by a colon from the following definition. If the definition spans multiple lines, each continuation line must begin with a colon placed at the same column as in the first line. Blank lines are not allowed within productionlist directive arguments.

The definition can contain token names which are marked as interpreted text (e.g., "sum ::= `integer` "+" `integer`") -- this generates cross-references to the productions of these tokens. Outside of the production list, you can reference to token productions using token.

The productionGroup argument to productionlist serves to distinguish different sets of production lists that belong to different grammars. Multiple production lists with the same productionGroup thus define rules in the same scope.

Inside of the production list, tokens implicitly refer to productions from the current group. You can refer to the production of another grammar by prefixing the token with its group name and a colon, e.g, "otherGroup:sum". If the group of the token should not be shown in the production, it can be prefixed by a tilde, e.g., "~otherGroup:sum". To refer to a production from an unnamed grammar, the token should be prefixed by a colon, e.g., ":sum".

Outside of the production list, if you have given a productionGroup argument you must prefix the token name in the cross-reference with the group name and a colon, e.g., "myGroup:sum" instead of just "sum". If the group should not be shown in the title of the link either an explicit title can be given (e.g., "myTitle <myGroup:sum>"), or the target can be prefixed with a tilde (e.g., "~myGroup:sum").

Note that no further reST parsing is done in the production, so that you don't have to escape * or | characters.


The following is an example taken from the Python Reference Manual:

.. productionlist::

try_stmt: try1_stmt | try2_stmt
try1_stmt: "try" ":" `suite`
: ("except" [`expression` ["," `target`]] ":" `suite`)+
: ["else" ":" `suite`]
: ["finally" ":" `suite`]
try2_stmt: "try" ":" `suite`
: "finally" ":" `suite`


FOOTNOTES

[1]
The LaTeX writer only refers the maxdepth option of first toctree directive in the document.
[2]
A note on available globbing syntax: you can use the standard shell constructs *, ?, [...] and [!...] with the feature that these all don't match slashes. A double star ** can be used to match any sequence of characters including slashes.
[3]
There is a standard .. include directive, but it raises errors if the file is not found. This one only emits a warning.
[4]
For most builders name and format are the same. At the moment only builders derived from the html builder distinguish between the builder format and the builder name.

Note that the current builder tag is not available in conf.py, it is only available after the builder is initialized.

Field Lists

As previously discussed, field lists are sequences of fields marked up like this:

:fieldname: Field content


Sphinx extends standard docutils behavior for field lists and adds some extra functionality that is covered in this section.

NOTE:

The values of field lists will be parsed as strings. You cannot use Python collections such as lists or dictionaries.


File-wide metadata

A field list near the top of a file is normally parsed by docutils as the docinfo and shown on the page. However, in Sphinx, a field list preceding any other markup is moved from the docinfo to the Sphinx environment as document metadata, and is not displayed in the output.

NOTE:

A field list appearing after the document title will be part of the docinfo as normal and will be displayed in the output.


Special metadata fields

Sphinx provides custom behavior for bibliographic fields compared to docutils.

At the moment, these metadata fields are recognized:

The maximum depth for a table of contents of this file.

:tocdepth: 2


NOTE:

This metadata effects to the depth of local toctree. But it does not effect to the depth of global toctree. So this would not be change the sidebar of some themes which uses global one.


Added in version 0.4.

If set, the web application won't display a comment form for a page generated from this source file.

:nocomments:


If set, warnings about this file not being included in any toctree will be suppressed.

:orphan:


Added in version 1.0.

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.


MOVED: Domains

MOVED: Basic Markup

See Domains.

MOVED: Python Domain

See The Python Domain.

MOVED: C Domain

See The C Domain.

MOVED: C++ Domain

See The C++ Domain.

MOVED: Standard Domain

See The Standard Domain.

MOVED: JavaScript Domain

See The JavaScript Domain.

MOVED: reStructuredText Domain

See The reStructuredText Domain.

MOVED: Math Domain

See The Mathematics Domain.

MOVED: More domains

See Domains.

Markdown

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

Configuration

To configure your Sphinx project for Markdown support, proceed as follows:

1.
Install the Markdown parser MyST-Parser:

pip install --upgrade myst-parser


2.
Add myst_parser to the list of configured extensions:

extensions = ['myst_parser']


NOTE:

MyST-Parser requires Sphinx 2.1 or newer.


3.
If you want to use Markdown files with extensions other than .md, adjust the source_suffix variable. The following example configures Sphinx to parse all files with the extensions .md and .txt as Markdown:

source_suffix = {

'.rst': 'restructuredtext',
'.txt': 'markdown',
'.md': 'markdown', }


4.
You can further configure MyST-Parser to allow custom syntax that standard CommonMark doesn't support. Read more in the MyST-Parser documentation.

Cross-referencing syntax

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

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

  • You may supply an explicit title and reference target, like in reST direct hyperlinks: :role:`title <target>` will refer to target, but the link text will be title.
  • If you prefix the content with !, no reference/hyperlink will be created.
  • If you prefix the content with ~, the link text will only be the last component of the target. For example, :py:meth:`~Queue.Queue.get` will refer to Queue.Queue.get but only display get as the link text. This does not work with all cross-reference roles, but is domain specific.

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


Cross-referencing anything

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


Cross-referencing objects

These roles are described with their respective domains:

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

Cross-referencing arbitrary locations

:ref:
To support cross-referencing to arbitrary locations in any document, the standard reST labels are used. For this to work label names must be unique throughout the entire documentation. There are two ways in which you can refer to labels:
If you place a label directly before a section title, you can reference to it with :ref:`label-name`. For example:

.. _my-reference-label:
Section to cross-reference
--------------------------
This is the text of the section.
It refers to the section itself, see :ref:`my-reference-label`.


The :ref: role would then generate a link to the section, with the link title being "Section to cross-reference". This works just as well when section and reference are in different source files.

Automatic labels also work with figures. For example:

.. _my-figure:
.. figure:: whatever

Figure caption


In this case, a reference :ref:`my-figure` would insert a reference to the figure with link text "Figure caption".

The same works for tables that are given an explicit caption using the table directive.

Labels that aren't placed before a section title can still be referenced, but you must give the link an explicit title, using this syntax: :ref:`Link title <label-name>`.

NOTE:

Reference labels must start with an underscore. When referencing a label, the underscore must be omitted (see examples above).


Using ref is advised over standard reStructuredText links to sections (like `Section title`_) because it works across files, when section headings are changed, will raise warnings if incorrect, and works for all builders that support cross-references.


Cross-referencing documents

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.


Referencing downloadable files

Added in version 0.6.

:download:
This role lets you link to files within your source tree that are not reST documents that can be viewed, but files that can be downloaded.

When you use this role, the referenced file is automatically marked for inclusion in the output when building (obviously, for HTML output only). All downloadable files are put into a _downloads/<unique hash>/ subdirectory of the output directory; duplicate filenames are handled.

An example:

See :download:`this example script <../example.py>`.


The given filename is usually relative to the directory the current source file is contained in, but if it absolute (starting with /), it is taken as relative to the top source directory.

The example.py file will be copied to the output directory, and a suitable link generated to it.

Not to show unavailable download links, you should wrap whole paragraphs that have this role:

.. only:: builder_html

See :download:`this example script <../example.py>`.



Cross-referencing figures by figure number

Added in version 1.3.

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

:numref:
Link to the specified figures, tables, code-blocks and sections; the standard reST labels are used. When you use this role, it will insert a reference to the figure with link text by its figure number like "Fig. 1.1".

If an explicit link text is given (as usual: :numref:`Image of Sphinx (Fig. %s) <my-figure>`), the link caption will serve as title of the reference. As placeholders, %s and {number} get replaced by the figure number and {name} by the figure caption. If no explicit link text is given, the numfig_format setting is used as fall-back default.

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


Cross-referencing other items of interest

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

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

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

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

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

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

:term:
Reference to a term in a glossary. A glossary is created using the glossary directive containing a definition list with terms and definitions. It does not have to be in the same file as the term markup, for example the Python docs have one global glossary in the glossary.rst file.

If you use a term that's not explained in a glossary, you'll get a warning during build.


Configuration

The configuration directory must contain a file named conf.py. This file (containing Python code) is called the "build configuration file" and contains (almost) all configuration needed to customize Sphinx input and output behavior.

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

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

Important points to note:

  • If not otherwise documented, values must be strings, and their default is the empty string.
  • The term "fully-qualified name" refers to a string that names an importable Python object inside a module; for example, the FQN "sphinx.builders.Builder" means the Builder class in the sphinx.builders module.
  • Remember that document names use / as the path separator and don't contain the file name extension.
  • Since conf.py is read as a Python file, the usual rules apply for encodings and Unicode support.
  • The contents of the config namespace are pickled (so that Sphinx can find out when configuration changes), so it may not contain unpickleable values -- delete them from the namespace with del if appropriate. Modules are removed automatically, so you don't need to del your imports after use.
  • There is a special object named tags available in the config file. It can be used to query and change the tags (see Including content based on tags). Use tags.has('tag') to query, tags.add('tag') and tags.remove('tag') to change. Only tags set via the -t command-line option or via tags.add('tag') can be queried using tags.has('tag'). Note that the current builder tag is not available in conf.py, as it is created after the builder is initialized.

Project information

The documented project's name.

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

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

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


An alias of copyright.

Added in version 3.5.


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

The full project version, used as the replacement for |release| and e.g. in the HTML templates. For example, for the Python documentation, this may be something like 2.6.0rc1.

If you don't need the separation provided between version and release, just set them both to the same value.


General configuration

A list of strings that are module names of extensions. These can be extensions coming with Sphinx (named sphinx.ext.*) or custom ones.

Note that you can extend sys.path within the conf file if your extensions live in another directory -- but make sure you use absolute paths. If your extension path is relative to the configuration directory, use os.path.abspath() like so:

import sys, os
sys.path.append(os.path.abspath('sphinxext'))
extensions = ['extname']


That way, you can load an extension called extname from the subdirectory sphinxext.

The configuration file itself can be an extension; for that, you only need to provide a setup() function in it.


The file extensions of source files. Sphinx considers the files with this suffix as sources. The value can be a dictionary mapping file extensions to file types. For example:

source_suffix = {

'.rst': 'restructuredtext',
'.txt': 'restructuredtext',
'.md': 'markdown', }


By default, Sphinx only supports 'restructuredtext' file type. You can add a new file type using source parser extensions. Please read a document of the extension to know which file type the extension supports.

The value may also be a list of file extensions: then Sphinx will consider that they all map to the 'restructuredtext' file type.

Default is {'.rst': 'restructuredtext'}.

NOTE:

file extensions have to start with a dot (e.g. .rst).


Changed in version 1.3: Can now be a list of extensions.

Changed in version 1.8: Support file type mapping


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

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


If given, a dictionary of parser classes for different source suffices. The keys are the suffix, the values can be either a class or a string giving a fully-qualified name of a parser class. The parser class can be either docutils.parsers.Parser or sphinx.parsers.Parser. Files with a suffix that is not in the dictionary will be parsed with the default reStructuredText parser.

For example:

source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}


NOTE:

Refer to Markdown for more information on using Markdown with Sphinx.


Added in version 1.3.

Deprecated since version 1.8: Now Sphinx provides an API Sphinx.add_source_parser() to register a source parser. Please use it instead.


Same as root_doc.

Changed in version 4.0: Renamed master_doc to root_doc.


The document name of the "root" document, that is, the document that contains the root toctree directive. Default is 'index'.

Changed in version 2.0: The default is changed to 'index' from 'contents'.

Changed in version 4.0: Renamed root_doc from master_doc.


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

Example patterns:

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

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

Added in version 1.0.


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

Example patterns:

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

Added in version 5.1.


A list of paths that contain extra templates (or templates that overwrite builtin/theme-specific templates). Relative paths are taken as relative to the configuration directory.

Changed in version 1.3: As these files are not meant to be built, they are automatically added to exclude_patterns.


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

A string of reStructuredText that will be included at the end of every source file that is read. This is a possible place to add substitutions that should be available in every file (another being rst_prolog). An example:

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


Added in version 0.6.


A string of reStructuredText that will be included at the beginning of every source file that is read. This is a possible place to add substitutions that should be available in every file (another being rst_epilog). An example:

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


Added in version 1.0.


The name of the default domain. Can also be None to disable a default domain. The default is 'py'. Those objects in other domains (whether the domain name is given explicitly, or selected by a default-domain directive) will have the domain name explicitly prepended when named (e.g., when the default domain is C, Python functions will be named "Python function", not just "function").

Added in version 1.0.


The name of a reST role (builtin or Sphinx extension) to use as the default role, that is, for text marked up `like this`. This can be set to 'py:obj' to make `filter` a cross-reference to the Python function "filter". The default is None, which doesn't reassign the default role.

The default role can always be set within individual documents using the standard reST default-role directive.

Added in version 0.4.


If true, keep warnings as "system message" paragraphs in the built documents. Regardless of this setting, warnings are always written to the standard error stream when sphinx-build is run.

The default is False, the pre-0.5 behavior was to always keep them.

Added in version 0.5.


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

Added in version 7.3.0.


A list of warning types to suppress arbitrary warning messages.

Sphinx core supports following warning types:

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

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

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

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

Added in version 1.4.

Changed in version 1.5: Added misc.highlighting_failure

Changed in version 1.5.1: Added epub.unknown_project_files

Changed in version 1.6: Added ref.footnote

Changed in version 2.1: Added autosectionlabel.<document name>

Changed in version 3.3.0: Added epub.duplicated_toc_entry

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

Added in version 4.5: Added i18n.inconsistent_references

Added in version 7.1: Added index warning type.

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


If set to a major.minor version string like '1.1', Sphinx will compare it with its version and refuse to build if it is too old. Default is no requirement.

Added in version 1.0.

Changed in version 1.4: also accepts micro version string


This value can be a dictionary specifying version requirements for extensions in extensions, e.g. needs_extensions = {'sphinxcontrib.something': '1.5'}. The version strings should be in the form major.minor. Requirements do not have to be specified for all extensions, only for those you want to check.

This requires that the extension specifies its version to Sphinx (see Sphinx Extensions API for how to do that).

Added in version 1.3.


A URL to cross-reference manpage roles. If this is defined to https://manpages.debian.org/{path}, the :manpage:`man(1)` role will link to <https://manpages.debian.org/man(1)>. The patterns available are:
  • page - the manual page (man)
  • section - the manual section (1)
  • path - the original manual page and section specified (man(1))

This also supports manpages specified as man.1.

NOTE:

This currently affects only HTML writers but could be expanded in the future.


Added in version 1.7.


If true, Sphinx will warn about all references where the target cannot be found. Default is False. You can activate this mode temporarily using the -n command-line switch.

Added in version 1.0.


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

Added in version 1.1.

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


An extended version of nitpick_ignore, which instead interprets the type and target strings as regular expressions. Note, that the regular expression must match the whole string (as if the ^ and $ markers were inserted).

For example, (r'py:.*', r'foo.*bar\.B.*') will ignore nitpicky warnings for all python entities that start with 'foo' and have 'bar.B' in them, such as ('py:const', 'foo_package.bar.BAZ_VALUE') or ('py:class', 'food.bar.Barman').

Added in version 4.1.

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


If true, figures, tables and code-blocks are automatically numbered if they have a caption. The numref role is enabled. Obeyed so far only by HTML and LaTeX builders. Default is False.

NOTE:

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


Added in version 1.3.


A dictionary mapping 'figure', 'table', 'code-block' and 'section' to strings that are used for format of figure numbers. As a special character, %s will be replaced to figure number.

Default is to use 'Fig. %s' for 'figure', 'Table %s' for 'table', 'Listing %s' for 'code-block' and 'Section %s' for 'section'.

Added in version 1.3.


  • if set to 0, figures, tables and code-blocks are continuously numbered starting at 1.
  • if 1 (default) numbers will be x.1, x.2, ... with x the section number (top level sectioning; no x. if no section). This naturally applies only if section numbering has been activated via the :numbered: option of the toctree directive.
  • 2 means that numbers will be x.y.1, x.y.2, ... if located in a sub-section (but still x.1, x.2, ... if located directly under a section and 1, 2, ... if not in any top level section.)
  • etc...

Added in version 1.3.

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


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

Added in version 1.6.6: It replaces deprecated html_use_smartypants. It applies by default to all builders except man and text (see smartquotes_excludes.)

A docutils.conf file located in the configuration directory (or a global ~/.docutils file) is obeyed unconditionally if it deactivates smart quotes via the corresponding Docutils option. But if it activates them, then smartquotes does prevail.


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

Added in version 1.6.6.


This is a dict whose default is:

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


Each entry gives a sufficient condition to ignore the smartquotes setting and deactivate the Smart Quotes transform. Accepted keys are as above 'builders' or 'languages'. The values are lists.

NOTE:

Currently, in case of invocation of make with multiple targets, the first target name is the only one which is tested against the 'builders' entry and it decides for all. Also, a make text following make html needs to be issued in the form make text O="-E" to force re-parsing of source files, as the cached ones are already transformed. On the other hand the issue does not arise with direct usage of sphinx-build as it caches (in its default usage) the parsed source files in per builder locations.


HINT:

An alternative way to effectively deactivate (or customize) the smart quotes for a given builder, for example latex, is to use make this way:

make latex O="-D smartquotes_action="


This can follow some make html with no problem, in contrast to the situation from the prior note.



Added in version 1.6.6.


A User-Agent of Sphinx. It is used for a header on HTTP access (ex. linkcheck, intersphinx and so on). Default is "Sphinx/X.Y.Z requests/X.Y.Z python/X.Y.Z".

Added in version 2.3.


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

Added in version 1.5.


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

Added in version 1.5.

TIP:

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



These values determine how to format the current date, used as the replacement for |today|.
  • If you set today to a non-empty value, it is used.
  • Otherwise, the current time is formatted using time.strftime() and the format given in today_fmt.

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


The default language to highlight source code in. The default is 'default'. It is similar to 'python3'; it is mostly a superset of 'python' but it fallbacks to 'none' without warning if failed. 'python3' and other languages will emit warning if failed.

The value should be a valid Pygments lexer name, see Showing code examples for more details.

Added in version 0.5.

Changed in version 1.4: The default is now 'default'. If you prefer Python 2 only highlighting, you can set it back to 'python'.


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

Example:

highlight_options = {

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


A single dictionary of options are also allowed. Then it is recognized as options to the lexer specified by highlight_language:

# configuration for the ``highlight_language``
highlight_options = {'stripall': True}


Added in version 1.3.

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


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.


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

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

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

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

Added in version 7.1.


A boolean that decides whether parentheses are appended to function and method role text (e.g. the content of :func:`input`) to signify that the name is callable. Default is True.

A boolean that decides whether module names are prepended to all object names (for object types where a "module" of some kind is defined), e.g. for py:function directives. Default is True.

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

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

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

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

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

Added in version 5.2.


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

A list of prefixes that are ignored for sorting the Python module index (e.g., if this is set to ['foo.'], then foo.bar is shown under B, not F). This can be handy if you document a project that consists of a single package. Works only for the HTML builder currently. Default is [].

Added in version 0.6.


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

Added in version 0.6.


If true, doctest flags (comments looking like # doctest: FLAG, ...) at the ends of lines and <BLANKLINE> markers are removed for all code blocks showing interactive Python sessions (i.e. doctests). Default is True. See the extension doctest for more possibilities of including doctests.

Added in version 1.0.

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


Default is False. When backslash stripping is enabled then every occurrence of \\ in a domain directive will be changed to \, even within string literals. This was the behaviour before version 3.0, and setting this variable to True will reinstate that behaviour.

Added in version 3.0.


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

Added in version 5.1.


Options for internationalization

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

The code for the language the docs are written in. Any text automatically generated by Sphinx will be in that language. Also, Sphinx will try to substitute individual paragraphs from your documents with the translation sets obtained from locale_dirs. Sphinx will search language-specific figures named by figure_language_filename (e.g. the German version of myfigure.png will be myfigure.de.png by default setting) and substitute them for original figures. In the LaTeX builder, a suitable language will be selected as an option for the Babel package. Default is 'en'.

Added in version 0.5.

Changed in version 1.4: Support figure substitution

Changed in version 5.0.

Currently supported languages by Sphinx are:

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


Added in version 0.5.

Directories in which to search for additional message catalogs (see language), relative to the source directory. The directories on this path are searched by the standard gettext module.

Internal messages are fetched from a text domain of sphinx; so if you add the directory ./locale to this setting, the message catalogs (compiled from .po format using msgfmt) must be in ./locale/language/LC_MESSAGES/sphinx.mo. The text domain of individual documents depends on gettext_compact.

The default is ['locales'].

NOTE:

The -v option for sphinx-build command is useful to check the locale_dirs config works as expected. It emits debug messages if message catalog directory not found.


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


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

Added in version 4.3.


Added in version 1.1.

If true, a document's text domain is its docname if it is a top-level project file and its very base directory otherwise.

If set to string, all document's text domain is this string, making all documents use single text domain.

By default, the document markup/code.rst ends up in the markup text domain. With this option set to False, it is markup/code.

Changed in version 3.3: The string value is now accepted.


If true, Sphinx generates uuid information for version tracking in message catalogs. It is used for:
  • Add uid line for each msgids in .pot files.
  • Calculate similarity between new msgids and previously saved old msgids. This calculation takes a long time.

If you want to accelerate the calculation, you can use python-levenshtein 3rd-party package written in C by using pip install python-levenshtein.

The default is False.

Added in version 1.3.


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

The default is True.

Added in version 1.3.


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

The default is True.

Added in version 1.3.


To specify names to enable gettext extracting and translation applying for i18n additionally. You can specify below names:
index terms
literal blocks (:: annotation and code-block directive)
doctest block
raw content
image/figure uri

For example: gettext_additional_targets = ['literal-block', 'image'].

The default is [].

Added in version 1.3.

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


The filename format for language-specific figures. The default value is {root}.{language}{ext}. It will be expanded to dirname/filename.en.png from .. image:: dirname/filename.png. The available format tokens are:
  • {root} - the filename, including any path component, without the file extension, e.g. dirname/filename
  • {path} - the directory path component of the filename, with a trailing slash if non-empty, e.g. dirname/
  • {docpath} - the directory path component for the current document, with a trailing slash if non-empty.
  • {basename} - the filename without the directory path or file extension components, e.g. filename
  • {ext} - the file extension, e.g. .png
  • {language} - the translation language, e.g. en

For example, setting this to {path}{language}/{basename}{ext} will expand to dirname/en/filename.png instead.

Added in version 1.4.

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

Changed in version 3.2: Added {docpath} token.


Control which, if any, classes are added to indicate translation progress. This setting would likely only be used by translators of documentation, in order to quickly indicate translated and untranslated content.
  • True: add translated and untranslated classes to all nodes with translatable content.
  • translated: only add the translated class.
  • untranslated: only add the untranslated class.
  • False: do not add any classes to indicate translation progress.

Defaults to False.

Added in version 7.1.


Options for Math

These options influence Math notations.

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

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.


If True, displayed math equations are numbered across pages when numfig is enabled. The numfig_secnum_depth setting is respected. The eq, not numref, role must be used to reference equation numbers. Default is True.

Added in version 1.7.


Options for HTML output

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

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

Added in version 0.6.


A dictionary of options that influence the look and feel of the selected theme. These are theme-specific. For the options understood by the builtin themes, see this section.

Added in version 0.6.


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.


The style sheet to use for HTML pages. A file of that name must exist either in Sphinx's static/ path, or in one of the custom paths given in html_static_path. Default is the stylesheet given by the selected theme. If you only want to add or override a few things compared to the theme's stylesheet, use CSS @import to import the theme's stylesheet.

The "title" for HTML documentation generated with Sphinx's own templates. This is appended to the <title> tag of individual pages, and used in the navigation bar as the "topmost" element. It defaults to '<project> v<revision> documentation'.

A shorter "title" for the HTML docs. This is used for links in the header and in the HTML Help docs. If not given, it defaults to the value of html_title.

Added in version 0.4.


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

Added in version 1.8.


The style of line numbers for code-blocks.
  • 'table' -- display line numbers using <table> tag
  • 'inline' -- display line numbers using <span> tag (default)

Added in version 3.2.

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

Deprecated since version 4.0.


A dictionary of values to pass into the template engine's context for all pages. Single values can also be put in this dictionary using the -A command-line option of sphinx-build.

Added in version 0.5.


If given, this must be the name of an image file (path relative to the configuration directory) that is the logo of the docs, or URL that points an image file for the logo. It is placed at the top of the sidebar; its width should therefore not exceed 200 pixels. Default: None.

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

Changed in version 4.0: Also accepts the URL for the logo file.


If given, this must be the name of an image file (path relative to the configuration directory) that is the favicon of the docs, or URL that points an image file for the favicon. Modern browsers use this as the icon for tabs, windows and bookmarks. It should be a Windows-style icon file (.ico), which is 16x16 or 32x32 pixels large. Default: None.

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

Changed in version 4.0: Also accepts the URL for the favicon.


A list of CSS files. The entry must be a filename string or a tuple containing the filename string and the attributes dictionary. The filename must be relative to the html_static_path, or a full URI with scheme like https://example.org/style.css. The attributes is used for attributes of <link> tag. It defaults to an empty list.

Example:

html_css_files = ['custom.css',

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


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

Added in version 1.8.

Changed in version 3.5: Support priority attribute


A list of JavaScript filename. The entry must be a filename string or a tuple containing the filename string and the attributes dictionary. The filename must be relative to the html_static_path, or a full URI with scheme like https://example.org/script.js. The attributes is used for attributes of <script> tag. It defaults to an empty list.

Example:

html_js_files = ['script.js',

'https://example.com/scripts/custom.js',
('custom.js', {'async': 'async'})]


As a special attribute, priority can be set as an integer to load the JavaScript file at an earlier or lazier step. For more information, refer Sphinx.add_js_file().

Added in version 1.8.

Changed in version 3.5: Support priority attribute


A list of paths that contain custom static files (such as style sheets or script files). Relative paths are taken as relative to the configuration directory. They are copied to the output's _static directory after the theme's static files, so a file named default.css will overwrite the theme's default.css.

As these files are not meant to be built, they are automatically excluded from source files.

NOTE:

For security reasons, dotfiles under html_static_path will not be copied. If you would like to copy them intentionally, please add each filepath to this setting:

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


Another way to do that, you can also use html_extra_path. It allows to copy dotfiles under the directories.



Changed in version 0.4: The paths in html_static_path can now contain subdirectories.

Changed in version 1.0: The entries in html_static_path can now be single files.

Changed in version 1.8: The files under html_static_path are excluded from source files.


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.


If this is not None, a 'Last updated on:' timestamp is inserted at every page bottom, using the given strftime() format. The empty string is equivalent to '%b %d, %Y' (or a locale-dependent equivalent).

If true, quotes and dashes are converted to typographically correct entities. Default: True.

Deprecated since version 1.6: To disable smart quotes, use rather smartquotes.


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

Added in version 3.5.


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

Added in version 3.5.


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

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

The values can be either lists or single strings.

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

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

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

Deprecated since version 1.7: a single string value for html_sidebars will be removed in 2.0

Builtin sidebar templates that can be rendered are:

  • localtoc.html -- a fine-grained table of contents of the current document
  • globaltoc.html -- a coarse-grained table of contents for the whole documentation set, collapsed
  • relations.html -- two links to the previous and next documents
  • sourcelink.html -- a link to the source of the current document, if enabled in html_show_sourcelink
  • searchbox.html -- the "quick search" box

Example:

html_sidebars = {

'**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
'using/windows': ['windowssidebar.html', 'searchbox.html'], }


This will render the custom template windowssidebar.html and the quick search box within the sidebar of the given document, and render the default sidebars for all other pages (except that the local TOC is replaced by the global TOC).

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

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


Additional templates that should be rendered to HTML pages, must be a dictionary that maps document names to template names.

Example:

html_additional_pages = {

'download': 'customdownload.html', }


This will render the template customdownload.html as the page download.html.


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

This value can be a bool or a list of index names that should be generated. To find out the index name for a specific index, look at the HTML file name. For example, the Python module index has the name 'py-modindex'.

Added in version 1.0.


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

Added in version 0.4.


If true, the index is generated twice: once as a single page with all the entries, and once as one page per starting letter. Default is False.

Added in version 0.4.


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

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

Added in version 0.6.


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

Added in version 1.5.


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

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

Added in version 0.4.


Suffix for generated links to HTML files. The default is whatever html_file_suffix is set to; it can be set differently (e.g. to support different web server setups).

Added in version 0.6.


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

Added in version 1.0.


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

Added in version 4.5.


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

Added in version 0.4.


Encoding of HTML output files. Default is 'utf-8'. Note that this encoding name must both be a valid Python encoding name and a valid HTML charset value.

Added in version 1.0.


If true, a list all whose items consist of a single paragraph and/or a sub-list all whose items etc... (recursive definition) will not use the <p> element for any of its items. This is standard docutils behavior. Default: True.

Added in version 1.0.


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

Added in version 1.0.


Language to be used for generating the HTML full-text search index. This defaults to the global language selected with language. If there is no support for this language, "en" is used which selects the English language.

Support is present for these languages:

  • da -- Danish
  • nl -- Dutch
  • en -- English
  • fi -- Finnish
  • fr -- French
  • de -- German
  • hu -- Hungarian
  • it -- Italian
  • ja -- Japanese
  • no -- Norwegian
  • pt -- Portuguese
  • ro -- Romanian
  • ru -- Russian
  • es -- Spanish
  • sv -- Swedish
  • tr -- Turkish
  • zh -- Chinese

Each language (except Japanese) provides its own stemming algorithm. Sphinx uses a Python implementation by default. You can use a C implementation to accelerate building the index file.

  • PorterStemmer (en)
  • PyStemmer (all languages)



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

Changed in version 1.3: Added additional languages.


A dictionary with options for the search language support, empty by default. The meaning of these options depends on the language selected.

The English support has no options.

The Japanese support has these options:


is dotted module path string to specify Splitter implementation which should be derived from sphinx.search.ja.BaseSplitter. If not specified or None is specified, 'sphinx.search.ja.DefaultSplitter' will be used.

You can choose from these modules:

'sphinx.search.ja.DefaultSplitter'
TinySegmenter algorithm. This is default splitter.
'sphinx.search.ja.MecabSplitter'
MeCab binding. To use this splitter, 'mecab' python binding or dynamic link library ('libmecab.so' for linux, 'libmecab.dll' for windows) is required.
'sphinx.search.ja.JanomeSplitter'
Janome binding. To use this splitter, Janome is required.

Deprecated since version 1.6: 'mecab', 'janome' and 'default' is deprecated. To keep compatibility, 'mecab', 'janome' and 'default' are also acceptable.


Other option values depend on splitter value which you choose.

Options for 'mecab':

is the encoding for the MeCab algorithm.

is the dictionary to use for the MeCab algorithm.

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

is the user dictionary file path for Janome.

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


Added in version 1.1.

Changed in version 1.4: html_search_options for Japanese is re-organized and any custom splitter can be used by type settings.

The Chinese support has these options:

dict -- the jieba dictionary path if want to use custom dictionary.


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.


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

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

.. image:: sphinx.png

:scale: 50%
:class: no-scaled-link


Added in version 1.3.

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


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

Added in version 1.8.


Output is processed with HTML5 writer. Default is False.

Added in version 1.6.

Deprecated since version 2.0.


Output is processed with HTML4 writer. Default is False.

Options for Single HTML output

Custom sidebar templates, must be a dictionary that maps document names to template names. And it only allows a key named 'index'. All other keys are ignored. For more information, refer to html_sidebars. By default, it is same as html_sidebars.

Options for HTML help output

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

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

Added in version 2.0.


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

Added in version 2.0.


Options for Apple Help output

Added in version 1.3.

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

NOTE:

Apple Help output will only work on Mac OS X 10.6 and higher, as it requires the hiutil and codesign command line tools, neither of which are Open Source.

You can disable the use of these tools using applehelp_disable_external_tools, but the result will not be a valid help book until the indexer is run over the .lproj folders within the bundle.



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

The bundle ID for the help book bundle.

WARNING:

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



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

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

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.

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

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

Defaults to None for no remote search.


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

e.g. if you set it to https://example.com/help/Foo/ and Help Viewer wants a copy of index.html for an English speaking customer, it will look at https://example.com/help/Foo/en.lproj/index.html.

Defaults to None for no remote content.


If True, tell the help indexer to index anchors in the generated HTML. This can be useful for jumping to a particular topic using the AHLookupAnchor function or the openHelpAnchor:inBook: method in your code. It also allows you to use help:anchor URLs; see the Apple documentation for more information on this topic.

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

Either a language specification (to use the built-in stopwords), or the path to a stopwords plist, or None if you do not want to use stopwords. The default stopwords plist can be found at /usr/share/hiutil/Stopwords.plist and contains, at time of writing, stopwords for the following languages:
Language Code
English en
German de
Spanish es
French fr
Swedish sv
Hungarian hu
Italian it

Defaults to language, or if that is not set, to 'en'.


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

Defaults to language, or if that is not set, to 'en'.


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

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

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


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

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


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

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

If True, the builder will not run the indexer or the code signing tool, no matter what other settings are specified.

This is mainly useful for testing, or where you want to run the Sphinx build on a non-Mac OS X platform and then complete the final steps on OS X for some reason.

Defaults to False.


Options for epub output

These options influence the epub output. As this builder derives from the HTML builder, the HTML options also apply where appropriate. The actual values for some of the options is not really important, they just have to be entered into the Dublin Core metadata.

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

The HTML theme for the epub output. Since the default themes are not optimized for small screen space, using the same theme for HTML and epub output is usually not wise. This defaults to 'epub', a theme designed to save visual space.

A dictionary of options that influence the look and feel of the selected theme. These are theme-specific. For the options understood by the builtin themes, see this section.

Added in version 1.2.


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

Changed in version 2.0: It defaults to the project option.


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

Added in version 1.4.

Changed in version 1.5: Renamed from epub3_description


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

The name of a person, organization, etc. that played a secondary role in the creation of the content of an EPUB Publication. The default value is 'unknown'.

Added in version 1.4.

Changed in version 1.5: Renamed from epub3_contributor


The language of the document. This is put in the Dublin Core metadata. The default is the language option or 'en' if unset.

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

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

An identifier for the document. This is put in the Dublin Core metadata. For published documents this is the ISBN number, but you can also use an alternative scheme, e.g. the project homepage. The default value is 'unknown'.

The publication scheme for the epub_identifier. This is put in the Dublin Core metadata. For published books the scheme is 'ISBN'. If you use the project homepage, 'URL' seems reasonable. The default value is 'unknown'.

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

The cover page information. This is a tuple containing the filenames of the cover image and the html template. The rendered html cover page is inserted as the first item in the spine in content.opf. If the template filename is empty, no html cover page is created. No cover at all is created if the tuple is empty. Examples:

epub_cover = ('_static/cover.png', 'epub-cover.html')
epub_cover = ('_static/cover.png', '')
epub_cover = ()


The default value is ().

Added in version 1.1.


A list of CSS files. The entry must be a filename string or a tuple containing the filename string and the attributes dictionary. For more information, see html_css_files.

Added in version 1.8.


Meta data for the guide element of content.opf. This is a sequence of tuples containing the type, the uri and the title of the optional guide information. See the OPF documentation at https://idpf.org/epub for details. If possible, default entries for the cover and toc types are automatically inserted. However, the types can be explicitly overwritten if the default entries are not appropriate. Example:

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


The default value is ().


Additional files that should be inserted before the text generated by Sphinx. It is a list of tuples containing the file name and the title. If the title is empty, no entry is added to toc.ncx. Example:

epub_pre_files = [

('index.html', 'Welcome'), ]


The default value is [].


Additional files that should be inserted after the text generated by Sphinx. It is a list of tuples containing the file name and the title. This option can be used to add an appendix. If the title is empty, no entry is added to toc.ncx. The default value is [].

A list of files that are generated/copied in the build directory but should not be included in the epub file. The default value is [].

The depth of the table of contents in the file toc.ncx. It should be an integer greater than zero. The default value is 3. Note: A deeply nested table of contents may be difficult to navigate.

This flag determines if a toc entry is inserted again at the beginning of its nested toc listing. This allows easier navigation to the top of a chapter, but can be confusing because it mixes entries of different depth in one list. The default value is True.

This setting control the scope of the epub table of contents. The setting can have the following values:
  • 'default' -- include all toc entries that are not hidden (default)
  • 'includehidden' -- include all toc entries

Added in version 1.2.


This flag determines if sphinx should try to fix image formats that are not supported by some epub readers. At the moment palette images with a small color table are upgraded. You need Pillow, the Python Image Library, installed to use this option. The default value is False because the automatic conversion may lose information.

Added in version 1.2.


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

Added in version 1.2.


Control whether to display URL addresses. This is very useful for readers that have no other means to display the linked URL. The settings can have the following values:
  • 'inline' -- display URLs inline in parentheses (default)
  • 'footnote' -- display URLs in footnotes
  • 'no' -- do not display URLs

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

Added in version 1.2.


If true, add an index to the epub document. It defaults to the html_use_index option but can be set independently for epub creation.

Added in version 1.2.


It specifies writing direction. It can accept 'horizontal' (default) and 'vertical'
epub_writing_mode 'horizontal' 'vertical'
writing-mode [2] horizontal-tb vertical-rl
page progression left to right right to left
iBook's Scroll Theme support scroll-axis is vertical. scroll-axis is horizontal.
[2]
https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode

Options for LaTeX output

These options influence LaTeX output.

The LaTeX engine to build the docs. The setting can have the following values:
  • 'pdflatex' -- PDFLaTeX (default)
  • 'xelatex' -- XeLaTeX
  • 'lualatex' -- LuaLaTeX
  • 'platex' -- pLaTeX
  • 'uplatex' -- upLaTeX (default if language is 'ja')

'pdflatex''s support for Unicode characters is limited.

NOTE:

2.0 adds to 'pdflatex' support in Latin language document of occasional Cyrillic or Greek letters or words. This is not automatic, see the discussion of the latex_elements 'fontenc' key.


If your project uses Unicode characters, setting the engine to 'xelatex' or 'lualatex' and making sure to use an OpenType font with wide-enough glyph coverage is often easier than trying to make 'pdflatex' work with the extra Unicode characters. Since Sphinx 2.0 the default is the GNU FreeFont which covers well Latin, Cyrillic and Greek.

Changed in version 2.1.0: Use xelatex (and LaTeX package xeCJK) by default for Chinese documents.

Changed in version 2.2.1: Use xelatex by default for Greek documents.

Changed in version 2.3: Add uplatex support.

Changed in version 4.0: uplatex becomes the default setting of Japanese documents.

Contrarily to MathJaX math rendering in HTML output, LaTeX requires some extra configuration to support Unicode literals in math: the only comprehensive solution (as far as we know) is to use 'xelatex' or 'lualatex' and to add r'\usepackage{unicode-math}' (e.g. via the latex_elements 'preamble' key). You may prefer r'\usepackage[math-style=literal]{unicode-math}' to keep a Unicode literal such as α (U+03B1) for example as is in output, rather than being rendered as \alpha.


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:
String that specifies the document name of the LaTeX file's master document. All documents referenced by the startdoc document in TOC trees will be included in the LaTeX file. (If you want to use the default root document for your LaTeX build, provide your root_doc here.)
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).
LaTeX theme. See latex_theme.
Must be True or False. If true, the startdoc document itself is not included in the output, only the documents referenced by it via TOC trees. With this option, you can put extra stuff in the master document that shows up in the HTML, but not the LaTeX output.

Added in version 1.2: In the past including your own document class required you to prepend the document class name with the string "sphinx". This is not necessary anymore.

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


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

This value determines the topmost sectioning unit. It should be chosen from 'part', 'chapter' or 'section'. The default is None; the topmost sectioning unit is switched by documentclass: section is used if documentclass will be howto, otherwise chapter will be used.

Note that if LaTeX uses \part command, then the numbering of sectioning units one level deep gets off-sync with HTML numbering, because LaTeX numbers continuously \chapter (or \section for howto.)

Added in version 1.4.


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

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

This value can be a bool or a list of index names that should be generated, like for html_domain_indices.

Added in version 1.0.


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

Added in version 1.0.


Control whether to display URL addresses. This is very useful for printed copies of the manual. The setting can have the following values:
  • 'no' -- do not display URLs (default)
  • 'footnote' -- display URLs in footnotes
  • 'inline' -- display URLs inline in parentheses

Added in version 1.0.

Changed in version 1.1: This value is now a string; previously it was a boolean value, and a true value selected the 'inline' display. For backwards compatibility, True is still accepted.


The default is False: it means that Sphinx's own macros are used for merged cells from grid tables. They allow general contents (literal blocks, lists, blockquotes, ...) but may have problems if the tabularcolumns directive was used to inject LaTeX mark-up of the type >{..}, <{..}, @{..} as column specification.

Setting to True means to use LaTeX's standard \multicolumn; this is incompatible with literal blocks in the horizontally merged cell, and also with multiple paragraphs in such cell if the table is rendered using tabulary.

Added in version 1.6.


A list of styling classes (strings). Currently supported:
  • 'booktabs': no vertical lines, and only 2 or 3 horizontal lines (the latter if there is a header), using the booktabs package.
  • 'borderless': no lines whatsoever.
  • 'colorrows': the table rows are rendered with alternating background colours. The interface to customize them is via dedicated keys of The sphinxsetup configuration setting.

    IMPORTANT:

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



Default: ['booktabs', 'colorrows']

Added in version 5.3.0.

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

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

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

NOTE:

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

>{\columncolor{blue}\sphinxnorowcolor}


in a table column specification.

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

>{\sphinxcolorblend{!95!red}}


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

HINT:

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


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



HINT:

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

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




If True, the PDF build from the LaTeX files created by Sphinx will use xindy (doc) rather than makeindex for preparing the index of general terms (from index usage). This means that words with UTF-8 characters will get ordered correctly for the language.
  • This option is ignored if latex_engine is 'platex' (Japanese documents; mendex replaces makeindex then).
  • The default is True for 'xelatex' or 'lualatex' as makeindex, if any indexed term starts with a non-ascii character, creates .ind files containing invalid bytes for UTF-8 encoding. With 'lualatex' this then breaks the PDF build.
  • The default is False for 'pdflatex' but True is recommended for non-English documents as soon as some indexed terms use non-ascii characters from the language script.

Sphinx adds to xindy base distribution some dedicated support for using 'pdflatex' engine with Cyrillic scripts. And whether with 'pdflatex' or Unicode engines, Cyrillic documents handle correctly the indexing of Latin names, even with diacritics.

Added in version 1.8.


Added in version 0.5.

Its documentation has moved to LaTeX customization.


A dictionary mapping 'howto' and 'manual' to names of real document classes that will be used as the base for the two Sphinx classes. Default is to use 'article' for 'howto' and 'report' for 'manual'.

Added in version 1.0.

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


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

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

ATTENTION:

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


Added in version 0.6.

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


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

As a built-in LaTeX themes, manual and howto are bundled.

A LaTeX theme for writing a manual. It imports the report document class (Japanese documents use jsbook).
A LaTeX theme for writing an article. It imports the article document class (Japanese documents use jreport rather). latex_appendices is available only for this theme.

It defaults to 'manual'.

Added in version 3.0.


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

Added in version 3.1.


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.


Options for text output

These options influence text output.

Determines which end-of-line character(s) are used in text output.
  • 'unix': use Unix-style line endings (\n)
  • 'windows': use Windows-style line endings (\r\n)
  • 'native': use the line ending style of the platform the documentation is built on

Default: 'unix'.

Added in version 1.1.


A string of 7 characters that should be used for underlining sections. The first character is used for first-level headings, the second for second-level headings and so on.

The default is '*=-~"+`'.

Added in version 1.1.


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

Added in version 1.7.


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

Added in version 1.7.


Options for manual page output

These options influence manual page output.

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:
String that specifies the document name of the manual page's master document. All documents referenced by the startdoc document in TOC trees will be included in the manual file. (If you want to use the default root document for your manual pages build, use your root_doc here.)
name
Name of the manual page. This should be a short string without spaces or special characters. It is used to determine the file name as well as the name of the manual page (in the NAME section).
Description 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.
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.
The manual page section. Used for the output file name as well as in the manual page header.

Added in version 1.0.


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

Added in version 1.1.


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

Added in version 3.3.

Changed in version 4.0: The default is changed to False from True.

Changed in version 4.0.2: The default is changed to True from False again.


Options for Texinfo output

These options influence Texinfo output.

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:
String that specifies the document name of the the Texinfo file's master document. All documents referenced by the startdoc document in TOC trees will be included in the Texinfo file. (If you want to use the default master document for your Texinfo build, provide your root_doc here.)
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'.
The name that will appear in the top-level DIR menu file.
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.
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.


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

Added in version 1.1.


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

This value can be a bool or a list of index names that should be generated, like for html_domain_indices.

Added in version 1.1.


Control how to display URL addresses.
  • 'footnote' -- display URLs in footnotes (default)
  • 'no' -- do not display URLs
  • 'inline' -- display URLs inline in parentheses

Added in version 1.1.


If true, do not generate a @detailmenu in the "Top" node's menu containing entries for each sub-node in the document. Default is False.

Added in version 1.2.


A dictionary that contains Texinfo snippets that override those Sphinx usually puts into the generated .texi files.
Keys that you may want to override include:
'paragraphindent'
Number of spaces to indent the first line of each paragraph, default 2. Specify 0 for no indentation.
'exampleindent'
Number of spaces to indent the lines for examples or literal blocks, default 4. Specify 0 for no indentation.
'preamble'
Texinfo markup inserted near the beginning of the file.
'copying'
Texinfo markup inserted within the @copying block and displayed after the title. The default value consists of a simple title page identifying the project.

Keys that are set by other options and therefore should not be overridden are:

'author' 'body' 'date' 'direntry' 'filename' 'project' 'release' 'title'


Added in version 1.1.


If false, do not generate inline references in a document. That makes an info file more readable with stand-alone reader (info). Default is True.

Added in version 4.4.


Options for QtHelp output

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

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

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

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

A dictionary of options that influence the look and feel of the selected theme. These are theme-specific. For the options understood by the builtin themes, see this section.

Options for the linkcheck builder

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.


A dictionary that maps a pattern of the source URI to a pattern of the canonical URI. The linkcheck builder treats the redirected link as "working" when:
  • the link in the document matches the source URI pattern, and
  • the redirect location matches the canonical URI pattern.

Example:

linkcheck_allowed_redirects = {

# All HTTP redirections from the source URI to the canonical URI will be treated as "working".
r'https://sphinx-doc\.org/.*': r'https://sphinx-doc\.org/en/master/.*' }


If set, linkcheck builder will emit a warning when disallowed redirection found. It's useful to detect unexpected redirects under the warn-is-error mode.

Added in version 4.1.


A dictionary that maps baseurls to HTTP request headers.

The key is a URL base string like "https://www.sphinx-doc.org/". To specify headers for other hosts, "*" can be used. It matches all hosts only when the URL does not match other settings.

The value is a dictionary that maps header name to its value.

Example:

linkcheck_request_headers = {

"https://www.sphinx-doc.org/": {
"Accept": "text/html",
"Accept-Encoding": "utf-8",
},
"*": {
"Accept": "text/html,application/xhtml+xml",
} }


Added in version 3.1.


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

Added in version 1.4.


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

Added in version 1.1.


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

Added in version 1.1.


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

Added in version 1.2.


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

TIP:

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


NOTE:

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


Added in version 1.5.


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

Added in version 7.1.


Pass authentication information when doing a linkcheck build.

A list of (regex_pattern, auth_info) tuples where the items are:

A regular expression that matches a URI.
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.


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

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

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

Added in version 3.4.


A list of regular expressions that match documents in which Sphinx should not check the validity of links. This can be used for permitting link decay in legacy or historical sections of the documentation.

Example:

# ignore all links in documents located in a subfolder named 'legacy'
linkcheck_exclude_documents = [r'.*/legacy/.*']


Added in version 4.4.


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

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

Added in version 7.3.


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

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

Added in version 7.3.


Options for the XML builder

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

Added in version 1.2.


FOOTNOTES

[1]
A note on available globbing syntax: you can use the standard shell constructs *, ?, [...] and [!...] with the feature that these all don't match slashes. A double star ** can be used to match any sequence of characters including slashes.

Options for the C domain

A list of strings that the parser additionally should accept as attributes. This can for example be used when attributes have been #define d for portability.

Added in version 3.0.


A list of strings that the parser additionally should accept as attributes with one argument. That is, if my_align_as is in the list, then my_align_as(X) is parsed as an attribute for all strings X that have balanced braces ((), [], and {}). This can for example be used when attributes have been #define d for portability.

Added in version 3.0.


A list of identifiers to be recognized as keywords by the C parser. It defaults to ['alignas', 'alignof', 'bool', 'complex', 'imaginary', 'noreturn', 'static_assert', 'thread_local'].

Added in version 4.0.3.


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

Added in version 7.1.


Options for the C++ domain

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

Added in version 1.5.


A list of strings that the parser additionally should accept as attributes. This can for example be used when attributes have been #define d for portability.

Added in version 1.5.


A list of strings that the parser additionally should accept as attributes with one argument. That is, if my_align_as is in the list, then my_align_as(X) is parsed as an attribute for all strings X that have balanced braces ((), [], and {}). This can for example be used when attributes have been #define d for portability.

Added in version 1.5.


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

Added in version 7.1.


Options for the Python domain

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

Examples

The examples below use the following py:function directive:

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


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

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




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

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




Added in version 6.2.


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

Added in version 4.0.

NOTE:

This configuration is still in experimental



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

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

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

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


Added in version 7.1.


Options for the Javascript domain

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

Added in version 7.1.


Example of configuration file

# test documentation build configuration file, created by
# sphinx-quickstart on Sun Jun 26 00:00:43 2016.
#
# This file is executed through importlib.import_module with 
# the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The encoding of source files.
#
# source_encoding = 'utf-8-sig'
# The master toctree document.
root_doc = 'index'
# General information about the project.
project = 'test'
copyright = '2016, test'
author = 'test'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = 'test'
# The full version, including alpha/beta/rc tags.
release = 'test'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#
# today = ''
#
# Else, today_fmt is used as the format for a strftime call.
#
# today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# These patterns also affect html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# The reST default role (used for this markup: `text`) to use for all
# documents.
#
# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#
# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#
# add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#
# show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'
# Theme options are theme-specific and customize the look and feel of a theme
# further.  For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = []
# The name for this set of Sphinx documents.
# "<project> v<release> documentation" by default.
#
# html_title = 'test vtest'
# A shorter title for the navigation bar.  Default is the same as html_title.
#
# html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#
# html_logo = None
# The name of an image file (relative to this directory) to use as a favicon of
# the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#
# html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#
# html_extra_path = []
# If not None, a 'Last updated on:' timestamp is inserted at every page
# bottom, using the given strftime format.
# The empty string is equivalent to '%b %d, %Y'.
#
# html_last_updated_fmt = None
# Custom sidebar templates, maps document names to template names.
#
# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#
# html_additional_pages = {}
# If false, no module index is generated.
#
# html_domain_indices = True
# If false, no index is generated.
#
# html_use_index = True
# If true, the index is split into individual pages for each letter.
#
# html_split_index = False
# If true, links to the reST sources are added to the pages.
#
# html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#
# html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#
# html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it.  The value of this option must be the
# base URL from which the finished HTML is served.
#
# html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None
# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
#
# html_search_language = 'en'
# A dictionary with options for the search language support, empty by default.
# 'ja' uses this config value.
# 'zh' user can custom change `jieba` dictionary path.
#
# html_search_options = {'type': 'default'}
# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#
# html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
htmlhelp_basename = 'testdoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {

# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [
(root_doc, 'test.tex', 'test Documentation',
'test', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of # the title page. # # latex_logo = None # If true, show page references after internal links. # # latex_show_pagerefs = False # If true, show URL addresses after external links. # # latex_show_urls = False # Documents to append as an appendix to all manuals. # # latex_appendices = [] # If false, no module index is generated. # # latex_domain_indices = True # -- Options for manual page output --------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [
(root_doc, 'test', 'test Documentation',
[author], 1) ] # If true, show URL addresses after external links. # # man_show_urls = False # -- Options for Texinfo output ------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [
(root_doc, 'test', 'test Documentation',
author, 'test', 'One line description of project.',
'Miscellaneous'), ] # Documents to append as an appendix to all manuals. # # texinfo_appendices = [] # If false, no module index is generated. # # texinfo_domain_indices = True # How to display URL addresses: 'footnote', 'no', or 'inline'. # # texinfo_show_urls = 'footnote' # If true, do not generate a @detailmenu in the "Top" node's menu. # # texinfo_no_detailmenu = False # If false, do not generate in manual @ref nodes. # # texinfo_cross_references = False # -- A random example ----------------------------------------------------- import sys, os sys.path.insert(0, os.path.abspath('.')) exclude_patterns = ['zzz'] numfig = True #language = 'ja' extensions.append('sphinx.ext.todo') extensions.append('sphinx.ext.autodoc') #extensions.append('sphinx.ext.autosummary') extensions.append('sphinx.ext.intersphinx') extensions.append('sphinx.ext.mathjax') extensions.append('sphinx.ext.viewcode') extensions.append('sphinx.ext.graphviz') autosummary_generate = True html_theme = 'default' #source_suffix = ['.rst', '.txt']


Builders

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

The builder's "name" must be given to the -M or -b command-line options of sphinx-build to select a builder.

The most common builders are:

Build HTML pages. This is the default builder.
Build HTML pages, but with a single directory per document. Makes for prettier URLs (no .html) if served from a webserver.
Build a single HTML with the whole content.
Build HTML files with additional information for building a documentation collection in one of these formats.
Build an Apple Help Book. Requires hiutil and codesign, which are not Open Source and presently only available on Mac OS X 10.6 and higher.
Build LaTeX sources that can be compiled to a PDF document using pdflatex.
Build manual pages in groff format for UNIX systems.
Build Texinfo files that can be processed into Info files using makeinfo.
Build plain text files.
Build gettext-style message catalogs (.pot files).
Run all doctests in the documentation, if the doctest extension is enabled.
Check the integrity of all external links.
Build Docutils-native XML files.
Build compact pretty-printed "pseudo-XML" files displaying the internal structure of the intermediate document trees.


----



class sphinx.builders.html.StandaloneHTMLBuilder
This is the standard HTML builder. Its output is a directory with HTML files, complete with style sheets and optionally the reST sources. There are quite a few configuration values that customize the output of this builder, see the chapter Options for HTML output for details.
name = 'html'
The builder's name, for the -b command line option.

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

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


class sphinx.builders.dirhtml.DirectoryHTMLBuilder
This is a subclass of the standard HTML builder. Its output is a directory with HTML files, where each file is called index.html and placed in a subdirectory named like its page name. For example, the document markup/rest.rst will not result in an output file markup/rest.html, but markup/rest/index.html. When generating links between pages, the index.html is omitted, so that the URL would look like markup/rest/.
name = 'dirhtml'
The builder's name, for the -b command line option.

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

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

Added in version 0.6.


class sphinx.builders.singlehtml.SingleFileHTMLBuilder
This is an HTML builder that combines the whole project in one output file. (Obviously this only works with smaller projects.) The file is named like the root document. No indices will be generated.
name = 'singlehtml'
The builder's name, for the -b command line option.

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

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

Added in version 1.0.


class sphinxcontrib.htmlhelp.HTMLHelpBuilder
This builder produces the same output as the standalone HTML builder, but also generates HTML Help support files that allow the Microsoft HTML Help Workshop to compile them into a CHM file.
name = 'htmlhelp'
The builder's name, for the -b command line option.

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

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


class sphinxcontrib.qthelp.QtHelpBuilder
This builder produces the same output as the standalone HTML builder, but also generates Qt help collection support files that allow the Qt collection generator to compile them.

Changed in version 2.0: Moved to sphinxcontrib.qthelp from sphinx.builders package.

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

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

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


class sphinxcontrib.applehelp.AppleHelpBuilder
This builder produces an Apple Help Book based on the same output as the standalone HTML builder.

If the source directory contains any .lproj folders, the one corresponding to the selected language will have its contents merged with the generated output. These folders will be ignored by all other documentation types.

In order to generate a valid help book, this builder requires the command line tool hiutil, which is only available on Mac OS X 10.6 and above. You can disable the indexing step by setting applehelp_disable_external_tools to True, in which case the output will not be valid until hiutil has been run on all of the .lproj folders within the bundle.

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

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

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

Added in version 1.3.

Changed in version 2.0: Moved to sphinxcontrib.applehelp from sphinx.builders package.


class sphinxcontrib.devhelp.DevhelpBuilder
This builder produces the same output as the standalone HTML builder, but also generates GNOME Devhelp support file that allows the GNOME Devhelp reader to view them.
name = 'devhelp'
The builder's name, for the -b command line option.

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

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

Changed in version 2.0: Moved to sphinxcontrib.devhelp from sphinx.builders package.


class sphinx.builders.epub3.Epub3Builder
This builder produces the same output as the standalone HTML builder, but also generates an epub file for ebook readers. See Epub info for details about it. For definition of the epub format, have a look at https://idpf.org/epub or https://en.wikipedia.org/wiki/EPUB. The builder creates EPUB 3 files.
name = 'epub'
The builder's name, for the -b command line option.

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

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

Added in version 1.4.

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


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

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

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

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

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

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

Additional packages are needed in some circumstances:

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

NOTE:

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

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

make latexpdf LATEXMKOPTS="-silent"


reduces console output to a minimum.

Also, if latexmk is at version 4.52b or higher (January 2017) LATEXMKOPTS="-xelatex" speeds up PDF builds via XeLateX in case of numerous graphics inclusions.

To pass options directly to the (pdf|xe|lua)latex binary, use variable LATEXOPTS, for example:

make latexpdf LATEXOPTS="--halt-on-error"




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

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

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


Note that a direct PDF builder is being provided by rinohtype. The builder's name is rinoh. Refer to the rinohtype manual for details.

class sphinx.builders.text.TextBuilder
This builder produces a text file for each reST file -- this is almost the same as the reST source, but with much of the markup stripped for better readability.
name = 'text'
The builder's name, for the -b command line option.

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

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

Added in version 0.4.


class sphinx.builders.manpage.ManualPageBuilder
This builder produces manual pages in the groff format. You have to specify which documents are to be included in which manual pages via the man_pages configuration value.
name = 'man'
The builder's name, for the -b command line option.

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

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

Added in version 1.0.


class sphinx.builders.texinfo.TexinfoBuilder
This builder produces Texinfo files that can be processed into Info files by the makeinfo program. You have to specify which documents are to be included in which Texinfo files via the texinfo_documents configuration value.

The Info format is the basis of the on-line help system used by GNU Emacs and the terminal-based program info. See Texinfo info for more details. The Texinfo format is the official documentation system used by the GNU project. More information on Texinfo can be found at https://www.gnu.org/software/texinfo/.

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

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

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

Added in version 1.1.


class sphinxcontrib.serializinghtml.SerializingHTMLBuilder
This builder uses a module that implements the Python serialization API (pickle, simplejson, phpserialize, and others) to dump the generated HTML documentation. The pickle builder is a subclass of it.

A concrete subclass of this builder serializing to the PHP serialization format could look like this:

import phpserialize
class PHPSerializedBuilder(SerializingHTMLBuilder):

name = 'phpserialized'
implementation = phpserialize
out_suffix = '.file.phpdump'
globalcontext_filename = 'globalcontext.phpdump'
searchindex_filename = 'searchindex.phpdump'


A module that implements dump(), load(), dumps() and loads() functions that conform to the functions with the same names from the pickle module. Known modules implementing this interface are simplejson, phpserialize, plistlib, and others.

The suffix for all regular files.

The filename for the file that contains the "global context". This is a dict with some general configuration values such as the name of the project.

The filename for the search index Sphinx generates.

See Serialization builder details for details about the output format.

Added in version 0.5.


class sphinxcontrib.serializinghtml.PickleHTMLBuilder
This builder produces a directory with pickle files containing mostly HTML fragments and TOC information, for use of a web application (or custom postprocessing tool) that doesn't use the standard HTML templates.

See Serialization builder details for details about the output format.

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

The old name web still works as well.


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

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

The file suffix is .fpickle. The global context is called globalcontext.pickle, the search index searchindex.pickle.


class sphinxcontrib.serializinghtml.JSONHTMLBuilder
This builder produces a directory with JSON files containing mostly HTML fragments and TOC information, for use of a web application (or custom postprocessing tool) that doesn't use the standard HTML templates.

See Serialization builder details for details about the output format.

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

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

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

The file suffix is .fjson. The global context is called globalcontext.json, the search index searchindex.json.

Added in version 0.5.


class sphinx.builders.gettext.MessageCatalogBuilder
This builder produces gettext-style message catalogs. Each top-level file or subdirectory grows a single .pot catalog template.

See the documentation on Internationalization for further reference.

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

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

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

Added in version 1.1.


class sphinx.builders.changes.ChangesBuilder
This builder produces an HTML overview of all versionadded, versionchanged, deprecated and versionremoved directives for the current version. This is useful to generate a changelog file, for example.
name = 'changes'
The builder's name, for the -b command line option.

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

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


class sphinx.builders.dummy.DummyBuilder
This builder produces no output. The input is only parsed and checked for consistency. This is useful for linting purposes.
name = 'dummy'
The builder's name, for the -b command line option.

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

Added in version 1.4.


class sphinx.builders.linkcheck.CheckExternalLinksBuilder
This builder scans all documents for external links, tries to open them with requests, and writes an overview which ones are broken and redirected to standard output and to output.txt in the output directory.
name = 'linkcheck'
The builder's name, for the -b command line option.

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

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

Changed in version 1.5: Since Sphinx 1.5, the linkcheck builder uses the requests module.

Changed in version 3.4: The linkcheck builder retries links when servers apply rate limits.


class sphinx.builders.xml.XMLBuilder
This builder produces Docutils-native XML files. The output can be transformed with standard XML tools such as XSLT processors into arbitrary final forms.
name = 'xml'
The builder's name, for the -b command line option.

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

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

Added in version 1.2.


class sphinx.builders.xml.PseudoXMLBuilder
This builder is used for debugging the Sphinx/Docutils "Reader to Transform to Writer" pipeline. It produces compact pretty-printed "pseudo-XML", files where nesting is indicated by indentation (no end-tags). External attributes for all elements are output, and internal attributes for any leftover "pending" elements are also given.
name = 'pseudoxml'
The builder's name, for the -b command line option.

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

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

Added in version 1.2.


Built-in Sphinx extensions that offer more builders are:

  • doctest
  • coverage

Serialization builder details

All serialization builders outputs one file per source file and a few special files. They also copy the reST source files in the directory _sources under the output directory.

The PickleHTMLBuilder is a builtin subclass that implements the pickle serialization interface.

The files per source file have the extensions of out_suffix, and are arranged in directories just as the source files are. They unserialize to a dictionary (or dictionary like structure) with these keys:

body
The HTML "body" (that is, the HTML rendering of the source file), as rendered by the HTML translator.
title
The title of the document, as HTML (may contain markup).
toc
The table of contents for the file, rendered as an HTML <ul>.
display_toc
A boolean that is True if the toc contains more than one entry.
The document name of the current file.
parents, prev and next
Information about related chapters in the TOC tree. Each relation is a dictionary with the keys link (HREF for the relation) and title (title of the related document, as HTML). parents is a list of relations, while prev and next are a single relation.
sourcename
The name of the source file under _sources.

The special files are located in the root output directory. They are:

A pickled dict with these keys:
project, copyright, release, version
The same values as given in the configuration file.
html_style.
last_updated
Date of last build.
builder
Name of the used builder, in the case of pickles this is always 'pickle'.
titles
A dictionary of all documents' titles, as HTML strings.

An index that can be used for searching the documentation. It is a pickled list with these entries:
  • A list of indexed docnames.
  • A list of document titles, as HTML strings, in the same order as the first list.
  • A dict mapping word roots (processed by an English-language stemmer) to a list of integers, which are indices into the first list.

The build environment. This is always a pickle file, independent of the builder and a copy of the environment that was used when the builder was started.

Todo

Document common members.



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

Domains

Added in version 1.0.

Originally, Sphinx was conceived for a single project, the documentation of the Python language. Shortly afterwards, it was made available for everyone as a documentation tool, but the documentation of Python modules remained deeply built in -- the most fundamental directives, like function, were designed for Python objects. Since Sphinx has become somewhat popular, interest developed in using it for many different purposes: C/C++ projects, JavaScript, or even reStructuredText markup (like in this documentation).

While this was always possible, it is now much easier to easily support documentation of projects using different programming languages or even ones not supported by the main Sphinx distribution, by providing a domain for every such purpose.

A domain is a collection of markup (reStructuredText directives and roles) to describe and link to objects belonging together, e.g. elements of a programming language. Directive and role names in a domain have names like domain:name, e.g. py:function. Domains can also provide custom indices (like the Python Module Index).

Having domains means that there are no naming problems when one set of documentation wants to refer to e.g. C++ and Python classes. It also means that extensions that support the documentation of whole new languages are much easier to write.

This section describes what the domains that are included with Sphinx provide. The domain API is documented as well, in the section Domain API.

Basic Markup

Most domains provide a number of object description directives, used to describe specific objects provided by modules. Each directive requires one or more signatures to provide basic information about what is being described, and the content should be the description.

A domain will typically keep an internal index of all entities to aid cross-referencing. Typically it will also add entries in the shown general index. If you want to suppress the addition of an entry in the shown index, you can give the directive option flag :no-index-entry:. If you want to exclude the object description from the table of contents, you can give the directive option flag :no-contents-entry:. If you want to typeset an object description, without even making it available for cross-referencing, you can give the directive option flag :no-index: (which implies :no-index-entry:). If you do not want to typeset anything, you can give the directive option flag :no-typesetting:. This can for example be used to create only a target and index entry for later reference. Though, note that not every directive in every domain may support these options.

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

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

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

Changed in version 7.2:

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

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

An example using a Python domain directive:

.. py:function:: spam(eggs)

ham(eggs)
Spam or ham the foo.


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

.. py:function:: filterwarnings(action, message='', category=Warning, \

module='', lineno=0, append=False)
:no-index:


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

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

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


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

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

.. py:function:: spam(eggs)

:no-typesetting: .. code::
def spam(eggs):
pass The function :py:func:`spam` does nothing.


Default Domain

For documentation describing objects from solely one domain, authors will not have to state again its name at each directive, role, etc... after having specified a default. This can be done either via the config value primary_domain or via this directive:

.. default-domain:: name
Select a new default domain. While the primary_domain selects a global default, this only has an effect within the same file.

If no other default is selected, the Python domain (named py) is the default one, mostly for compatibility with documentation written for older versions of Sphinx.

Directives and roles that belong to the default domain can be mentioned without giving the domain name, i.e.

.. function:: pyfunc()

Describes a Python function. Reference to :func:`pyfunc`.


Cross-referencing syntax

For cross-reference roles provided by domains, the same facilities exist as for general cross-references. See Cross-referencing syntax.

In short:

  • You may supply an explicit title and reference target: :role:`title <target>` will refer to target, but the link text will be title.
  • If you prefix the content with !, no reference/hyperlink will be created.
  • If you prefix the content with ~, the link text will only be the last component of the target. For example, :py:meth:`~Queue.Queue.get` will refer to Queue.Queue.get but only display get as the link text.

Built-in domains

The following domains are included within Sphinx:

The Standard Domain

Added in version 1.0.

The so-called "standard" domain collects all markup that doesn't warrant a domain of its own. Its directives and roles are not prefixed with a domain name.

The standard domain is also where custom object descriptions, added using the add_object_type() API, are placed.

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

.. option:: name args, name args, ...
Describes a command line argument or switch. Option argument names should be enclosed in angle brackets. Examples:

.. option:: dest_dir

Destination directory. .. option:: -m <module>, --module <module>
Run a module as a script.


The directive will create cross-reference targets for the given options, referenceable by option (in the example case, you'd use something like :option:`dest_dir`, :option:`-m`, or :option:`--module`).

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

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

cmdoption directive is a deprecated alias for the option directive.


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

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

If you use program, you have to qualify the references in your option roles by the program name, so if you have the following situation

.. program:: rm
.. option:: -r

Work recursively. .. program:: svn .. option:: -r <revision>
Specify the revision to work upon.


then :option:`rm -r` would refer to the first option, while :option:`svn -r` would refer to the second one.

If None is passed to the argument, the directive will reset the current program name.

The program name may contain spaces (in case you want to document subcommands like svn add and svn commit separately).

Added in version 0.5.


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

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

.. describe:: PAPER

You can set this variable to select a paper size.



The C Domain

Added in version 1.0.

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

.. c:member:: declaration
.. c:var:: declaration
Describes a C struct member or variable. Example signature:

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


The difference between the two directives is only cosmetic.


.. c:function:: function prototype
Describes a C function. The signature should be given as in C, e.g.:

.. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)


Note that you don't have to backslash-escape asterisks in the signature, as it is not parsed by the reST inliner.

In the description of a function you can use the following info fields (see also Info field lists).

  • param, parameter, arg, argument, Description of a parameter.
  • type: Type of a parameter, written as if passed to the c:expr role.
  • returns, return: Description of the return value.
  • rtype: Return type, written as if passed to the c:expr role.
  • retval, retvals: An alternative to returns for describing the result of the function.

Added in version 4.3: The retval field type.

For example:

.. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

:param type: description of the first parameter.
:param nitems: description of the second parameter.
:returns: a result.
:retval NULL: under some conditions.
:retval NULL: under some other conditions as well.


which renders as

  • type -- description of the first parameter.
  • nitems -- description of the second parameter.

a result.
  • NULL -- under some conditions.
  • NULL -- under some other conditions as well.



:single-line-parameter-list: (no value)
Ensures that the function's parameters will be emitted on a single logical line, overriding c_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.1.



.. c:macro:: name
.. c:macro:: name(arg list)
Describes a C macro, i.e., a C-language #define, without the replacement text.

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

Added in version 3.0: The function style variant.

:single-line-parameter-list: (no value)
Ensures that the macro's parameters will be emitted on a single logical line, overriding c_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.1.



.. c:struct:: name
Describes a C struct.

Added in version 3.0.


.. c:union:: name
Describes a C union.

Added in version 3.0.


.. c:enum:: name
Describes a C enum.

Added in version 3.0.


.. c:enumerator:: name
Describes a C enumerator.

Added in version 3.0.


.. c:type:: typedef-like declaration
.. c:type:: name
Describes a C type, either as a typedef, or the alias for an unspecified type.

Cross-referencing C constructs

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

:c:member:
:c:data:
:c:var:
:c:func:
:c:macro:
:c:struct:
:c:union:
:c:enum:
:c:enumerator:
:c:type:
Reference a C declaration, as defined above. Note that c:member, c:data, and c:var are equivalent.

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


Anonymous Entities

C supports anonymous structs, enums, and unions. For the sake of documentation they must be given some name that starts with @, e.g., @42 or @data. These names can also be used in cross-references, though nested symbols will be found even when omitted. The @... name will always be rendered as [anonymous] (possibly as a link).

Example:

.. c:struct:: Data

.. c:union:: @data
.. c:var:: int a
.. c:var:: double b Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`.


This will be rendered as:


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

Added in version 3.0.

Aliasing Declarations

Sometimes it may be helpful list declarations elsewhere than their main documentation, e.g., when creating a synopsis of an interface. The following directive can be used for this purpose.

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

For example:

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

f


becomes




Added in version 3.2.

Options

:maxdepth: int
Insert nested declarations as well, up to the total depth given. Use 0 for infinite depth and 1 for just the mentioned declaration. Defaults to 1.

Added in version 3.3.


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

Added in version 3.5.



Inline Expressions and Types

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

.. c:var:: int a = 42
.. c:function:: int f(int i)
An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`).
A type: :c:expr:`const Data*`
(or as text :c:texpr:`const Data*`).


will be rendered as follows:



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

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

Added in version 3.0.


Namespacing

Added in version 3.1.

The C language it self does not support namespacing, but it can sometimes be useful to emulate it in documentation, e.g., to show alternate declarations. The feature may also be used to document members of structs/unions/enums separate from their parent declaration.

The current scope can be changed using three namespace directives. They manage a stack declarations where c:namespace resets the stack and changes a given scope.

The c:namespace-push directive changes the scope to a given inner scope of the current one.

The c:namespace-pop directive undoes the most recent c:namespace-push directive.

.. c:namespace:: scope specification
Changes the current scope for the subsequent objects to the given scope, and resets the namespace directive stack. Note that nested scopes can be specified by separating with a dot, e.g.:

.. c:namespace:: Namespace1.Namespace2.SomeStruct.AnInnerStruct


All subsequent objects will be defined as if their name were declared with the scope prepended. The subsequent cross-references will be searched for starting in the current scope.

Using NULL or 0 as the scope will change to global scope.


.. c:namespace-push:: scope specification
Change the scope relatively to the current scope. For example, after:

.. c:namespace:: A.B
.. c:namespace-push:: C.D


the current scope will be A.B.C.D.


.. c:namespace-pop::
Undo the previous c:namespace-push directive (not just pop a scope). For example, after:

.. c:namespace:: A.B
.. c:namespace-push:: C.D
.. c:namespace-pop::


the current scope will be A.B (not A.B.C).

If no previous c:namespace-push directive has been used, but only a c:namespace directive, then the current scope will be reset to global scope. That is, .. c:namespace:: A.B is equivalent to:

.. c:namespace:: NULL
.. c:namespace-push:: A.B



Configuration Variables

See Options for the C domain.

The C++ Domain

Added in version 1.0.

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

Directives for Declaring Entities

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

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

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


The difference between cpp:class and cpp:struct is only cosmetic: the prefix rendered in the output, and the specifier shown in the index.

The class can be directly declared inside a nested scope, e.g.,:

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


A class template can be declared:

.. cpp:class:: template<typename T, std::size_t N> std::array


or with a line break:

.. cpp:class:: template<typename T, std::size_t N> \

std::array


Full and partial template specialisations can be declared:

.. cpp:class:: template<> \

std::array<bool, 256> .. cpp:class:: template<typename T> \
std::array<T, 42>


Added in version 2.0: The cpp:struct directive.


.. cpp:function:: (member) function prototype
Describe a function or member function, e.g.,:

.. cpp:function:: bool myMethod(int arg1, std::string arg2)

A function with parameters and types. .. cpp:function:: bool myMethod(int, double)
A function with unnamed parameters. .. cpp:function:: const T &MyClass::operator[](std::size_t i) const
An overload for the indexing operator. .. cpp:function:: operator bool() const
A casting operator. .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept
A constexpr function. .. cpp:function:: MyClass::MyClass(const MyClass&) = default
A copy constructor with default implementation.


Function templates can also be described:

.. cpp:function:: template<typename U> \

void print(U &&u)


and function template specialisations:

.. cpp:function:: template<> \

void print(int i)


:single-line-parameter-list: (no value)
Ensures that the function's parameters will be emitted on a single logical line, overriding cpp_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.1.



.. cpp:member:: (member) variable declaration
.. cpp:var:: (member) variable declaration
Describe a variable or member variable, e.g.,:

.. cpp:member:: std::string MyClass::myMember
.. cpp:var:: std::string MyClass::myOtherMember[N][M]
.. cpp:member:: int a = 42


Variable templates can also be described:

.. cpp:member:: template<class T> \

constexpr T pi = T(3.1415926535897932385)



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

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

A typedef-like declaration of a type. .. cpp:type:: MyContainer::const_iterator
Declaration of a type alias with unspecified type. .. cpp:type:: MyType = std::unordered_map<int, std::string>
Declaration of a type alias.


A type alias can also be templated:

.. cpp:type:: template<typename T> \

MyContainer = std::vector<T>


The example are rendered as follows.

A typedef-like declaration of a type.

Declaration of a type alias with unspecified type.




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

.. cpp:enum:: MyEnum

An unscoped enum. .. cpp:enum:: MySpecificEnum : long
An unscoped enum with specified underlying type. .. cpp:enum-class:: MyScopedEnum
A scoped enum. .. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type
A scoped enum with non-default visibility, and with a specified
underlying type.



.. cpp:enumerator:: name
.. cpp:enumerator:: name = constant
Describe an enumerator, optionally with its value defined, e.g.,:

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



.. cpp:union:: name
Describe a union.

Added in version 1.8.


.. cpp:concept:: template-parameter-list name

WARNING:

The support for concepts is experimental. It is based on the current draft standard and the Concepts Technical Specification. The features may change as they evolve.


Describe a concept. It must have exactly 1 template parameter list. The name may be a nested name. Example:

.. cpp:concept:: template<typename It> std::Iterator

Proxy to an element of a notional sequence that can be compared,
indirected, or incremented.
**Notation**
.. cpp:var:: It r
An lvalue.
**Valid Expressions**
- :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.
- :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when
:cpp:expr:`r` is incrementable.


This will render as follows:

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

Notation

An lvalue.

Valid Expressions

  • *r, when r is dereferenceable.
  • ++r, with return type It&, when r is incrementable.


Added in version 1.5.


Options

Some directives support options:

  • :no-index-entry: and :no-contents-entry:, see Basic Markup.
  • :tparam-line-spec:, for templated declarations. If specified, each template parameter will be rendered on a separate line.

    Added in version 1.6.


Anonymous Entities

C++ supports anonymous namespaces, classes, enums, and unions. For the sake of documentation they must be given some name that starts with @, e.g., @42 or @data. These names can also be used in cross-references and (type) expressions, though nested symbols will be found even when omitted. The @... name will always be rendered as [anonymous] (possibly as a link).

Example:

.. cpp:class:: Data

.. cpp:union:: @data
.. cpp:var:: int a
.. cpp:var:: double b Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.


This will be rendered as:


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

Added in version 1.8.

Aliasing Declarations

Sometimes it may be helpful list declarations elsewhere than their main documentation, e.g., when creating a synopsis of a class interface. The following directive can be used for this purpose.

.. cpp:alias:: name or function signature
Insert one or more alias declarations. Each entity can be specified as they can in the cpp:any role. If the name of a function is given (as opposed to the complete signature), then all overloads of the function will be listed.

For example:

.. cpp:alias:: Data::a

overload_example::C::f


becomes


whereas:

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

void overload_example::C::f(double d)


becomes


Added in version 2.0.

Options

:maxdepth: int
Insert nested declarations as well, up to the total depth given. Use 0 for infinite depth and 1 for just the mentioned declaration. Defaults to 1.

Added in version 3.5.


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

Added in version 3.5.



Constrained Templates

WARNING:

The support for concepts is experimental. It is based on the current draft standard and the Concepts Technical Specification. The features may change as they evolve.


NOTE:

Sphinx does not currently support requires clauses.


Placeholders

Declarations may use the name of a concept to introduce constrained template parameters, or the keyword auto to introduce unconstrained template parameters:

.. cpp:function:: void f(auto &&arg)

A function template with a single unconstrained template parameter. .. cpp:function:: void f(std::Iterator it)
A function template with a single template parameter, constrained by the
Iterator concept.


Template Introductions

Simple constrained function or class templates can be declared with a template introduction instead of a template parameter list:

.. cpp:function:: std::Iterator{It} void advance(It &it)

A function template with a template parameter constrained to be an
Iterator. .. cpp:class:: std::LessThanComparable{T} MySortedContainer
A class template with a template parameter constrained to be
LessThanComparable.


They are rendered as follows.

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

A class template with a template parameter constrained to be LessThanComparable.

Note however that no checking is performed with respect to parameter compatibility. E.g., Iterator{A, B, C} will be accepted as an introduction even though it would not be valid C++.

Inline Expressions and Types

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

.. cpp:var:: int a = 42
.. cpp:function:: int f(int i)
An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`).
A type: :cpp:expr:`const MySortedContainer<int>&`
(or as text :cpp:texpr:`const MySortedContainer<int>&`).


will be rendered as follows:



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

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

Added in version 1.7: The cpp:expr role.

Added in version 1.8: The cpp:texpr role.


Namespacing

Declarations in the C++ domain are as default placed in global scope. The current scope can be changed using three namespace directives. They manage a stack declarations where cpp:namespace resets the stack and changes a given scope.

The cpp:namespace-push directive changes the scope to a given inner scope of the current one.

The cpp:namespace-pop directive undoes the most recent cpp:namespace-push directive.

.. cpp:namespace:: scope specification
Changes the current scope for the subsequent objects to the given scope, and resets the namespace directive stack. Note that the namespace does not need to correspond to C++ namespaces, but can end in names of classes, e.g.,:

.. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass


All subsequent objects will be defined as if their name were declared with the scope prepended. The subsequent cross-references will be searched for starting in the current scope.

Using NULL, 0, or nullptr as the scope will change to global scope.

A namespace declaration can also be templated, e.g.,:

.. cpp:class:: template<typename T> \

std::vector .. cpp:namespace:: template<typename T> std::vector .. cpp:function:: std::size_t size() const


declares size as a member function of the class template std::vector. Equivalently this could have been declared using:

.. cpp:class:: template<typename T> \

std::vector
.. cpp:function:: std::size_t size() const


or:

.. cpp:class:: template<typename T> \

std::vector



.. cpp:namespace-push:: scope specification
Change the scope relatively to the current scope. For example, after:

.. cpp:namespace:: A::B
.. cpp:namespace-push:: C::D


the current scope will be A::B::C::D.

Added in version 1.4.


.. cpp:namespace-pop::
Undo the previous cpp:namespace-push directive (not just pop a scope). For example, after:

.. cpp:namespace:: A::B
.. cpp:namespace-push:: C::D
.. cpp:namespace-pop::


the current scope will be A::B (not A::B::C).

If no previous cpp:namespace-push directive has been used, but only a cpp:namespace directive, then the current scope will be reset to global scope. That is, .. cpp:namespace:: A::B is equivalent to:

.. cpp:namespace:: nullptr
.. cpp:namespace-push:: A::B


Added in version 1.4.


Info field lists

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

tparam: Description of a template parameter.

The cpp:function directive additionally supports the following fields:

  • param, parameter, arg, argument: Description of a parameter.
  • returns, return: Description of a return value.
  • retval, retvals: An alternative to returns for describing the result of the function.
  • throws, throw, exception: Description of a possibly thrown exception.

Added in version 4.3: The retval field type.

Cross-referencing

These roles link to the given declaration types:

:cpp:any:
:cpp:class:
:cpp:struct:
:cpp:func:
:cpp:member:
:cpp:var:
:cpp:type:
:cpp:concept:
:cpp:enum:
:cpp:enumerator:
Reference a C++ declaration by name (see below for details). The name must be properly qualified relative to the position of the link.

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


These roles follow the Sphinx Cross-referencing syntax rules. This means care must be taken when referencing a (partial) template specialization, e.g. if the link looks like this: :cpp:class:`MyClass<int>`. This is interpreted as a link to int with a title of MyClass. In this case, escape the opening angle bracket with a backslash, like this: :cpp:class:`MyClass\<int>`.

When a custom title is not needed it may be useful to use the roles for inline expressions, cpp:expr and cpp:texpr, where angle brackets do not need escaping.



Declarations without template parameters and template arguments

For linking to non-templated declarations the name must be a nested name, e.g., f or MyClass::f.

Overloaded (member) functions

When a (member) function is referenced using just its name, the reference will point to an arbitrary matching overload. The cpp:any and cpp:func roles use an alternative format, which simply is a complete function declaration. This will resolve to the exact matching overload. As example, consider the following class declaration:


References using the cpp:func role:

  • Arbitrary overload: C::f, C::f()
  • Also arbitrary overload: C::f(), C::f()
  • Specific overload: void C::f(), void C::f()
  • Specific overload: void C::f(int), void C::f(int)
  • Specific overload: void C::f(double), void C::f(double)
  • Specific overload: void C::f(double) const, void C::f(double) const

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

Templated declarations

Assume the following declarations.


In general the reference must include the template parameter declarations, and template arguments for the prefix of qualified names. For example:

  • template\<typename TOuter> Wrapper::Outer (template<typename TOuter> Wrapper::Outer)
  • template\<typename TOuter> template\<typename TInner> Wrapper::Outer<TOuter>::Inner (template<typename TOuter> template<typename TInner> Wrapper::Outer<TOuter>::Inner)

Currently the lookup only succeed if the template parameter identifiers are equal strings. That is, template\<typename UOuter> Wrapper::Outer will not work.

As a shorthand notation, if a template parameter list is omitted, then the lookup will assume either a primary template or a non-template, but not a partial template specialisation. This means the following references work as well:

  • Wrapper::Outer (Wrapper::Outer)
  • Wrapper::Outer::Inner (Wrapper::Outer::Inner)
  • template\<typename TInner> Wrapper::Outer::Inner (template<typename TInner> Wrapper::Outer::Inner)

(Full) Template Specialisations

Assume the following declarations.



In general the reference must include a template parameter list for each template argument list. The full specialisation above can therefore be referenced with template\<> Outer\<int> (template<> Outer<int>) and template\<> template\<> Outer\<int>::Inner\<bool> (template<> template<> Outer<int>::Inner<bool>). As a shorthand the empty template parameter list can be omitted, e.g., Outer\<int> (Outer<int>) and Outer\<int>::Inner\<bool> (Outer<int>::Inner<bool>).

Partial Template Specialisations

Assume the following declaration.


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

Configuration Variables

See Options for the C++ domain.

The JavaScript Domain

Added in version 1.0.

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

.. js:module:: name
This directive sets the module name for object declarations that follow after. The module name is used in the global module index and in cross references. This directive does not create an object heading like py:class would, for example.

By default, this directive will create a linkable entity and will cause an entry in the global module index, unless the no-index option is specified. If this option is specified, the directive will only update the current module name.

Added in version 1.6.

Changed in version 5.2: Module directives support body content.


.. js:function:: name(signature)
Describes a JavaScript function or method. If you want to describe arguments as optional use square brackets as documented for Python signatures.

You can use fields to give more details about arguments and their expected types, errors which may be thrown by the function, and the value being returned:

.. js:function:: $.getJSON(href, callback[, errback])

:param string href: An URI to the location of the resource.
:param callback: Gets called with the object.
:param errback:
Gets called in case the request fails. And a lot of other
text so we need multiple lines.
:throws SomeError: For whatever reason in that case.
:returns: Something.


This is rendered as:

$.getJSON(href, callback[, errback])
  • href (string()) -- An URI to the location of the resource.
  • callback -- Gets called with the object.
  • errback -- Gets called in case the request fails. And a lot of other text so we need multiple lines.

SomeError() -- For whatever reason in that case.
Something.


:single-line-parameter-list: (no value)
Ensures that the function's parameters will be emitted on a single logical line, overriding javascript_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.1.



.. js:method:: name(signature)
This directive is an alias for js:function, however it describes a function that is implemented as a method on a class object.

Added in version 1.6.

:single-line-parameter-list: (no value)
Ensures that the function's parameters will be emitted on a single logical line, overriding javascript_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.1.



.. js:class:: name
Describes a constructor that creates an object. This is basically like a function but will show up with a class prefix:

.. js:class:: MyAnimal(name[, age])

:param string name: The name of the animal
:param number age: an optional age for the animal


This is rendered as:

class MyAnimal(name[, age])
  • name (string()) -- The name of the animal
  • age (number()) -- an optional age for the animal



:single-line-parameter-list: (no value)
Ensures that the function's parameters will be emitted on a single logical line, overriding javascript_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.1.



.. js:data:: name
Describes a global variable or constant.

.. js:attribute:: object.name
Describes the attribute name of object.

These roles are provided to refer to the described objects:

:js:mod:
:js:func:
:js:meth:
:js:class:
:js:data:
:js:attr:

The Mathematics Domain

Added in version 1.8.

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

:math:numref:
Role for cross-referencing equations defined by math directive via their label. Example:

.. math:: e^{i\pi} + 1 = 0

:label: euler Euler's identity, equation :math:numref:`euler`, was elected one of the most beautiful mathematical formulas.


Added in version 1.8.


The Python Domain

Added in version 1.0.

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

.. py:module:: name
This directive marks the beginning of the description of a module (or package submodule, in which case the name should be fully qualified, including the package name). A description of the module such as the docstring can be placed in the body of the directive.

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

Changed in version 5.2: Module directives support body content.

options

:platform: platforms (comma separated list)
Indicate platforms which the module is available (if it is available on all platforms, the option should be omitted). The keys are short identifiers; examples that are in use include "IRIX", "Mac", "Windows" and "Unix". It is important to use a key which has already been used when applicable.

:synopsis: purpose (text)
Consist of one sentence describing the module's purpose -- it is currently only used in the Global Module Index.

:deprecated: (no argument)
Mark a module as deprecated; it will be designated as such in various locations then.


.. py:currentmodule:: name
This directive tells Sphinx that the classes, functions etc. documented from here are in the given module (like py:module), but it will not create index entries, an entry in the Global Module Index, or a link target for py:mod. This is helpful in situations where documentation for things in a module is spread over multiple files or sections -- one location has the py:module directive, the others only py:currentmodule.

The following directives are provided for module and class contents:

.. py:function:: name(parameters)
.. py:function:: name[type parameters](parameters)
Describes a module-level function. The signature should include the parameters, together with optional type parameters, as given in the Python function definition, see Python Signatures. For example:

.. py:function:: Timer.repeat(repeat=3, number=1_000_000)
.. py:function:: add[T](a: T, b: T) -> T


For methods you should use py:method.

The description normally includes information about the parameters required and how they are used (especially whether mutable objects passed as parameters are modified), side effects, and possible exceptions.

This information can (in any py directive) optionally be given in a structured form, see Info field lists.

options

:async: (no value)
Indicate the function is an async function.

Added in version 2.1.


:canonical: (full qualified name including module name)
Describe the location where the object is defined if the object is imported from other modules

Added in version 4.0.


:single-line-parameter-list: (no value)
Ensures that the function's arguments will be emitted on a single logical line, overriding python_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.1.


:single-line-type-parameter-list: (no value)
Ensure that the function's type parameters are emitted on a single logical line, overriding python_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.1.



.. py:data:: name
Describes global data in a module, including both variables and values used as "defined constants." Class and object attributes are not documented using this environment.

options

:type: type of the variable (text)
Added in version 2.4.


:value: initial value of the variable (text)
Added in version 2.4.


:canonical: (full qualified name including module name)
Describe the location where the object is defined if the object is imported from other modules

Added in version 4.0.



.. py:exception:: name
.. py:exception:: name(parameters)
.. py:exception:: name[type parameters](parameters)
Describes an exception class. The signature can, but need not include parentheses with constructor arguments, or may optionally include type parameters (see PEP 695).

options

:final: (no value)
Indicate the class is a final class.

Added in version 3.1.


:single-line-parameter-list: (no value)
See py:class:single-line-parameter-list.

Added in version 7.1.


:single-line-type-parameter-list: (no value)
See py:class:single-line-type-parameter-list.

Added in version 7.1.



.. py:class:: name
.. py:class:: name(parameters)
.. py:class:: name[type parameters](parameters)
Describes a class. The signature can optionally include type parameters (see PEP 695) or parentheses with parameters which will be shown as the constructor arguments. See also Python Signatures.

Methods and attributes belonging to the class should be placed in this directive's body. If they are placed outside, the supplied name should contain the class name so that cross-references still work. Example:

.. py:class:: Foo

.. py:method:: quux() -- or -- .. py:class:: Bar .. py:method:: Bar.quux()


The first way is the preferred one.

options

:canonical: (full qualified name including module name)
Describe the location where the object is defined if the object is imported from other modules

Added in version 4.0.


:final: (no value)
Indicate the class is a final class.

Added in version 3.1.


:single-line-parameter-list: (no value)
Ensures that the class constructor's arguments will be emitted on a single logical line, overriding python_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.1.


:single-line-type-parameter-list: (no value)
Ensure that the class type parameters are emitted on a single logical line, overriding python_maximum_signature_line_length and maximum_signature_line_length.


.. py:attribute:: name
Describes an object data attribute. The description should include information about the type of the data to be expected and whether it may be changed directly.

options

:type: type of the attribute (text)
Added in version 2.4.


:value: initial value of the attribute (text)
Added in version 2.4.


:canonical: (full qualified name including module name)
Describe the location where the object is defined if the object is imported from other modules

Added in version 4.0.



.. py:property:: name
Describes an object property.

Added in version 4.0.

options

:abstractmethod: (no value)
Indicate the property is abstract.

:classmethod: (no value)
Indicate the property is a classmethod.

Added in version 4.2.


:type: type of the property (text)


.. py:method:: name(parameters)
.. py:method:: name[type parameters](parameters)
Describes an object method. The parameters should not include the self parameter. The description should include similar information to that described for function. See also Python Signatures and Info field lists.

options

:abstractmethod: (no value)
Indicate the method is an abstract method.

Added in version 2.1.


:async: (no value)
Indicate the method is an async method.

Added in version 2.1.


:canonical: (full qualified name including module name)
Describe the location where the object is defined if the object is imported from other modules

Added in version 4.0.


:classmethod: (no value)
Indicate the method is a class method.

Added in version 2.1.


:final: (no value)
Indicate the method is a final method.

Added in version 3.1.


:single-line-parameter-list: (no value)
Ensures that the method's arguments will be emitted on a single logical line, overriding python_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.1.


:single-line-type-parameter-list: (no value)
Ensure that the method's type parameters are emitted on a single logical line, overriding python_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.2.


:staticmethod: (no value)
Indicate the method is a static method.

Added in version 2.1.



.. py:staticmethod:: name(parameters)
.. py:staticmethod:: name[type parameters](parameters)
Like py:method, but indicates that the method is a static method.

Added in version 0.4.


.. py:classmethod:: name(parameters)
.. py:classmethod:: name[type parameters](parameters)
Like py:method, but indicates that the method is a class method.

Added in version 0.6.


.. py:decorator:: name
.. py:decorator:: name(parameters)
.. py:decorator:: name[type parameters](parameters)
Describes a decorator function. The signature should represent the usage as a decorator. For example, given the functions

def removename(func):

func.__name__ = ''
return func def setnewname(name):
def decorator(func):
func.__name__ = name
return func
return decorator


the descriptions should look like this:

.. py:decorator:: removename

Remove name of the decorated function. .. py:decorator:: setnewname(name)
Set name of the decorated function to *name*.


(as opposed to .. py:decorator:: removename(func).)

There is no py:deco role to link to a decorator that is marked up with this directive; rather, use the py:func role.

:single-line-parameter-list: (no value)
Ensures that the decorator's arguments will be emitted on a single logical line, overriding python_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.1.


:single-line-type-parameter-list: (no value)
Ensure that the decorator's type parameters are emitted on a single logical line, overriding python_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.2.



.. py:decoratormethod:: name
.. py:decoratormethod:: name(signature)
.. py:decoratormethod:: name[type parameters](signature)
Same as py:decorator, but for decorators that are methods.

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


Python Signatures

Signatures of functions, methods and class constructors can be given like they would be written in Python.

Default values for optional arguments can be given (but if they contain commas, they will confuse the signature parser). Python 3-style argument annotations can also be given as well as return type annotations:

.. py:function:: compile(source : string, filename, symbol='file') -> ast object


For functions with optional parameters that don't have default values (typically functions implemented in C extension modules without keyword argument support), you can use brackets to specify the optional parts:


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

Python 3.12 introduced type parameters, which are type variables declared directly within the class or function definition:

class AnimalList[AnimalT](list[AnimalT]):

... def add[T](a: T, b: T) -> T:
return a + b


The corresponding reStructuredText documentation would be:

.. py:class:: AnimalList[AnimalT]
.. py:function:: add[T](a: T, b: T) -> T


See PEP 695 and PEP 696 for details and the full specification.

Info field lists

Added in version 0.4.

Changed in version 3.0: meta fields are added.

Inside Python object description directives, reST field lists with these fields are recognized and formatted nicely:

  • param, parameter, arg, argument, key, keyword: Description of a parameter.
  • type: Type of a parameter. Creates a link if possible.
  • raises, raise, except, exception: That (and when) a specific exception is raised.
  • var, ivar, cvar: Description of a variable.
  • vartype: Type of a variable. Creates a link if possible.
  • returns, return: Description of the return value.
  • rtype: Return type. Creates a link if possible.
  • meta: Add metadata to description of the python object. The metadata will not be shown on output document. For example, :meta private: indicates the python object is private member. It is used in sphinx.ext.autodoc for filtering members.

NOTE:

In current release, all var, ivar and cvar are represented as "Variable". There is no difference at all.


The field names must consist of one of these keywords and an argument (except for returns and rtype, which do not need an argument). This is best explained by an example:

.. py:function:: send_message(sender, recipient, message_body, [priority=1])

Send a message to a recipient
:param str sender: The person sending the message
:param str recipient: The recipient of the message
:param str message_body: The body of the message
:param priority: The priority of the message, can be a number 1-5
:type priority: integer or None
:return: the message id
:rtype: int
:raises ValueError: if the message_body exceeds 160 characters
:raises TypeError: if the message_body is not a basestring


This will render like this:

Send a message to a recipient
  • sender (str) -- The person sending the message
  • recipient (str) -- The recipient of the message
  • message_body (str) -- The body of the message
  • priority (int or None) -- The priority of the message, can be a number 1-5

the message id
int
  • ValueError -- if the message_body exceeds 160 characters
  • TypeError -- if the message_body is not a basestring



It is also possible to combine parameter type and description, if the type is a single word, like this:

:param int priority: The priority of the message, can be a number 1-5


Added in version 1.5.

Container types such as lists and dictionaries can be linked automatically using the following syntax:

:type priorities: list(int)
:type priorities: list[int]
:type mapping: dict(str, int)
:type mapping: dict[str, int]
:type point: tuple(float, float)
:type point: tuple[float, float]


Multiple types in a type field will be linked automatically if separated by the word "or":

:type an_arg: int or None
:vartype a_var: str or int
:rtype: float or str


Cross-referencing Python objects

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

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

:py:func:
Reference a Python function; dotted names may be used. The role text needs not include trailing parentheses to enhance readability; they will be added automatically by Sphinx if the add_function_parentheses config value is True (the default).

:py:data:
Reference a module-level variable.

:py:const:
Reference a "defined" constant. This may be a Python variable that is not intended to be changed.

:py:class:
Reference a class; a dotted name may be used.

:py:meth:
Reference a method of an object. The role text can include the type name and the method name; if it occurs within the description of a type, the type name can be omitted. A dotted name may be used.

:py:attr:
Reference a data attribute of an object.

NOTE:

The role is also able to refer to property.



:py:exc:
Reference an exception. A dotted name may be used.

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

Added in version 0.4.


The name enclosed in this markup can include a module name and/or a class name. For example, :py:func:`filter` could refer to a function named filter in the current module, or the built-in function of that name. In contrast, :py:func:`foo.filter` clearly refers to the filter function in the foo module.

Normally, names in these roles are searched first without any further qualification, then with the current module name prepended, then with the current module and class name (if any) prepended. If you prefix the name with a dot, this order is reversed. For example, in the documentation of Python's codecs module, :py:func:`open` always refers to the built-in function, while :py:func:`.open` refers to codecs.open().

A similar heuristic is used to determine whether the name is an attribute of the currently documented class.

Also, if the name is prefixed with a dot, and no exact match is found, the target is taken as a suffix and all object names with that suffix are searched. For example, :py:meth:`.TarFile.close` references the tarfile.TarFile.close() function, even if the current module is not tarfile. Since this can get ambiguous, if there is more than one possible match, you will get a warning from Sphinx.

Note that you can combine the ~ and . prefixes: :py:meth:`~.TarFile.close` will reference the tarfile.TarFile.close() method, but the visible link caption will only be close().

The reStructuredText Domain

Added in version 1.0.

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

.. rst:directive:: name
Describes a reST directive. The name can be a single directive name or actual directive syntax (.. prefix and :: suffix) with arguments that will be rendered differently. For example:

.. rst:directive:: foo

Foo description. .. rst:directive:: .. bar:: baz
Bar description.


will be rendered as:

.. foo::
Foo description.

.. bar:: baz
Bar description.


.. rst:directive:option:: name
Describes an option for reST directive. The name can be a single option name or option name with arguments which separated with colon (:). For example:

.. rst:directive:: toctree

.. rst:directive:option:: caption: caption of ToC
.. rst:directive:option:: glob


will be rendered as:

.. toctree::
:caption: caption of ToC

:glob:


options

:type: description of argument (text)
Describe the type of option value.

For example:

.. rst:directive:: toctree

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


Added in version 2.1.



.. rst:role:: name
Describes a reST role. For example:

.. rst:role:: foo

Foo description.


will be rendered as:

:foo:
Foo description.


These roles are provided to refer to the described objects:

:rst:dir:
:rst:role:

More domains

There are several third-party domains available as extensions, including:

  • Ada
  • Chapel
  • CoffeeScript
  • Common Lisp
  • dqn
  • Erlang
  • Go
  • HTTP
  • Jinja
  • Lasso
  • MATLAB
  • Operation
  • PHP
  • Ruby
  • Scala

Extensions

Since many projects will need special features in their documentation, Sphinx allows adding "extensions" to the build process, each of which can modify almost any aspect of document processing.

This chapter describes the extensions bundled with Sphinx. For the API documentation on writing your own extension, refer to Sphinx Extensions API.

Built-in extensions

These extensions are built in and can be activated by respective entries in the extensions configuration value:

sphinx.ext.autodoc -- Include documentation from docstrings

This extension can import the modules you are documenting, and pull in documentation from docstrings in a semi-automatic way.

NOTE:

For Sphinx (actually, the Python interpreter that executes Sphinx) to find your module, it must be importable. That means that the module or the package must be in one of the directories on sys.path -- adapt your sys.path in the configuration file accordingly.


WARNING:

autodoc imports the modules to be documented. If any modules have side effects on import, these will be executed by autodoc when sphinx-build is run.

If you document scripts (as opposed to library modules), make sure their main routine is protected by a if __name__ == '__main__' condition.



For this to work, the docstrings must of course be written in correct reStructuredText. You can then use all of the usual Sphinx markup in the docstrings, and it will end up correctly in the documentation. Together with hand-written documentation, this technique eases the pain of having to maintain two locations for documentation, while at the same time avoiding auto-generated-looking pure API documentation.

If you prefer NumPy or Google style docstrings over reStructuredText, you can also enable the napoleon extension. napoleon is a preprocessor that converts your docstrings to correct reStructuredText before autodoc processes them.

Directives

autodoc provides several directives that are versions of the usual py:module, py:class and so forth. On parsing time, they import the corresponding module and extract the docstring of the given objects, inserting them into the page source under a suitable py:module, py:class etc. directive.

NOTE:

Just as py:class respects the current py:module, autoclass will also do so. Likewise, automethod will respect the current py:class.


.. automodule::
.. autoclass::
.. autoexception::
Document a module, class or exception. All three directives will by default only insert the docstring of the object itself:

.. autoclass:: Noodle


will produce source like this:

.. class:: Noodle

Noodle's docstring.


The "auto" directives can also contain content of their own, it will be inserted into the resulting non-auto directive source after the docstring (but before any automatic member documentation).

Therefore, you can also mix automatic and non-automatic member documentation, like so:

.. autoclass:: Noodle

:members: eat, slurp
.. method:: boil(time=10)
Boil the noodle *time* minutes.


Options

:members: (no value or comma separated list)
If set, autodoc will generate document for the members of the target module, class or exception.

For example:

.. automodule:: noodle

:members:


will document all module members (recursively), and

.. autoclass:: Noodle

:members:


will document all class member methods and properties.

By default, autodoc will not generate document for the members that are private, not having docstrings, inherited from super class, or special members.

For modules, __all__ will be respected when looking for members unless you give the ignore-module-all flag option. Without ignore-module-all, the order of the members will also be the order in __all__.

You can also give an explicit list of members; only these will then be documented:

.. autoclass:: Noodle

:members: eat, slurp



:undoc-members: (no value)
If set, autodoc will also generate document for the members not having docstrings:

.. automodule:: noodle

:members:
:undoc-members:



:private-members: (no value or comma separated list)
If set, autodoc will also generate document for the private members (that is, those named like _private or __private):

.. automodule:: noodle

:members:
:private-members:


It can also take an explicit list of member names to be documented as arguments:

.. automodule:: noodle

:members:
:private-members: _spicy, _garlickly


Added in version 1.1.

Changed in version 3.2: The option can now take arguments.


:special-members: (no value or comma separated list)
If set, autodoc will also generate document for the special members (that is, those named like __special__):

.. autoclass:: my.Class

:members:
:special-members:


It can also take an explicit list of member names to be documented as arguments:

.. autoclass:: my.Class

:members:
:special-members: __init__, __name__


Added in version 1.1.

Changed in version 1.2: The option can now take arguments


Options and advanced usage

If you want to make the members option (or other options described below) the default, see autodoc_default_options.

TIP:

You can use a negated form, 'no-flag', as an option of autodoc directive, to disable it temporarily. For example:

.. automodule:: foo

:no-undoc-members:




TIP:

You can use autodoc directive options to temporarily override or extend default options which takes list as an input. For example:

.. autoclass:: Noodle

:members: eat
:private-members: +_spicy, _garlickly




Changed in version 3.5: The default options can be overridden or extended temporarily.

autodoc considers a member private if its docstring contains :meta private: in its Info field lists. For example:

def my_function(my_arg, my_other_arg):

"""blah blah blah
:meta private:
"""


Added in version 3.0.

autodoc considers a member public if its docstring contains :meta public: in its Info field lists, even if it starts with an underscore. For example:

def _my_function(my_arg, my_other_arg):

"""blah blah blah
:meta public:
"""


Added in version 3.1.

autodoc considers a variable member does not have any default value if its docstring contains :meta hide-value: in its Info field lists. Example:

var1 = None  #: :meta hide-value:


Added in version 3.5.

For classes and exceptions, members inherited from base classes will be left out when documenting all members, unless you give the inherited-members option, in addition to members:

.. autoclass:: Noodle

:members:
:inherited-members:


This can be combined with undoc-members to document all available members of the class or module.

It can take an ancestor class not to document inherited members from it. By default, members of object class are not documented. To show them all, give None to the option.

For example; If your class Foo is derived from list class and you don't want to document list.__len__(), you should specify a option :inherited-members: list to avoid special members of list class.

Another example; If your class Foo has __str__ special method and autodoc directive has both inherited-members and special-members, __str__ will be documented as in the past, but other special method that are not implemented in your class Foo.

Since v5.0, it can take a comma separated list of ancestor classes. It allows to suppress inherited members of several classes on the module at once by specifying the option to automodule directive.

Note: this will lead to markup errors if the inherited members come from a module whose docstrings are not reST formatted.

Added in version 0.3.

Changed in version 3.0: It takes an ancestor class name as an argument.

Changed in version 5.0: It takes a comma separated list of ancestor class names.

It's possible to override the signature for explicitly documented callable objects (functions, methods, classes) with the regular syntax that will override the signature gained from introspection:

.. autoclass:: Noodle(type)

.. automethod:: eat(persona)


This is useful if the signature from the method is hidden by a decorator.

Added in version 0.4.

  • The automodule, autoclass and autoexception directives also support a flag option called show-inheritance. When given, a list of base classes will be inserted just below the class signature (when used with automodule, this will be inserted for every class that is documented in the module).

    Added in version 0.4.

  • All autodoc directives support the no-index flag option that has the same effect as for standard py:function etc. directives: no index entries are generated for the documented object (and all autodocumented members).

    Added in version 0.4.

  • automodule also recognizes the synopsis, platform and deprecated options that the standard py:module directive supports.

    Added in version 0.5.

  • automodule and autoclass also has an member-order option that can be used to override the global value of autodoc_member_order for one directive.

    Added in version 0.6.

  • The directives supporting member documentation also have a exclude-members option that can be used to exclude single member names from documentation, if all members are to be documented.

    Added in version 0.6.

  • In an automodule directive with the members option set, only module members whose __module__ attribute is equal to the module name as given to automodule will be documented. This is to prevent documentation of imported classes or functions. Set the imported-members option if you want to prevent this behavior and document all available members. Note that attributes from imported modules will not be documented, because attribute documentation is discovered by parsing the source file of the current module.

    Added in version 1.2.

  • Add a list of modules in the autodoc_mock_imports to prevent import errors to halt the building process when some external dependencies are not importable at build time.

    Added in version 1.3.

  • As a hint to autodoc extension, you can put a :: separator in between module name and object name to let autodoc know the correct module name if it is ambiguous.

.. autoclass:: module.name::Noodle


autoclass also recognizes the class-doc-from option that can be used to override the global value of autoclass_content.

Added in version 4.1.



.. autofunction::
.. autodecorator::
.. autodata::
.. automethod::
.. autoattribute::
.. autoproperty::
These work exactly like autoclass etc., but do not offer the options used for automatic member documentation.

autodata and autoattribute support the annotation option. The option controls how the value of variable is shown. If specified without arguments, only the name of the variable will be printed, and its value is not shown:

.. autodata:: CD_DRIVE

:annotation:


If the option specified with arguments, it is printed after the name as a value of the variable:

.. autodata:: CD_DRIVE

:annotation: = your CD device name


By default, without annotation option, Sphinx tries to obtain the value of the variable and print it after the name.

The no-value option can be used instead of a blank annotation to show the type hint but not the value:

.. autodata:: CD_DRIVE

:no-value:


If both the annotation and no-value options are used, no-value has no effect.

For module data members and class attributes, documentation can either be put into a comment with special formatting (using a #: to start the comment instead of just #), or in a docstring after the definition. Comments need to be either on a line of their own before the definition, or immediately after the assignment on the same line. The latter form is restricted to one line only.

This means that in the following class definition, all attributes can be autodocumented:

class Foo:

"""Docstring for class Foo."""
#: Doc comment for class attribute Foo.bar.
#: It can have multiple lines.
bar = 1
flox = 1.5 #: Doc comment for Foo.flox. One line only.
baz = 2
"""Docstring for class attribute Foo.baz."""
def __init__(self):
#: Doc comment for instance attribute qux.
self.qux = 3
self.spam = 4
"""Docstring for instance attribute spam."""


Changed in version 0.6: autodata and autoattribute can now extract docstrings.

Changed in version 1.1: Comment docs are now allowed on the same line after an assignment.

Changed in version 1.2: autodata and autoattribute have an annotation option.

Changed in version 2.0: autodecorator added.

Changed in version 2.1: autoproperty added.

Changed in version 3.4: autodata and autoattribute now have a no-value option.

NOTE:

If you document decorated functions or methods, keep in mind that autodoc retrieves its docstrings by importing the module and inspecting the __doc__ attribute of the given function or method. That means that if a decorator replaces the decorated function with another, it must copy the original __doc__ to the new function.



Configuration

There are also config values that you can set:

This value selects what content will be inserted into the main body of an autoclass directive. The possible values are:
"class"
Only the class' docstring is inserted. This is the default. You can still document __init__ as a separate method using automethod or the members option to autoclass.
"both"
Both the class' and the __init__ method's docstring are concatenated and inserted.
"init"
Only the __init__ method's docstring is inserted.

Added in version 0.3.

If the class has no __init__ method or if the __init__ method's docstring is empty, but the class has a __new__ method's docstring, it is used instead.

Added in version 1.4.


This value selects how the signature will be displayed for the class defined by autoclass directive. The possible values are:
"mixed"
Display the signature with the class name.
"separated"
Display the signature as a method.

The default is "mixed".

Added in version 4.1.


This value selects if automatically documented members are sorted alphabetical (value 'alphabetical'), by member type (value 'groupwise') or by source order (value 'bysource'). The default is alphabetical.

Note that for source order, the module must be a Python module with the source code available.

Added in version 0.6.

Changed in version 1.0: Support for 'bysource'.


This value is a list of autodoc directive flags that should be automatically applied to all autodoc directives. The supported flags are 'members', 'undoc-members', 'private-members', 'special-members', 'inherited-members', 'show-inheritance', 'ignore-module-all' and 'exclude-members'.

Added in version 1.0.

Deprecated since version 1.8: Integrated into autodoc_default_options.


The default options for autodoc directives. They are applied to all autodoc directives automatically. It must be a dictionary which maps option names to the values. For example:

autodoc_default_options = {

'members': 'var1, var2',
'member-order': 'bysource',
'special-members': '__init__',
'undoc-members': True,
'exclude-members': '__weakref__' }


Setting None or True to the value is equivalent to giving only the option name to the directives.

The supported options are 'members', 'member-order', 'undoc-members', 'private-members', 'special-members', 'inherited-members', 'show-inheritance', 'ignore-module-all', 'imported-members', 'exclude-members', 'class-doc-from' and 'no-value'.

Added in version 1.8.

Changed in version 2.0: Accepts True as a value.

Changed in version 2.1: Added 'imported-members'.

Changed in version 4.1: Added 'class-doc-from'.

Changed in version 4.5: Added 'no-value'.


Functions imported from C modules cannot be introspected, and therefore the signature for such functions cannot be automatically determined. However, it is an often-used convention to put the signature into the first line of the function's docstring.

If this boolean value is set to True (which is the default), autodoc will look at the first line of the docstring for functions and methods, and if it looks like a signature, use the line as the signature and remove it from the docstring content.

autodoc will continue to look for multiple signature lines, stopping at the first line that does not look like a signature. This is useful for declaring overloaded function signatures.

Added in version 1.1.

Changed in version 3.1: Support overloaded signatures

Changed in version 4.0: Overloaded signatures do not need to be separated by a backslash


This value contains a list of modules to be mocked up. This is useful when some external dependencies are not met at build time and break the building process. You may only specify the root package of the dependencies themselves and omit the sub-modules:

autodoc_mock_imports = ["django"]


Will mock all imports under the django package.

Added in version 1.3.

Changed in version 1.6: This config value only requires to declare the top-level modules that should be mocked.


This value controls how to represent typehints. The setting takes the following values:
  • 'signature' -- Show typehints in the signature (default)
  • 'description' -- Show typehints as content of the function or method The typehints of overloaded functions or methods will still be represented in the signature.
  • 'none' -- Do not show typehints
  • 'both' -- Show typehints in the signature and as content of the function or method

Overloaded functions or methods will not have typehints included in the description because it is impossible to accurately represent all possible overloads as a list of parameters.

Added in version 2.1.

Added in version 3.0: New option 'description' is added.

Added in version 4.1: New option 'both' is added.


This value controls whether the types of undocumented parameters and return values are documented when autodoc_typehints is set to description.

The default value is "all", meaning that types are documented for all parameters and return values, whether they are documented or not.

When set to "documented", types will only be documented for a parameter or a return value that is already documented by the docstring.

With "documented_params", parameter types will only be annotated if the parameter is documented in the docstring. The return type is always annotated (except if it is None).

Added in version 4.0.

Added in version 5.0: New option 'documented_params' is added.


A dictionary for users defined type aliases that maps a type name to the full-qualified object name. It is used to keep type aliases not evaluated in the document. Defaults to empty ({}).

The type aliases are only available if your program enables Postponed Evaluation of Annotations (PEP 563) feature via from __future__ import annotations.

For example, there is code using a type alias:

from __future__ import annotations
AliasType = Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]
def f() -> AliasType:

...


If autodoc_type_aliases is not set, autodoc will generate internal mark-up from this code as following:

.. py:function:: f() -> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]

...


If you set autodoc_type_aliases as {'AliasType': 'your.module.AliasType'}, it generates the following document internally:

.. py:function:: f() -> your.module.AliasType:

...


Added in version 3.3.


This value controls the format of typehints. The setting takes the following values:
  • 'fully-qualified' -- Show the module name and its name of typehints
  • 'short' -- Suppress the leading module names of the typehints (ex. io.StringIO -> StringIO) (default)

Added in version 4.4.

Changed in version 5.0: The default setting was changed to 'short'


If True, the default argument values of functions will be not evaluated on generating document. It preserves them as is in the source code.

Added in version 4.0: Added as an experimental feature. This will be integrated into autodoc core in the future.


This value controls the behavior of sphinx-build -W during importing modules. If False is given, autodoc forcedly suppresses the error if the imported module emits warnings. By default, True.

This value controls the docstrings inheritance. If set to True the docstring for classes or methods, if not explicitly set, is inherited from parents.

The default is True.

Added in version 1.7.


autodoc supports to suppress warning messages via suppress_warnings. It allows following warnings types in addition:
  • autodoc
  • autodoc.import_object


Docstring preprocessing

autodoc provides the following additional events:

Added in version 0.4.

Emitted when autodoc has read and processed a docstring. lines is a list of strings -- the lines of the processed docstring -- that the event handler can modify in place to change what Sphinx puts into the output.

  • app -- the Sphinx application object
  • what -- the type of the object which the docstring belongs to (one of "module", "class", "exception", "function", "method", "attribute")
  • name -- the fully qualified name of the object
  • obj -- the object itself
  • options -- the options given to the directive: an object with attributes inherited_members, undoc_members, show_inheritance and no-index that are true if the flag option of same name was given to the auto directive
  • lines -- the lines of the docstring, see above



Added in version 2.4.

Emitted before autodoc formats a signature for an object. The event handler can modify an object to change its signature.

  • app -- the Sphinx application object
  • obj -- the object itself
  • bound_method -- a boolean indicates an object is bound method or not



Added in version 0.5.

Emitted when autodoc has formatted a signature for an object. The event handler can return a new tuple (signature, return_annotation) to change what Sphinx puts into the output.

  • app -- the Sphinx application object
  • what -- the type of the object which the docstring belongs to (one of "module", "class", "exception", "function", "method", "attribute")
  • name -- the fully qualified name of the object
  • obj -- the object itself
  • options -- the options given to the directive: an object with attributes inherited_members, undoc_members, show_inheritance and no-index that are true if the flag option of same name was given to the auto directive
  • signature -- function signature, as a string of the form "(parameter_1, parameter_2)", or None if introspection didn't succeed and signature wasn't specified in the directive.
  • return_annotation -- function return annotation as a string of the form " -> annotation", or None if there is no return annotation



The sphinx.ext.autodoc module provides factory functions for commonly needed docstring processing in event autodoc-process-docstring:

Return a listener that removes the first pre and last post lines of every docstring. If what is a sequence of strings, only docstrings of a type in what will be processed.

Use like this (e.g. in the setup() function of conf.py):

from sphinx.ext.autodoc import cut_lines
app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))


This can (and should) be used in place of automodule_skip_lines.


Return a listener that either keeps, or if exclude is True excludes, lines between lines that match the marker regular expression. If no line matches, the resulting docstring would be empty, so no change will be made unless keepempty is true.

If what is a sequence of strings, only docstrings of a type in what will be processed.


Emitted when autodoc has read and processed a class to determine the base-classes. bases is a list of classes that the event handler can modify in place to change what Sphinx puts into the output. It's emitted only if show-inheritance option given.
  • app -- the Sphinx application object
  • name -- the fully qualified name of the object
  • obj -- the object itself
  • options -- the options given to the class directive
  • bases -- the list of base classes signature. see above.


Added in version 4.1.

Changed in version 4.3: bases can contain a string as a base class name. It will be processed as reST mark-up'ed text.


Skipping members

autodoc allows the user to define a custom method for determining whether a member should be included in the documentation by using the following event:

Added in version 0.5.

Emitted when autodoc has to decide whether a member should be included in the documentation. The member is excluded if a handler returns True. It is included if the handler returns False.

If more than one enabled extension handles the autodoc-skip-member event, autodoc will use the first non-None value returned by a handler. Handlers should return None to fall back to the skipping behavior of autodoc and other enabled extensions.

  • app -- the Sphinx application object
  • what -- the type of the object which the docstring belongs to (one of "module", "class", "exception", "function", "method", "attribute")
  • name -- the fully qualified name of the object
  • obj -- the object itself
  • skip -- a boolean indicating if autodoc will skip this member if the user handler does not override the decision
  • options -- the options given to the directive: an object with attributes inherited_members, undoc_members, show_inheritance and no-index that are true if the flag option of same name was given to the auto directive



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

Added in version 1.4.

This extension allows you to refer sections its title. This affects to the reference role (ref).

For example:

A Plain Title
-------------
This is the text of the section.
It refers to the section title, see :ref:`A Plain Title`.


Internally, this extension generates the labels for each section. If same section names are used in whole of document, any one is used for a target by default. The autosectionlabel_prefix_document configuration variable can be used to make headings which appear multiple times but in different documents unique.

Configuration

True to prefix each section label with the name of the document it is in, followed by a colon. For example, index:Introduction for a section called Introduction that appears in document index.rst. Useful for avoiding ambiguity when the same section heading appears in different documents.

If set, autosectionlabel chooses the sections for labeling by its depth. For example, when set 1 to autosectionlabel_maxdepth, labels are generated only for top level sections, and deeper sections are not labeled. It defaults to None (disabled).

Debugging

The WARNING: undefined label indicates that your reference in ref is mis-spelled. Invoking sphinx-build with -vv (see -v) will print all section names and the labels that have been generated for them. This output can help finding the right reference label.

sphinx.ext.autosummary -- Generate autodoc summaries

Added in version 0.6.

This extension generates function/method/attribute summary lists, similar to those output e.g. by Epydoc and other API doc generation tools. This is especially useful when your docstrings are long and detailed, and putting each one of them on a separate page makes them easier to read.

The sphinx.ext.autosummary extension does this in two parts:

1.
There is an autosummary directive for generating summary listings that contain links to the documented items, and short summary blurbs extracted from their docstrings.
2.
A autosummary directive also generates short "stub" files for the entries listed in its content. These files by default contain only the corresponding sphinx.ext.autodoc directive, but can be customized with templates.

The sphinx-autogen script is also able to generate "stub" files from command line.


.. autosummary::
Insert a table that contains links to documented items, and a short summary blurb (the first sentence of the docstring) for each of them.

The autosummary directive can also optionally serve as a toctree entry for the included items. Optionally, stub .rst files for these items can also be automatically generated when autosummary_generate is True.

For example,

.. currentmodule:: sphinx
.. autosummary::

environment.BuildEnvironment
util.relative_uri


produces a table like this:

environment.BuildEnvironment(app) The environment in which the ReST files are translated.
util.relative_uri(base, to) Return a relative URL from base to to.

Autosummary preprocesses the docstrings and signatures with the same autodoc-process-docstring and autodoc-process-signature hooks as autodoc.

Options

If you want the autosummary table to also serve as a toctree entry, use the toctree option, for example:

.. autosummary::

:toctree: DIRNAME
sphinx.environment.BuildEnvironment
sphinx.util.relative_uri


The toctree option also signals to the sphinx-autogen script that stub pages should be generated for the entries listed in this directive. The option accepts a directory name as an argument; sphinx-autogen will by default place its output in this directory. If no argument is given, output is placed in the same directory as the file that contains the directive.

You can also use caption option to give a caption to the toctree.

Added in version 3.1: caption option added.

If you don't want the autosummary to show function signatures in the listing, include the nosignatures option:

.. autosummary::

:nosignatures:
sphinx.environment.BuildEnvironment
sphinx.util.relative_uri


You can specify a custom template with the template option. For example,

.. autosummary::

:template: mytemplate.rst
sphinx.environment.BuildEnvironment


would use the template mytemplate.rst in your templates_path to generate the pages for all entries listed. See Customizing templates below.

Added in version 1.0.

You can specify the recursive option to generate documents for modules and sub-packages recursively. It defaults to disabled. For example,

.. autosummary::

:recursive:
sphinx.environment.BuildEnvironment


Added in version 3.1.



sphinx-autogen -- generate autodoc stub pages

The sphinx-autogen script can be used to conveniently generate stub documentation pages for items included in autosummary listings.

For example, the command

$ sphinx-autogen -o generated *.rst


will read all autosummary tables in the *.rst files that have the :toctree: option set, and output corresponding stub pages in directory generated for all documented items. The generated pages by default contain text of the form:

sphinx.util.relative_uri
========================
.. autofunction:: sphinx.util.relative_uri


If the -o option is not given, the script will place the output files in the directories specified in the :toctree: options.

For more information, refer to the sphinx-autogen documentation

Generating stub pages automatically

If you do not want to create stub pages with sphinx-autogen, you can also use these config values:

A dictionary of values to pass into the template engine's context for autosummary stubs files.

Added in version 3.1.


Boolean indicating whether to scan all found documents for autosummary directives, and to generate stub pages for each. It is enabled by default.

Can also be a list of documents for which stub pages should be generated.

The new files will be placed in the directories specified in the :toctree: options of the directives.

Changed in version 2.3: Emits autodoc-skip-member event as autodoc does.

Changed in version 4.0: Enabled by default.


If true, autosummary overwrites existing files by generated stub pages. Defaults to true (enabled).

Added in version 3.0.


This value contains a list of modules to be mocked up. See autodoc_mock_imports for more details. It defaults to autodoc_mock_imports.

Added in version 2.0.


A boolean flag indicating whether to document classes and functions imported in modules. Default is False

Added in version 2.1.

Changed in version 4.4: If autosummary_ignore_module_all is False, this configuration value is ignored for members listed in __all__.


If False and a module has the __all__ attribute set, autosummary documents every member listed in __all__ and no others. Default is True

Note that if an imported member is listed in __all__, it will be documented regardless of the value of autosummary_imported_members. To match the behaviour of from module import *, set autosummary_ignore_module_all to False and autosummary_imported_members to True.

Added in version 4.4.


A dict mapping object names to filenames. This is necessary to avoid filename conflicts where multiple objects have names that are indistinguishable when case is ignored, on file systems where filenames are case-insensitive.

Added in version 3.2.


Customizing templates

Added in version 1.0.

You can customize the stub page templates, in a similar way as the HTML Jinja templates, see Templating. (TemplateBridge is not supported.)

NOTE:

If you find yourself spending much time tailoring the stub templates, this may indicate that it's a better idea to write custom narrative documentation instead.


Autosummary uses the following Jinja template files:

  • autosummary/base.rst -- fallback template
  • autosummary/module.rst -- template for modules
  • autosummary/class.rst -- template for classes
  • autosummary/function.rst -- template for functions
  • autosummary/attribute.rst -- template for class attributes
  • autosummary/method.rst -- template for class methods

The following variables are available in the templates:

Name of the documented object, excluding the module and class parts.

Name of the documented object, excluding the module parts.

Full name of the documented object, including module and class parts.

Type of the documented object, one of "module", "function", "class", "method", "attribute", "data", "object", "exception", "newvarattribute", "newtypedata", "property".

Name of the module the documented object belongs to.

Name of the class the documented object belongs to. Only available for methods and attributes.

A string containing len(full_name) * '='. Use the underline filter instead.

List containing names of all members of the module or class. Only available for modules and classes.

List containing names of all inherited members of class. Only available for classes.

Added in version 1.8.0.


List containing names of "public" functions in the module. Here, "public" means that the name does not start with an underscore. Only available for modules.

List containing names of "public" classes in the module. Only available for modules.

List containing names of "public" exceptions in the module. Only available for modules.

List containing names of "public" methods in the class. Only available for classes.

List containing names of "public" attributes in the class/module. Only available for classes and modules.

Changed in version 3.1: Attributes of modules are supported.


List containing names of "public" modules in the package. Only available for modules that are packages and the recursive option is on.

Added in version 3.1.


Additionally, the following filters are available

Escape any special characters in the text to be used in formatting RST contexts. For instance, this prevents asterisks making things bold. This replaces the builtin Jinja escape filter that does html-escaping.

Add a title underline to a piece of text.

For instance, {{ fullname | escape | underline }} should be used to produce the title of a page.

NOTE:

You can use the autosummary directive in the stub pages. Stub pages are generated also based on these directives.


sphinx.ext.coverage -- Collect doc coverage stats

This extension features one additional builder, the CoverageBuilder.

class sphinx.ext.coverage.CoverageBuilder
To use this builder, activate the coverage extension in your configuration file and give -M coverage on the command line.

Todo

Write this section.



Several configuration values can be used to specify what the builder should check:




List of Python regular expressions.

If any of these regular expressions matches any part of the full import path of a Python object, that Python object is excluded from the documentation coverage report.

Added in version 2.1.





Set to False to not write headlines.

Added in version 1.1.


Skip objects that are not documented in the source with a docstring. False by default.

Added in version 1.1.


Print objects that are missing to standard output also. False by default.

Added in version 3.1.


Print a tabular report of the coverage statistics to the coverage report. True by default.

Example output:

+-----------------------+----------+--------------+
| Module                | Coverage | Undocumented |
+=======================+==========+==============+
| package.foo_module    | 100.00%  | 0            |
+-----------------------+----------+--------------+
| package.bar_module    | 83.33%   | 1            |
+-----------------------+----------+--------------+


Added in version 7.2.


Print a tabular report of the coverage statistics to standard output. False by default.

Example output:

+-----------------------+----------+--------------+
| Module                | Coverage | Undocumented |
+=======================+==========+==============+
| package.foo_module    | 100.00%  | 0            |
+-----------------------+----------+--------------+
| package.bar_module    | 83.33%   | 1            |
+-----------------------+----------+--------------+


Added in version 7.2.


sphinx.ext.doctest -- Test snippets in the documentation

It is often helpful to include snippets of code in your documentation and demonstrate the results of executing them. But it is important to ensure that the documentation stays up-to-date with the code.

This extension allows you to test such code snippets in the documentation in a natural way. If you mark the code blocks as shown here, the doctest builder will collect them and run them as doctest tests.

Within each document, you can assign each snippet to a group. Each group consists of:

  • zero or more setup code blocks (e.g. importing the module to test)
  • one or more test blocks

When building the docs with the doctest builder, groups are collected for each document and run one after the other, first executing setup code blocks, then the test blocks in the order they appear in the file.

There are two kinds of test blocks:

  • doctest-style blocks mimic interactive sessions by interleaving Python code (including the interpreter prompt) and output.
  • code-output-style blocks consist of an ordinary piece of Python code, and optionally, a piece of output for that code.

Directives

The group argument below is interpreted as follows: if it is empty, the block is assigned to the group named default. If it is *, the block is assigned to all groups (including the default group). Otherwise, it must be a comma-separated list of group names.

.. testsetup:: [group]
A setup code block. This code is not shown in the output for other builders, but executed before the doctests of the group(s) it belongs to.

.. testcleanup:: [group]
A cleanup code block. This code is not shown in the output for other builders, but executed after the doctests of the group(s) it belongs to.

Added in version 1.1.


.. doctest:: [group]
A doctest-style code block. You can use standard doctest flags for controlling how actual output is compared with what you give as output. The default set of flags is specified by the doctest_default_flags configuration variable.

This directive supports five options:

  • hide, a flag option, hides the doctest block in other builders. By default it is shown as a highlighted doctest block.
  • options, a string option, can be used to give a comma-separated list of doctest flags that apply to each example in the tests. (You still can give explicit flags per example, with doctest comments, but they will show up in other builders too.)
  • pyversion, a string option, can be used to specify the required Python version for the example to be tested. For instance, in the following case the example will be tested only for Python versions greater than 3.10:

.. doctest::

:pyversion: > 3.10


The following operands are supported:

  • ~=: Compatible release clause
  • ==: Version matching clause
  • !=: Version exclusion clause
  • <=, >=: Inclusive ordered comparison clause
  • <, >: Exclusive ordered comparison clause
  • ===: Arbitrary equality clause.

pyversion option is followed PEP-440: Version Specifiers.

Added in version 1.6.

Changed in version 1.7: Supported PEP-440 operands and notations

trim-doctest-flags and no-trim-doctest-flags, a flag option, doctest flags (comments looking like # doctest: FLAG, ...) at the ends of lines and <BLANKLINE> markers are removed (or not removed) individually. Default is trim-doctest-flags.

Note that like with standard doctests, you have to use <BLANKLINE> to signal a blank line in the expected output. The <BLANKLINE> is removed when building presentation output (HTML, LaTeX etc.).

Also, you can give inline doctest options, like in doctest:

>>> datetime.date.now()   # doctest: +SKIP
datetime.date(2008, 1, 1)


They will be respected when the test is run, but stripped from presentation output.


.. testcode:: [group]
A code block for a code-output-style test.

This directive supports three options:

  • hide, a flag option, hides the code block in other builders. By default it is shown as a highlighted code block.
  • trim-doctest-flags and no-trim-doctest-flags, a flag option, doctest flags (comments looking like # doctest: FLAG, ...) at the ends of lines and <BLANKLINE> markers are removed (or not removed) individually. Default is trim-doctest-flags.

NOTE:

Code in a testcode block is always executed all at once, no matter how many statements it contains. Therefore, output will not be generated for bare expressions -- use print. Example:

.. testcode::

1+1 # this will give no output!
print(2+2) # this will give output .. testoutput::
4


Also, please be aware that since the doctest module does not support mixing regular output and an exception message in the same snippet, this applies to testcode/testoutput as well.




.. testoutput:: [group]
The corresponding output, or the exception message, for the last testcode block.

This directive supports four options:

  • hide, a flag option, hides the output block in other builders. By default it is shown as a literal block without highlighting.
  • options, a string option, can be used to give doctest flags (comma-separated) just like in normal doctest blocks.
  • trim-doctest-flags and no-trim-doctest-flags, a flag option, doctest flags (comments looking like # doctest: FLAG, ...) at the ends of lines and <BLANKLINE> markers are removed (or not removed) individually. Default is trim-doctest-flags.

Example:

.. testcode::

print('Output text.') .. testoutput::
:hide:
:options: -ELLIPSIS, +NORMALIZE_WHITESPACE
Output text.



The following is an example for the usage of the directives. The test via doctest and the test via testcode and testoutput are equivalent.

The parrot module
=================
.. testsetup:: *

import parrot The parrot module is a module about parrots. Doctest example: .. doctest::
>>> parrot.voom(3000)
This parrot wouldn't voom if you put 3000 volts through it! Test-Output example: .. testcode::
parrot.voom(3000) This would output: .. testoutput::
This parrot wouldn't voom if you put 3000 volts through it!


Skipping tests conditionally

skipif, a string option, can be used to skip directives conditionally. This may be useful e.g. when a different set of tests should be run depending on the environment (hardware, network/VPN, optional dependencies or different versions of dependencies). The skipif option is supported by all of the doctest directives. Below are typical use cases for skipif when used for different directives:

testsetup and testcleanup
  • conditionally skip test setup and/or cleanup
  • customize setup/cleanup code per environment

doctest
conditionally skip both a test and its output verification

testcode
  • conditionally skip a test
  • customize test code per environment

testoutput
  • conditionally skip output assertion for a skipped test
  • expect different output depending on the environment


The value of the skipif option is evaluated as a Python expression. If the result is a true value, the directive is omitted from the test run just as if it wasn't present in the file at all.

Instead of repeating an expression, the doctest_global_setup configuration option can be used to assign it to a variable which can then be used instead.

Here's an example which skips some tests if Pandas is not installed:

conf.py

extensions = ['sphinx.ext.doctest']
doctest_global_setup = '''
try:

import pandas as pd except ImportError:
pd = None '''


contents.rst

.. testsetup::

:skipif: pd is None
data = pd.Series([42]) .. doctest::
:skipif: pd is None
>>> data.iloc[0]
42 .. testcode::
:skipif: pd is None
print(data.iloc[-1]) .. testoutput::
:skipif: pd is None
42


Configuration

The doctest extension uses the following configuration values:

By default, these options are enabled:
  • ELLIPSIS, allowing you to put ellipses in the expected output that match anything in the actual output;
  • IGNORE_EXCEPTION_DETAIL, causing everything following the leftmost colon and any module information in the exception name to be ignored;
  • DONT_ACCEPT_TRUE_FOR_1, rejecting "True" in the output where "1" is given -- the default behavior of accepting this substitution is a relic of pre-Python 2.2 times.

Added in version 1.5.


Defaults to True. Controls whether successes are reported.

For a project with many doctests, it may be useful to set this to False to only highlight failures.

Added in version 7.2.


A list of directories that will be added to sys.path when the doctest builder is used. (Make sure it contains absolute paths.)

Python code that is treated like it were put in a testsetup directive for every file that is tested, and for every group. You can use this to e.g. import modules you will always need in your doctests.

Added in version 0.6.


Python code that is treated like it were put in a testcleanup directive for every file that is tested, and for every group. You can use this to e.g. remove any temporary files that the tests leave behind.

Added in version 1.1.


If this is a nonempty string (the default is 'default'), standard reST doctest blocks will be tested too. They will be assigned to the group name given.

reST doctest blocks are simply doctests put into a paragraph of their own, like so:

Some documentation text.
>>> print(1)
1
Some more documentation text.


(Note that no special :: is used to introduce a doctest block; docutils recognizes them from the leading >>>. Also, no additional indentation is used, though it doesn't hurt.)

If this value is left at its default value, the above snippet is interpreted by the doctest builder exactly like the following:

Some documentation text.
.. doctest::

>>> print(1)
1 Some more documentation text.


This feature makes it easy for you to test doctests in docstrings included with the autodoc extension without marking them up with a special directive.

Note though that you can't have blank lines in reST doctest blocks. They will be interpreted as one block ending and another one starting. Also, removal of <BLANKLINE> and # doctest: options only works in doctest blocks, though you may set trim_doctest_flags to achieve that in all code blocks with Python console content.


sphinx.ext.duration -- Measure durations of Sphinx processing

Added in version 2.4.

This extension measures durations of Sphinx processing and show its result at end of the build. It is useful for inspecting what document is slowly built.

Module author: Georg Brandl

Added in version 1.0.

This extension is meant to help with the common pattern of having many external links that point to URLs on one and the same site, e.g. links to bug trackers, version control web interfaces, or simply subpages in other websites. It does so by providing aliases to base URLs, so that you only need to give the subpage name when creating a link.

Let's assume that you want to include many links to issues at the Sphinx tracker, at https://github.com/sphinx-doc/sphinx/issues/num. Typing this URL again and again is tedious, so you can use extlinks to avoid repeating yourself.

The extension adds a config value:

This config value must be a dictionary of external sites, mapping unique short alias names to a base URL and a caption. For example, to create an alias for the above mentioned issues, you would add

extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',

'issue %s')}


Now, you can use the alias name as a new role, e.g. :issue:`123`. This then inserts a link to https://github.com/sphinx-doc/sphinx/issues/123. As you can see, the target given in the role is substituted in the base URL in the place of %s.

The link caption depends on the second item in the tuple, the caption:

  • If caption is None, the link caption is the full URL.
  • If caption is a string, then it must contain %s exactly once. In this case the link caption is caption with the partial URL substituted for %s -- in the above example, the link caption would be issue 123.

To produce a literal % in either base URL or caption, use %%:

extlinks = {'KnR': ('https://example.org/K%%26R/page/%s',

'[K&R; page %s]')}


You can also use the usual "explicit title" syntax supported by other roles that generate links, i.e. :issue:`this issue <123>`. In this case, the caption is not relevant.

Changed in version 4.0: Support to substitute by '%s' in the caption.


NOTE:

Since links are generated from the role in the reading stage, they appear as ordinary links to e.g. the linkcheck builder.


If enabled, extlinks emits a warning if a hardcoded link is replaceable by an extlink, and suggests a replacement via warning. It defaults to False.

Added in version 4.5.


sphinx.ext.githubpages -- Publish HTML docs in GitHub Pages

Added in version 1.4.

Changed in version 2.0: Support CNAME file

This extension creates .nojekyll file on generated HTML directory to publish the document on GitHub Pages.

It also creates a CNAME file for custom domains when html_baseurl set.

sphinx.ext.graphviz -- Add Graphviz graphs

Added in version 0.6.

This extension allows you to embed Graphviz graphs in your documents.

It adds these directives:

.. graphviz::
Directive to embed graphviz code. The input code for dot is given as the content. For example:

.. graphviz::

digraph foo {
"bar" -> "baz";
}


In HTML output, the code will be rendered to a PNG or SVG image (see graphviz_output_format). In LaTeX output, the code will be rendered to an embeddable PDF file.

You can also embed external dot files, by giving the file name as an argument to graphviz and no additional content:

.. graphviz:: external.dot


As for all file references in Sphinx, if the filename is absolute, it is taken as relative to the source directory.

Changed in version 1.1: Added support for external files.

options

:alt: alternate text (text)
The alternate text of the graph. By default, the graph code is used to the alternate text.

Added in version 1.0.


:align: alignment of the graph (left, center or right)
The horizontal alignment of the graph.

Added in version 1.5.


:caption: caption of the graph (text)
The caption of the graph.

Added in version 1.1.


:layout: layout type of the graph (text)
The layout of the graph (ex. dot, neato and so on). A path to the graphviz commands are also allowed. By default, graphviz_dot is used.

Added in version 1.4.

Changed in version 2.2: Renamed from graphviz_dot


:name: label (text)
The label of the graph.

Added in version 1.6.


:class: class names (a list of class names separated by spaces)
The class name of the graph.

Added in version 2.4.



.. graph::
Directive for embedding a single undirected graph. The name is given as a directive argument, the contents of the graph are the directive content. This is a convenience directive to generate graph <name> { <content> }.

For example:

.. graph:: foo

"bar" -- "baz";


NOTE:

The graph name is passed unchanged to Graphviz. If it contains non-alphanumeric characters (e.g. a dash), you will have to double-quote it.


options

Same as graphviz.

:alt: alternate text (text)
Added in version 1.0.


:align: alignment of the graph (left, center or right)
Added in version 1.5.


:caption: caption of the graph (text)
Added in version 1.1.


:layout: layout type of the graph (text)
Added in version 1.4.

Changed in version 2.2: Renamed from graphviz_dot


:name: label (text)
Added in version 1.6.


:class: class names (a list of class names separated by spaces)
The class name of the graph.

Added in version 2.4.



.. digraph::
Directive for embedding a single directed graph. The name is given as a directive argument, the contents of the graph are the directive content. This is a convenience directive to generate digraph <name> { <content> }.

For example:

.. digraph:: foo

"bar" -> "baz" -> "quux";


options

Same as graphviz.

:alt: alternate text (text)
Added in version 1.0.


:align: alignment of the graph (left, center or right)
Added in version 1.5.


:caption: caption of the graph (text)
Added in version 1.1.


:layout: layout type of the graph (text)
Added in version 1.4.

Changed in version 2.2: Renamed from graphviz_dot


:name: label (text)
Added in version 1.6.


:class: class names (a list of class names separated by spaces)
The class name of the graph.

Added in version 2.4.



There are also these config values:

The command name with which to invoke dot. The default is 'dot'; you may need to set this to a full path if dot is not in the executable search path.

Since this setting is not portable from system to system, it is normally not useful to set it in conf.py; rather, giving it on the sphinx-build command line via the -D option should be preferable, like this:

sphinx-build -M html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build



Additional command-line arguments to give to dot, as a list. The default is an empty list. This is the right place to set global graph, node or edge attributes via dot's -G, -N and -E options.

The output format for Graphviz when building HTML files. This must be either 'png' or 'svg'; the default is 'png'. If 'svg' is used, in order to make the URL links work properly, an appropriate target attribute must be set, such as "_top" and "_blank". For example, the link in the following graph should work in the svg output:

.. graphviz::

digraph example {
a [label="sphinx", href="https://www.sphinx-doc.org/", target="_top"];
b [label="other"];
a -> b;
}


Added in version 1.0: Previously, output always was PNG.


sphinx.ext.ifconfig -- Include content based on configuration

This extension is quite simple, and features only one directive:

WARNING:

This directive is designed to control only content of document. It could not control sections, labels and so on.


.. ifconfig::
Include content of the directive only if the Python expression given as an argument is True, evaluated in the namespace of the project's configuration (that is, all registered variables from conf.py are available).

For example, one could write

.. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')

This stuff is only included in the built docs for unstable versions.


To make a custom config value known to Sphinx, use add_config_value() in the setup function in conf.py, e.g.:

def setup(app):

app.add_config_value('releaselevel', '', 'env')


The second argument is the default value, the third should always be 'env' for such values (it selects if Sphinx re-reads the documents if the value changes).


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

Added in version 1.6.

This extension converts images in your document to appropriate format for builders. For example, it allows you to use SVG images with LaTeX builder. As a result, you don't mind what image format the builder supports.

By default the extension uses ImageMagick to perform conversions, and will not work if ImageMagick is not installed.

NOTE:

ImageMagick rasterizes a SVG image on conversion. As a result, the image becomes not scalable. To avoid that, please use other image converters like sphinxcontrib-svg2pdfconverter (which uses Inkscape or rsvg-convert).


Configuration

A path to a conversion command. By default, the imgconverter finds the command from search paths.

On Unix platforms, the command convert is used by default.

On Windows, the command magick is used by default.

Changed in version 3.1: Use magick command by default on windows


Additional command-line arguments to give to convert, as a list. The default is an empty list [].

On Windows, it defaults to ["convert"].

Changed in version 3.1: Use ["convert"] by default on Windows


sphinx.ext.inheritance_diagram -- Include inheritance diagrams

Added in version 0.6.

This extension allows you to include inheritance diagrams, rendered via the Graphviz extension.

It adds this directive:

.. inheritance-diagram::
This directive has one or more arguments, each giving a module or class name. Class names can be unqualified; in that case they are taken to exist in the currently described module (see py:module).

For each given class, and each class in each given module, the base classes are determined. Then, from all classes and their base classes, a graph is generated which is then rendered via the graphviz extension to a directed graph.

This directive supports an option called parts that, if given, must be an integer, advising the directive to keep that many dot-separated parts in the displayed names (from right to left). For example, parts=1 will only display class names, without the names of the modules that contain them.

Changed in version 2.0: The value of for parts can also be negative, indicating how many parts to drop from the left. For example, if all your class names start with lib., you can give :parts: -1 to remove that prefix from the displayed node names.

The directive also supports a private-bases flag option; if given, private base classes (those whose name starts with _) will be included.

You can use caption option to give a caption to the diagram.

Changed in version 1.1: Added private-bases option; previously, all bases were always included.

Changed in version 1.5: Added caption option

It also supports a top-classes option which requires one or more class names separated by comma. If specified inheritance traversal will stop at the specified class names. Given the following Python module:

"""

A
/ \
B C
/ \ / \
E D F """ class A:
pass class B(A):
pass class C(A):
pass class D(B, C):
pass class E(B):
pass class F(C):
pass


If you have specified a module in the inheritance diagram like this:

.. inheritance-diagram:: dummy.test

:top-classes: dummy.test.B, dummy.test.C


any base classes which are ancestors to top-classes and are also defined in the same module will be rendered as stand alone nodes. In this example class A will be rendered as stand alone node in the graph. This is a known issue due to how this extension works internally.

If you don't want class A (or any other ancestors) to be visible then specify only the classes you would like to generate the diagram for like this:

.. inheritance-diagram:: dummy.test.D dummy.test.E dummy.test.F

:top-classes: dummy.test.B, dummy.test.C


Changed in version 1.7: Added top-classes option to limit the scope of inheritance graphs.


Examples

The following are different inheritance diagrams for the internal InheritanceDiagram class that implements the directive.

With full names:

.. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram


Showing class names only:

.. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram

:parts: 1


Stopping the diagram at sphinx.util.docutils.SphinxDirective (the highest superclass still part of Sphinx), and dropping the common left-most part (sphinx) from all names:

.. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram

:top-classes: sphinx.util.docutils.SphinxDirective
:parts: -1


class sphinx.ext.inheritance_diagram.InheritanceDiagram
The internal class that implements the inheritance-diagram directive.

Configuration

A dictionary of graphviz graph attributes for inheritance diagrams.

For example:

inheritance_graph_attrs = dict(rankdir="LR", size='"6.0, 8.0"',

fontsize=14, ratio='compress')



A dictionary of graphviz node attributes for inheritance diagrams.

For example:

inheritance_node_attrs = dict(shape='ellipse', fontsize=14, height=0.75,

color='dodgerblue1', style='filled')



A dictionary of graphviz edge attributes for inheritance diagrams.

Allows mapping the full qualified name of the class to custom values (useful when exposing the underlying path of a class is not desirable, e.g. it's a private class and should not be instantiated by the user).

For example:

inheritance_alias = {'_pytest.Magic': 'pytest.Magic'}



Added in version 0.5.

This extension can generate links to the documentation of objects in external projects, either explicitly through the external role, or as a fallback resolution for any other cross-reference.

Usage for fallback resolution is simple: whenever Sphinx encounters a cross-reference that has no matching target in the current documentation set, it looks for targets in the external documentation sets configured in intersphinx_mapping. A reference like :py:class:`zipfile.ZipFile` can then link to the Python documentation for the ZipFile class, without you having to specify where it is located exactly.

When using the external role, you can force lookup to any external projects, and optionally to a specific external project. A link like :external:ref:`comparison manual <comparisons>` will then link to the label "comparisons" in whichever configured external project, if it exists, and a link like :external+python:ref:`comparison manual <comparisons>` will link to the label "comparisons" only in the doc set "python", if it exists.

Behind the scenes, this works as follows:

  • Each Sphinx HTML build creates a file named objects.inv that contains a mapping from object names to URIs relative to the HTML set's root.
  • Projects using the Intersphinx extension can specify the location of such mapping files in the intersphinx_mapping config value. The mapping will then be used to resolve both external references, and also otherwise missing references to objects into links to the other documentation.
  • By default, the mapping file is assumed to be at the same location as the rest of the documentation; however, the location of the mapping file can also be specified individually, e.g. if the docs should be buildable without Internet access.

Configuration

To use Intersphinx linking, add 'sphinx.ext.intersphinx' to your extensions config value, and use these config values to activate linking:

This config value contains the locations and names of other projects that should be linked to in this documentation.

Relative local paths for target locations are taken as relative to the base of the built documentation, while relative local paths for inventory locations are taken as relative to the source directory.

When fetching remote inventory files, proxy settings will be read from the $HTTP_PROXY environment variable.

Format

Added in version 1.0.

A dictionary mapping unique identifiers to a tuple (target, inventory). Each target is the base URI of a foreign Sphinx documentation set and can be a local path or an HTTP URI. The inventory indicates where the inventory file can be found: it can be None (an objects.inv file at the same location as the base URI) or another local file path or a full HTTP URI to an inventory file.

The unique identifier can be used in the external role, so that it is clear which intersphinx set the target belongs to. A link like external:python+ref:`comparison manual <comparisons>` will link to the label "comparisons" in the doc set "python", if it exists.

Example

To add links to modules and objects in the Python standard library documentation, use:

intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}


This will download the corresponding objects.inv file from the Internet and generate links to the pages under the given URI. The downloaded inventory is cached in the Sphinx environment, so it must be re-downloaded whenever you do a full rebuild.

A second example, showing the meaning of a non-None value of the second tuple item:

intersphinx_mapping = {'python': ('https://docs.python.org/3',

'python-inv.txt')}


This will read the inventory from python-inv.txt in the source directory, but still generate links to the pages under https://docs.python.org/3. It is up to you to update the inventory file as new objects are added to the Python documentation.

Multiple targets for the inventory

Added in version 1.3.

Alternative files can be specified for each inventory. One can give a tuple for the second inventory tuple item as shown in the following example. This will read the inventory iterating through the (second) tuple items until the first successful fetch. The primary use case for this to specify mirror sites for server downtime of the primary inventory:

intersphinx_mapping = {'python': ('https://docs.python.org/3',

(None, 'python-inv.txt'))}


For a set of books edited and tested locally and then published together, it could be helpful to try a local inventory file first, to check references before publication:

intersphinx_mapping = {

'otherbook':
('https://myproj.readthedocs.io/projects/otherbook/en/latest',
('../../otherbook/build/html/objects.inv', None)), }


Old format for this config value

Deprecated since version 6.2.

CAUTION:

This is the format used before Sphinx 1.0. It is deprecated and will be removed in Sphinx 8.0.


A dictionary mapping URIs to either None or an URI. The keys are the base URI of the foreign Sphinx documentation sets and can be local paths or HTTP URIs. The values indicate where the inventory file can be found: they can be None (at the same location as the base URI) or another local or HTTP URI.

Example:

intersphinx_mapping = {'https://docs.python.org/': None}



The maximum number of days to cache remote inventories. The default is 5, meaning five days. Set this to a negative value to cache inventories for unlimited time.

The number of seconds for timeout. The default is None, meaning do not timeout.

NOTE:

timeout is not a time limit on the entire response download; rather, an exception is raised if the server has not issued a response for timeout seconds.



Added in version 4.3.

Changed in version 5.0: Changed default value from an empty list to ['std:doc'].

A list of strings being either:

  • the name of a specific reference type in a domain, e.g., std:doc, py:func, or cpp:class,
  • the name of a domain, and a wildcard, e.g., std:*, py:*, or cpp:*, or
  • simply a wildcard *.

The default value is ['std:doc'].

When a non-external cross-reference is being resolved by intersphinx, skip resolution if it matches one of the specifications in this list.

For example, with intersphinx_disabled_reftypes = ['std:doc'] a cross-reference :doc:`installation` will not be attempted to be resolved by intersphinx, but :external+otherbook:doc:`installation` will be attempted to be resolved in the inventory named otherbook in intersphinx_mapping. At the same time, all cross-references generated in, e.g., Python, declarations will still be attempted to be resolved by intersphinx.

If * is in the list of domains, then no non-external references will be resolved by intersphinx.


Explicitly Reference External Objects

The Intersphinx extension provides the following role.

:external:
Added in version 4.4.

Use Intersphinx to perform lookup only in external projects, and not the current project. Intersphinx still needs to know the type of object you would like to find, so the general form of this role is to write the cross-refererence as if the object is in the current project, but then prefix it with :external. The two forms are then

  • :external:domain:reftype:`target`, e.g., :external:py:class:`zipfile.ZipFile`, or
  • :external:reftype:`target`, e.g., :external:doc:`installation`. With this shorthand, the domain is assumed to be std.

If you would like to constrain the lookup to a specific external project, then the key of the project, as specified in intersphinx_mapping, is added as well to get the two forms

  • :external+invname:domain:reftype:`target`, e.g., :external+python:py:class:`zipfile.ZipFile`, or
  • :external+invname:reftype:`target`, e.g., :external+python:doc:`installation`.


To show all Intersphinx links and their targets of an Intersphinx mapping file, run python -msphinx.ext.intersphinx url-or-path. This is helpful when searching for the root cause of a broken Intersphinx link in a documentation project. The following example prints the Intersphinx mapping of the Python 3 documentation:

$ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv


Using Intersphinx with inventory file under Basic Authorization

Intersphinx supports Basic Authorization like this:

intersphinx_mapping = {'python': ('https://user:password@docs.python.org/3',

None)}


The user and password will be stripped from the URL when generating the links.

Module author: Pauli Virtanen

Added in version 1.2.

This extension looks at your object descriptions (.. class::, .. function:: etc.) and adds external links to code hosted somewhere on the web. The intent is similar to the sphinx.ext.viewcode extension, but assumes the source code can be found somewhere on the Internet.

In your configuration, you need to specify a linkcode_resolve function that returns an URL based on the object.

Configuration

This is a function linkcode_resolve(domain, info), which should return the URL to source code corresponding to the object in given domain with given information.

The function should return None if no link is to be added.

The argument domain specifies the language domain the object is in. info is a dictionary with the following keys guaranteed to be present (dependent on the domain):

  • py: module (name of the module), fullname (name of the object)
  • c: names (list of names for the object)
  • cpp: names (list of names for the object)
  • javascript: object (name of the object), fullname (name of the item)

Example:

def linkcode_resolve(domain, info):

if domain != 'py':
return None
if not info['module']:
return None
filename = info['module'].replace('.', '/')
return "https://somesite/sourcerepo/%s.py" % filename



Math support for HTML outputs in Sphinx

Added in version 0.5.

Changed in version 1.8: Math support for non-HTML builders is integrated to sphinx-core. So mathbase extension is no longer needed.

Since mathematical notation isn't natively supported by HTML in any way, Sphinx gives a math support to HTML document with several extensions. These use the reStructuredText math directive and role.

sphinx.ext.imgmath -- Render math as images

Added in version 1.4.

This extension renders math via LaTeX and dvipng or dvisvgm into PNG or SVG images. This of course means that the computer where the docs are built must have both programs available.

There are various configuration values you can set to influence how the images are built:

The output image format. The default is 'png'. It should be either 'png' or 'svg'. The image is produced by first executing latex on the TeX mathematical mark-up then (depending on the requested format) either dvipng or dvisvgm.

dvipng and dvisvgm both have the ability to collect from LaTeX the "depth" of the rendered math: an inline image should use this "depth" in a vertical-align style to get correctly aligned with surrounding text.

This mechanism requires the LaTeX preview package (available as preview-latex-style on Ubuntu xenial). Therefore, the default for this option is False but it is strongly recommended to set it to True.

Changed in version 2.2: This option can be used with the 'svg' imgmath_image_format.


Default: True. If false, do not add the LaTeX code as an "alt" attribute for math images.

The font size (in pt) of the displayed math. The default value is 12. It must be a positive integer.

The command name with which to invoke LaTeX. The default is 'latex'; you may need to set this to a full path if latex is not in the executable search path.

Since this setting is not portable from system to system, it is normally not useful to set it in conf.py; rather, giving it on the sphinx-build command line via the -D option should be preferable, like this:

sphinx-build -M html -D imgmath_latex=C:\tex\latex.exe . _build


This value should only contain the path to the latex executable, not further arguments; use imgmath_latex_args for that purpose.

HINT:

To use OpenType Math fonts with unicode-math, via a custom imgmath_latex_preamble, you can set imgmath_latex to 'dvilualatex', but must then set imgmath_image_format to 'svg'. Note: this has only been tested with dvisvgm 3.0.3. It significantly increases image production duration compared to using standard 'latex' with traditional TeX math fonts.


HINT:

Some fancy LaTeX mark-up (an example was reported which used TikZ to add various decorations to the equation) require multiple runs of the LaTeX executable. To handle this, set this configuration setting to 'latexmk' (or a full path to it) as this Perl script reliably chooses dynamically how many latex runs are needed.


Changed in version 6.2.0: Using 'xelatex' (or a full path to it) is now supported. But you must then add '-no-pdf' to the imgmath_latex_args list of the command options. The 'svg' imgmath_image_format is required. Also, you may need the dvisvgm binary to be relatively recent (testing was done only with its 3.0.3 release).

NOTE:

Regarding the previous note, it is currently not supported to use latexmk with option -xelatex.



Additional arguments to give to latex, as a list. The default is an empty list.

Additional LaTeX code to put into the preamble of the LaTeX files used to translate the math snippets. This is left empty by default. Use it e.g. to add packages which modify the fonts used for math, such as '\\usepackage{newtxsf}' for sans-serif fonts, or '\\usepackage{fouriernc}' for serif fonts. Indeed, the default LaTeX math fonts have rather thin glyphs which (in HTML output) often do not match well with the font for text.

The command name to invoke dvipng. The default is 'dvipng'; you may need to set this to a full path if dvipng is not in the executable search path. This option is only used when imgmath_image_format is set to 'png'.

Additional arguments to give to dvipng, as a list. The default value is ['-gamma', '1.5', '-D', '110', '-bg', 'Transparent'] which makes the image a bit darker and larger then it is by default (this compensates somewhat for the thinness of default LaTeX math fonts), and produces PNGs with a transparent background. This option is used only when imgmath_image_format is 'png'.

The command name to invoke dvisvgm. The default is 'dvisvgm'; you may need to set this to a full path if dvisvgm is not in the executable search path. This option is only used when imgmath_image_format is 'svg'.

Additional arguments to give to dvisvgm, as a list. The default value is ['--no-fonts'], which means that dvisvgm will render glyphs as path elements (cf the dvisvgm FAQ). This option is used only when imgmath_image_format is 'svg'.

Default: False. If true, encode LaTeX output images within HTML files (base64 encoded) and do not save separate png/svg files to disk.

Added in version 5.2.


sphinx.ext.mathjax -- Render math via JavaScript

WARNING:

Version 4.0 changes the version of MathJax used to version 3. You may need to override mathjax_path to https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML or update your configuration options for version 3 (see mathjax3_config).


Added in version 1.1.

This extension puts math as-is into the HTML files. The JavaScript package MathJax is then loaded and transforms the LaTeX markup to readable math live in the browser.

Because MathJax (and the necessary fonts) is very large, it is not included in Sphinx but is set to automatically include it from a third-party site.

ATTENTION:

You should use the math directive and role, not the native MathJax $$, \(, etc.


The path to the JavaScript file to include in the HTML files in order to load MathJax.

The default is the https:// URL that loads the JS files from the jsdelivr Content Delivery Network. See the MathJax Getting Started page for details. If you want MathJax to be available offline or without including resources from a third-party site, you have to download it and set this value to a different path.

The path can be absolute or relative; if it is relative, it is relative to the _static directory of the built docs.

For example, if you put MathJax into the static path of the Sphinx docs, this value would be MathJax/MathJax.js. If you host more than one Sphinx documentation set on one server, it is advisable to install MathJax in a shared location.

You can also give a full https:// URL different from the CDN URL.


The options to script tag for mathjax. For example, you can set integrity option with following setting:

mathjax_options = {

'integrity': 'sha384-......', }


The default is empty ({}).

Added in version 1.8.

Changed in version 4.4.1: Allow to change the loading method (async or defer) of MathJax if "async" or "defer" key is set.


The configuration options for MathJax v3 (which is used by default). The given dictionary is assigned to the JavaScript variable window.MathJax. For more information, please read Configuring MathJax.

The default is empty (not configured).

Added in version 4.0.


The configuration options for MathJax v2 (which can be loaded via mathjax_path). The value is used as a parameter of MathJax.Hub.Config(). For more information, please read Using in-line configuration options.

For example:

mathjax2_config = {

'extensions': ['tex2jax.js'],
'jax': ['input/TeX', 'output/HTML-CSS'], }


The default is empty (not configured).

Added in version 4.0: mathjax_config has been renamed to mathjax2_config.


Former name of mathjax2_config.

For help converting your old MathJax configuration to to the new mathjax3_config, see Converting Your v2 Configuration to v3.

Added in version 1.8.

Changed in version 4.0: This has been renamed to mathjax2_config. mathjax_config is still supported for backwards compatibility.


sphinx.ext.jsmath -- Render math via JavaScript

This extension works just as the MathJax extension does, but uses the older package jsMath. It provides this config value:

The path to the JavaScript file to include in the HTML files in order to load JSMath. There is no default.

The path can be absolute or relative; if it is relative, it is relative to the _static directory of the built docs.

For example, if you put JSMath into the static path of the Sphinx docs, this value would be jsMath/easy/load.js. If you host more than one Sphinx documentation set on one server, it is advisable to install jsMath in a shared location.


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

Module author: Rob Ruana

Added in version 1.3.

Overview

Are you tired of writing docstrings that look like this:

:param path: The path of the file to wrap
:type path: str
:param field_storage: The :class:`FileStorage` instance to wrap
:type field_storage: FileStorage
:param temporary: Whether or not to delete the file when the File

instance is destructed :type temporary: bool :returns: A buffered writable file descriptor :rtype: BufferedFileStorage


reStructuredText is great, but it creates visually dense, hard to read docstrings. Compare the jumble above to the same thing rewritten according to the Google Python Style Guide:

Args:

path (str): The path of the file to wrap
field_storage (FileStorage): The :class:`FileStorage` instance to wrap
temporary (bool): Whether or not to delete the file when the File
instance is destructed Returns:
BufferedFileStorage: A buffered writable file descriptor


Much more legible, no?

Napoleon is a extension that enables Sphinx to parse both NumPy and Google style docstrings - the style recommended by Khan Academy.

Napoleon is a pre-processor that parses NumPy and Google style docstrings and converts them to reStructuredText before Sphinx attempts to parse them. This happens in an intermediate step while Sphinx is processing the documentation, so it doesn't modify any of the docstrings in your actual source code files.

Getting Started

1.
After setting up Sphinx to build your docs, enable napoleon in the Sphinx conf.py file:

# conf.py
# Add napoleon to the extensions list
extensions = ['sphinx.ext.napoleon']


2.
Use sphinx-apidoc to build your API documentation:

$ sphinx-apidoc -f -o docs/source projectdir



Docstrings

Napoleon interprets every docstring that autodoc can find, including docstrings on: modules, classes, attributes, methods, functions, and variables. Inside each docstring, specially formatted Sections are parsed and converted to reStructuredText.

All standard reStructuredText formatting still works as expected.

Docstring Sections

All of the following section headers are supported:

  • Args (alias of Parameters)
  • Arguments (alias of Parameters)
  • Attention
  • Attributes
  • Caution
  • Danger
  • Error
  • Example
  • Examples
  • Hint
  • Important
  • Keyword Args (alias of Keyword Arguments)
  • Keyword Arguments
  • Methods
  • Note
  • Notes
  • Other Parameters
  • Parameters
  • Return (alias of Returns)
  • Returns
  • Raise (alias of Raises)
  • Raises
  • References
  • See Also
  • Tip
  • Todo
  • Warning
  • Warnings (alias of Warning)
  • Warn (alias of Warns)
  • Warns
  • Yield (alias of Yields)
  • Yields

Google vs NumPy

Napoleon supports two styles of docstrings: Google and NumPy. The main difference between the two styles is that Google uses indentation to separate sections, whereas NumPy uses underlines.

Google style:

def func(arg1, arg2):

"""Summary line.
Extended description of function.
Args:
arg1 (int): Description of arg1
arg2 (str): Description of arg2
Returns:
bool: Description of return value
"""
return True


NumPy style:

def func(arg1, arg2):

"""Summary line.
Extended description of function.
Parameters
----------
arg1 : int
Description of arg1
arg2 : str
Description of arg2
Returns
-------
bool
Description of return value
"""
return True


NumPy style tends to require more vertical space, whereas Google style tends to use more horizontal space. Google style tends to be easier to read for short and simple docstrings, whereas NumPy style tends be easier to read for long and in-depth docstrings.

The choice between styles is largely aesthetic, but the two styles should not be mixed. Choose one style for your project and be consistent with it.

SEE ALSO:

For complete examples:
  • Example Google Style Python Docstrings
  • Example NumPy Style Python Docstrings



Type Annotations

PEP 484 introduced a standard way to express types in Python code. This is an alternative to expressing types directly in docstrings. One benefit of expressing types according to PEP 484 is that type checkers and IDEs can take advantage of them for static code analysis. PEP 484 was then extended by PEP 526 which introduced a similar way to annotate variables (and attributes).

Google style with Python 3 type annotations:

def func(arg1: int, arg2: str) -> bool:

"""Summary line.
Extended description of function.
Args:
arg1: Description of arg1
arg2: Description of arg2
Returns:
Description of return value
"""
return True class Class:
"""Summary line.
Extended description of class
Attributes:
attr1: Description of attr1
attr2: Description of attr2
"""
attr1: int
attr2: str


Google style with types in docstrings:

def func(arg1, arg2):

"""Summary line.
Extended description of function.
Args:
arg1 (int): Description of arg1
arg2 (str): Description of arg2
Returns:
bool: Description of return value
"""
return True class Class:
"""Summary line.
Extended description of class
Attributes:
attr1 (int): Description of attr1
attr2 (str): Description of attr2
"""


NOTE:

Python 2/3 compatible annotations aren't currently supported by Sphinx and won't show up in the docs.


Configuration

Listed below are all the settings used by napoleon and their default values. These settings can be changed in the Sphinx conf.py file. Make sure that "sphinx.ext.napoleon" is enabled in conf.py:

# conf.py
# Add any Sphinx extension module names here, as strings
extensions = ['sphinx.ext.napoleon']
# Napoleon settings
napoleon_google_docstring = True
napoleon_numpy_docstring = True
napoleon_include_init_with_doc = False
napoleon_include_private_with_doc = False
napoleon_include_special_with_doc = True
napoleon_use_admonition_for_examples = False
napoleon_use_admonition_for_notes = False
napoleon_use_admonition_for_references = False
napoleon_use_ivar = False
napoleon_use_param = True
napoleon_use_rtype = True
napoleon_preprocess_types = False
napoleon_type_aliases = None
napoleon_attr_annotations = True


True to parse Google style docstrings. False to disable support for Google style docstrings. Defaults to True.

True to parse NumPy style docstrings. False to disable support for NumPy style docstrings. Defaults to True.

True to list __init___ docstrings separately from the class docstring. False to fall back to Sphinx's default behavior, which considers the __init___ docstring as part of the class documentation. Defaults to False.

If True:

def __init__(self):

"""
This will be included in the docs because it has a docstring
""" def __init__(self):
# This will NOT be included in the docs



True to include private members (like _membername) with docstrings in the documentation. False to fall back to Sphinx's default behavior. Defaults to False.

If True:

def _included(self):

"""
This will be included in the docs because it has a docstring
"""
pass def _skipped(self):
# This will NOT be included in the docs
pass



True to include special members (like __membername__) with docstrings in the documentation. False to fall back to Sphinx's default behavior. Defaults to True.

If True:

def __str__(self):

"""
This will be included in the docs because it has a docstring
"""
return unicode(self).encode('utf-8') def __unicode__(self):
# This will NOT be included in the docs
return unicode(self.__class__.__name__)



True to use the .. admonition:: directive for the Example and Examples sections. False to use the .. rubric:: directive instead. One may look better than the other depending on what HTML theme is used. Defaults to False.

This NumPy style snippet will be converted as follows:

Example
-------
This is just a quick example


If True:

.. admonition:: Example

This is just a quick example


If False:

.. rubric:: Example
This is just a quick example



True to use the .. admonition:: directive for Notes sections. False to use the .. rubric:: directive instead. Defaults to False.

NOTE:

The singular Note section will always be converted to a .. note:: directive.


SEE ALSO:

napoleon_use_admonition_for_examples



True to use the .. admonition:: directive for References sections. False to use the .. rubric:: directive instead. Defaults to False.

SEE ALSO:

napoleon_use_admonition_for_examples



True to use the :ivar: role for instance variables. False to use the .. attribute:: directive instead. Defaults to False.

This NumPy style snippet will be converted as follows:

Attributes
----------
attr1 : int

Description of `attr1`


If True:

:ivar attr1: Description of `attr1`
:vartype attr1: int


If False:

.. attribute:: attr1

Description of `attr1`
:type: int



True to use a :param: role for each function parameter. False to use a single :parameters: role for all the parameters. Defaults to True.

This NumPy style snippet will be converted as follows:

Parameters
----------
arg1 : str

Description of `arg1` arg2 : int, optional
Description of `arg2`, defaults to 0


If True:

:param arg1: Description of `arg1`
:type arg1: str
:param arg2: Description of `arg2`, defaults to 0
:type arg2: :class:`int`, *optional*


If False:

:parameters: * **arg1** (*str*) --

Description of `arg1`
* **arg2** (*int, optional*) --
Description of `arg2`, defaults to 0



True to use a :keyword: role for each function keyword argument. False to use a single :keyword arguments: role for all the keywords. Defaults to True.

This behaves similarly to napoleon_use_param. Note unlike docutils, :keyword: and :param: will not be treated the same way - there will be a separate "Keyword Arguments" section, rendered in the same fashion as "Parameters" section (type links created if possible)

SEE ALSO:

napoleon_use_param



True to use the :rtype: role for the return type. False to output the return type inline with the description. Defaults to True.

This NumPy style snippet will be converted as follows:

Returns
-------
bool

True if successful, False otherwise


If True:

:returns: True if successful, False otherwise
:rtype: bool


If False:

:returns: *bool* -- True if successful, False otherwise



True to convert the type definitions in the docstrings as references. Defaults to False.

Added in version 3.2.1.

Changed in version 3.5: Do preprocess the Google style docstrings also.


A mapping to translate type names to other names or references. Works only when napoleon_use_param = True. Defaults to None.

With:

napoleon_type_aliases = {

"CustomType": "mypackage.CustomType",
"dict-like": ":term:`dict-like <mapping>`", }


This NumPy style snippet:

Parameters
----------
arg1 : CustomType

Description of `arg1` arg2 : dict-like
Description of `arg2`


becomes:

:param arg1: Description of `arg1`
:type arg1: mypackage.CustomType
:param arg2: Description of `arg2`
:type arg2: :term:`dict-like <mapping>`


Added in version 3.2.


True to allow using PEP 526 attributes annotations in classes. If an attribute is documented in the docstring without a type and has an annotation in the class body, that type is used.

Added in version 3.4.


Add a list of custom sections to include, expanding the list of parsed sections. Defaults to None.

The entries can either be strings or tuples, depending on the intention:

  • To create a custom "generic" section, just pass a string.
  • To create an alias for an existing section, pass a tuple containing the alias name and the original, in that order.
  • To create a custom section that displays like the parameters or returns section, pass a tuple containing the custom section name and a string value, "params_style" or "returns_style".

If an entry is just a string, it is interpreted as a header for a generic section. If the entry is a tuple/list/indexed container, the first entry is the name of the section, the second is the section key to emulate. If the second entry value is "params_style" or "returns_style", the custom section will be displayed like the parameters section or returns section.

Added in version 1.8.

Changed in version 3.5: Support params_style and returns_style


sphinx.ext.todo -- Support for todo items

Module author: Daniel Bültmann

Added in version 0.5.

There are two additional directives when using this extension:

.. todo::
Use this directive like, for example, note.

It will only show up in the output if todo_include_todos is True.

Added in version 1.3.2: This directive supports an class option that determines the class attribute for HTML output. If not given, the class defaults to admonition-todo.


.. todolist::
This directive is replaced by a list of all todo directives in the whole documentation, if todo_include_todos is True.

These can be configured as seen below.

Configuration

If this is True, todo and todolist produce output, else they produce nothing. The default is False.

If this is True, todo emits a warning for each TODO entries. The default is False.

Added in version 1.5.


If this is True, todolist produce output without file path and line, The default is False.

Added in version 1.4.


autodoc provides the following an additional event:

Added in version 1.5.

Emitted when a todo is defined. node is the defined sphinx.ext.todo.todo_node node.


Module author: Georg Brandl

Added in version 1.0.

This extension looks at your Python object descriptions (.. class::, .. function:: etc.) and tries to find the source files where the objects are contained. When found, a separate HTML page will be output for each module with a highlighted version of the source code, and a link will be added to all object descriptions that leads to the source code of the described object. A link back from the source to the description will also be inserted.

WARNING:

Basically, viewcode extension will import the modules being linked to. If any modules have side effects on import, these will be executed when sphinx-build is run.

If you document scripts (as opposed to library modules), make sure their main routine is protected by a if __name__ == '__main__' condition.

In addition, if you don't want to import the modules by viewcode, you can tell the location of the location of source code to viewcode using the viewcode-find-source event.

If viewcode_follow_imported_members is enabled, you will also need to resolve imported attributes using the viewcode-follow-imported event.



This extension works only on HTML related builders like html, applehelp, devhelp, htmlhelp, qthelp and so on except singlehtml. By default epub builder doesn't support this extension (see viewcode_enable_epub).

Configuration

If this is True, viewcode extension will emit viewcode-follow-imported event to resolve the name of the module by other extensions. The default is True.

Added in version 1.3.

Changed in version 1.8: Renamed from viewcode_import to viewcode_follow_imported_members.


If this is True, viewcode extension is also enabled even if you use epub builders. This extension generates pages outside toctree, but this is not preferred as epub format.

Until 1.4.x, this extension is always enabled. If you want to generate epub as same as 1.4.x, you should set True, but epub format checker's score becomes worse.

The default is False.

Added in version 1.5.

WARNING:

Not all epub readers support pages generated by viewcode extension. These readers ignore links to pages are not under toctree.

Some reader's rendering result are corrupted and epubcheck's score becomes worse even if the reader supports.




Default: False.

If set to True, inline line numbers will be added to the highlighted code.

Added in version 7.2.


Added in version 1.8.

Find the source code for a module. An event handler for this event should return a tuple of the source code itself and a dictionary of tags. The dictionary maps the name of a class, function, attribute, etc to a tuple of its type, the start line number, and the end line number. The type should be one of "class", "def", or "other".

  • app -- The Sphinx application object.
  • modname -- The name of the module to find source code for.



Added in version 1.8.

Find the name of the original module for an attribute.

  • app -- The Sphinx application object.
  • modname -- The name of the module that the attribute belongs to.
  • attribute -- The name of the member to follow.



Third-party extensions

You can find several extensions contributed by users in the sphinx-contrib organization. If you wish to include your extension in this organization, simply follow the instructions provided in the github-administration project. This is optional and there are several extensions hosted elsewhere. The awesome-sphinxdoc and sphinx-extensions projects are both curated lists of Sphinx packages, and many packages use the Framework :: Sphinx :: Extension and Framework :: Sphinx :: Theme trove classifiers for Sphinx extensions and themes, respectively.

Where to put your own extensions?

Extensions local to a project should be put within the project's directory structure. Set Python's module search path, sys.path, accordingly so that Sphinx can find them. For example, if your extension foo.py lies in the exts subdirectory of the project root, put into conf.py:

import sys, os
sys.path.append(os.path.abspath('exts'))
extensions = ['foo']


You can also install extensions anywhere else on sys.path, e.g. in the site-packages directory.

HTML Theming

Sphinx provides a number of builders for HTML and HTML-based formats.

Builders

Todo

Populate when the 'builders' document is split up.



Themes

Added in version 0.6.

NOTE:

This section provides information about using pre-existing HTML themes. If you wish to create your own theme, refer to HTML theme development.


Sphinx supports changing the appearance of its HTML output via themes. A theme is a collection of HTML templates, stylesheet(s) and other static files. Additionally, it has a configuration file which specifies from which theme to inherit, which highlighting style to use, and what options exist for customizing the theme's look and feel.

Themes are meant to be project-unaware, so they can be used for different projects without change.

Using a theme

Using a theme provided with Sphinx is easy. Since these do not need to be installed, you only need to set the html_theme config value. For example, to enable the classic theme, add the following to conf.py:

html_theme = "classic"


You can also set theme-specific options using the html_theme_options config value. These options are generally used to change the look and feel of the theme. For example, to place the sidebar on the right side and a black background for the relation bar (the bar with the navigation links at the page's top and bottom), add the following conf.py:

html_theme_options = {

"rightsidebar": "true",
"relbarbgcolor": "black" }


If the theme does not come with Sphinx, it can be in two static forms or as a Python package. For the static forms, either a directory (containing theme.toml and other needed files), or a zip file with the same contents is supported. The directory or zipfile must be put where Sphinx can find it; for this there is the config value html_theme_path. This can be a list of directories, relative to the directory containing conf.py, that can contain theme directories or zip files. For example, if you have a theme in the file blue.zip, you can put it right in the directory containing conf.py and use this configuration:

html_theme = "blue"
html_theme_path = ["."]


The third form is a Python package. If a theme you want to use is distributed as a Python package, you can use it after installing

# installing theme package
$ pip install sphinxjp.themes.dotted


Once installed, this can be used in the same manner as a directory or zipfile-based theme:

html_theme = "dotted"


For more information on the design of themes, including information about writing your own themes, refer to HTML theme development.

Builtin themes

Theme overview
[image: alabaster] [image] alabaster [image: classic] [image] classic
[image: sphinxdoc] [image] sphinxdoc [image: scrolls] [image] scrolls
[image: agogo] [image] agogo [image: traditional] [image] traditional
[image: nature] [image] nature [image: haiku] [image] haiku
[image: pyramid] [image] pyramid [image: bizstyle] [image] bizstyle

Sphinx comes with a selection of themes to choose from.

Note that from these themes only the Alabaster and Scrolls themes are mobile-optimated, the other themes resort to horizontal scrolling if the screen is too narrow.

These themes are:

This is a basically unstyled layout used as the base for the other themes, and usable as the base for custom themes as well. The HTML contains all important elements like sidebar and relation bar. There are these options (which are inherited by the other themes):
  • nosidebar (true or false): Don't include the sidebar. Defaults to False.
  • sidebarwidth (int or str): Width of the sidebar in pixels. This can be an int, which is interpreted as pixels or a valid CSS dimension string such as '70em' or '50%'. Defaults to 230 pixels.
  • body_min_width (int or str): Minimal width of the document body. This can be an int, which is interpreted as pixels or a valid CSS dimension string such as '70em' or '50%'. Use 0 if you don't want a width limit. Defaults may depend on the theme (often 450px).
  • body_max_width (int or str): Maximal width of the document body. This can be an int, which is interpreted as pixels or a valid CSS dimension string such as '70em' or '50%'. Use 'none' if you don't want a width limit. Defaults may depend on the theme (often 800px).
  • navigation_with_keys (true or false): Allow navigating with the following keyboard shortcuts:
  • Left arrow: previous page
  • Right arrow: next page

Defaults to False.

  • enable_search_shortcuts (true or false): Allow jumping to the search box with / and allow removal of search highlighting with Esc.

    Defaults to True.

  • globaltoc_collapse (true or false): Only expand subsections of the current document in globaltoc.html (see html_sidebars). Defaults to True.

    Added in version 3.1.

  • globaltoc_includehidden (true or false): Show even those subsections in globaltoc.html (see html_sidebars) which have been included with the :hidden: flag of the toctree directive. Defaults to False.

    Added in version 3.1.

  • globaltoc_maxdepth (int): The maximum depth of the toctree in globaltoc.html (see html_sidebars). Set it to -1 to allow unlimited depth. Defaults to the max depth selected in the toctree directive.

    Added in version 3.2.


Alabaster theme is a modified "Kr" Sphinx theme from @kennethreitz (especially as used in his Requests project), which was itself originally based on @mitsuhiko's theme used for Flask & related projects. Refer to its installation page for information on how to configure html_sidebars for its use.
This is the classic theme, which looks like the Python 2 documentation. It can be customized via these options:
  • rightsidebar (true or false): Put the sidebar on the right side. Defaults to False.
  • stickysidebar (true or false): Make the sidebar "fixed" so that it doesn't scroll out of view for long body content. This may not work well with all browsers. Defaults to False.
  • collapsiblesidebar (true or false): Add an experimental JavaScript snippet that makes the sidebar collapsible via a button on its side. Defaults to False.
  • externalrefs (true or false): Display external links differently from internal links. Defaults to False.

There are also various color and font options that can change the color scheme without having to write a custom stylesheet:

  • footerbgcolor (CSS color): Background color for the footer line.
  • footertextcolor (CSS color): Text color for the footer line.
  • sidebarbgcolor (CSS color): Background color for the sidebar.
  • sidebarbtncolor (CSS color): Background color for the sidebar collapse button (used when collapsiblesidebar is True).
  • sidebartextcolor (CSS color): Text color for the sidebar.
  • sidebarlinkcolor (CSS color): Link color for the sidebar.
  • relbarbgcolor (CSS color): Background color for the relation bar.
  • relbartextcolor (CSS color): Text color for the relation bar.
  • relbarlinkcolor (CSS color): Link color for the relation bar.
  • bgcolor (CSS color): Body background color.
  • textcolor (CSS color): Body text color.
  • linkcolor (CSS color): Body link color.
  • visitedlinkcolor (CSS color): Body color for visited links.
  • headbgcolor (CSS color): Background color for headings.
  • headtextcolor (CSS color): Text color for headings.
  • headlinkcolor (CSS color): Link color for headings.
  • codebgcolor (CSS color): Background color for code blocks.
  • codetextcolor (CSS color): Default text color for code blocks, if not set differently by the highlighting style.
  • bodyfont (CSS font-family): Font for normal text.
  • headfont (CSS font-family): Font for headings.

The theme originally used by this documentation. It features a sidebar on the right side. There are currently no options beyond nosidebar and sidebarwidth.

NOTE:

The Sphinx documentation now uses an adjusted version of the sphinxdoc theme.


A more lightweight theme, based on the Jinja documentation. The following color options are available:
  • headerbordercolor
  • subheadlinecolor
  • linkcolor
  • visitedlinkcolor
  • admonitioncolor

A theme created by Andi Albrecht. The following options are supported:
  • bodyfont (CSS font family): Font for normal text.
  • headerfont (CSS font family): Font for headings.
  • pagewidth (CSS length): Width of the page content, default 70em.
  • documentwidth (CSS length): Width of the document (without sidebar), default 50em.
  • sidebarwidth (CSS length): Width of the sidebar, default 20em.
  • rightsidebar (true or false): Put the sidebar on the right side. Defaults to True.
  • bgcolor (CSS color): Background color.
  • headerbg (CSS value for "background"): background for the header area, default a grayish gradient.
  • footerbg (CSS value for "background"): background for the footer area, default a light gray gradient.
  • linkcolor (CSS color): Body link color.
  • headercolor1, headercolor2 (CSS color): colors for <h1> and <h2> headings.
  • headerlinkcolor (CSS color): Color for the backreference link in headings.
  • textalign (CSS text-align value): Text alignment for the body, default is justify.

A greenish theme. There are currently no options beyond nosidebar and sidebarwidth.
A theme from the Pyramid web framework project, designed by Blaise Laflamme. There are currently no options beyond nosidebar and sidebarwidth.
A theme without sidebar inspired by the Haiku OS user guide. The following options are supported:
  • full_logo (true or false, default False): If this is true, the header will only show the html_logo. Use this for large logos. If this is false, the logo (if present) will be shown floating right, and the documentation title will be put in the header.
  • textcolor, headingcolor, linkcolor, visitedlinkcolor, hoverlinkcolor (CSS colors): Colors for various body elements.

A theme resembling the old Python documentation. There are currently no options beyond nosidebar and sidebarwidth.
A theme for the epub builder. This theme tries to save visual space which is a sparse resource on ebook readers. The following options are supported:
  • relbar1 (true or false, default True): If this is true, the relbar1 block is inserted in the epub output, otherwise it is omitted.
  • footer (true or false, default True): If this is true, the footer block is inserted in the epub output, otherwise it is omitted.

A simple bluish theme. The following options are supported beyond nosidebar and sidebarwidth:
rightsidebar (true or false): Put the sidebar on the right side. Defaults to False.


Added in version 1.3: 'alabaster', 'sphinx_rtd_theme' and 'bizstyle' theme.

Changed in version 1.3: The 'default' theme has been renamed to 'classic'. 'default' is still available, however it will emit a notice that it is an alias for the new 'alabaster' theme.

Third Party Themes

There are many third-party themes created for Sphinx. Some of these are for general use, while others are specific to an individual project.

sphinx-themes.org is a gallery that showcases various themes for Sphinx, with demo documentation rendered under each theme. Themes can also be found on PyPI (using the classifier Framework :: Sphinx :: Theme), GitHub and GitLab.

Internationalization

Added in version 1.1.

Complementary to translations provided for Sphinx-generated messages such as navigation bars, Sphinx provides mechanisms facilitating the translation of documents. See the Options for internationalization for details on configuration.

[image] Workflow visualization of translations in Sphinx. (The figure is created by plantuml.).UNINDENT

  • Sphinx internationalization details
  • Translating with sphinx-intl
  • Quick guide
  • Translating
  • Update your po files by new pot files

  • Using Transifex service for team translation
  • Using Weblate service for team translation
  • Contributing to Sphinx reference translation
  • Translation progress and statistics

Sphinx internationalization details

gettext [1] is an established standard for internationalization and localization. It naively maps messages in a program to a translated string. Sphinx uses these facilities to translate whole documents.

Initially project maintainers have to collect all translatable strings (also referred to as messages) to make them known to translators. Sphinx extracts these through invocation of sphinx-build -M gettext.

Every single element in the doctree will end up in a single message which results in lists being equally split into different chunks while large paragraphs will remain as coarsely-grained as they were in the original document. This grants seamless document updates while still providing a little bit of context for translators in free-text passages. It is the maintainer's task to split up paragraphs which are too large as there is no sane automated way to do that.

After Sphinx successfully ran the MessageCatalogBuilder you will find a collection of .pot files in your output directory. These are catalog templates and contain messages in your original language only.

They can be delivered to translators which will transform them to .po files --- so called message catalogs --- containing a mapping from the original messages to foreign-language strings.

gettext compiles them into a binary format known as binary catalogs through msgfmt for efficiency reasons. If you make these files discoverable with locale_dirs for your language, Sphinx will pick them up automatically.

An example: you have a document usage.rst in your Sphinx project. The gettext builder will put its messages into usage.pot. Imagine you have Spanish translations [2] stored in usage.po --- for your builds to be translated you need to follow these instructions:

Compile your message catalog to a locale directory, say locale, so it ends up in ./locale/es/LC_MESSAGES/usage.mo in your source directory (where es is the language code for Spanish.)

msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"


  • Set locale_dirs to ["locale/"].
  • Set language to es (also possible via -D).
  • Run your desired build.

In order to protect against mistakes, a warning is emitted if cross-references in the translated paragraph do not match those from the original. This can be turned off globally using the suppress_warnings configuration variable. Alternatively, to turn it off for one message only, end the message with #noqa like this:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
risus tortor, luctus id ultrices at. #noqa


(Write \#noqa in case you want to have "#noqa" literally in the text. This does not apply to code blocks, where #noqa is ignored because code blocks do not contain references anyway.)

Added in version 4.5: The #noqa mechanism.

Translating with sphinx-intl

Quick guide

sphinx-intl is a useful tool to work with Sphinx translation flow. This section describe an easy way to translate with sphinx-intl.

1.
Install sphinx-intl.

$ pip install sphinx-intl


2.
Add configurations to conf.py.

locale_dirs = ['locale/']   # path is example but recommended.
gettext_compact = False     # optional.


This case-study assumes that BUILDDIR is set to _build, locale_dirs is set to locale/ and gettext_compact is set to False (the Sphinx document is already configured as such).

3.
Extract translatable messages into pot files.

$ make gettext


The generated pot files will be placed in the _build/gettext directory.

4.
Generate po files.

We'll use the pot files generated in the above step.

$ sphinx-intl update -p _build/gettext -l de -l ja


Once completed, the generated po files will be placed in the below directories:

  • ./locale/de/LC_MESSAGES/
  • ./locale/ja/LC_MESSAGES/

5.
Translate po files.

As noted above, these are located in the ./locale/<lang>/LC_MESSAGES directory. An example of one such file, from Sphinx, builders.po, is given below.

# a5600c3d2e3d48fc8c261ea0284db79b
#: ../../builders.rst:4
msgid "Available builders"
msgstr "<FILL HERE BY TARGET LANGUAGE>"


Another case, msgid is multi-line text and contains reStructuredText syntax:

# 302558364e1d41c69b3277277e34b184
#: ../../builders.rst:9
msgid ""
"These are the built-in Sphinx builders. More builders can be added by "
":ref:`extensions <extensions>`."
msgstr ""
"FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
"BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."


Please be careful not to break reST notation. Most po-editors will help you with that.

6.
Build translated document.

You need a language parameter in conf.py or you may also specify the parameter on the command line.

For BSD/GNU make, run:

$ make -e SPHINXOPTS="-D language='de'" html


For Windows cmd.exe, run:

> set SPHINXOPTS=-D language=de
> .\make.bat html


For PowerShell, run:

> Set-Item env:SPHINXOPTS "-D language=de"
> .\make.bat html



Congratulations! You got the translated documentation in the _build/html directory.

Added in version 1.3: sphinx-build that is invoked by make command will build po files into mo files.

If you are using 1.2.x or earlier, please invoke sphinx-intl build command before make command.

Translating

Update your po files by new pot files

If a document is updated, it is necessary to generate updated pot files and to apply differences to translated po files. In order to apply the updates from a pot file to the po file, use the sphinx-intl update command.

$ sphinx-intl update -p _build/gettext


Using Transifex service for team translation

Transifex is one of several services that allow collaborative translation via a web interface. It has a nifty Python-based command line client that makes it easy to fetch and push translations.

1.
Install transifex-client.

You need tx command to upload resources (pot files).

$ pip install transifex-client


SEE ALSO:

Transifex Client documentation


2.
Create your Transifex account and create new project for your document.

Currently, Transifex does not allow for a translation project to have more than one version of the document, so you'd better include a version number in your project name.

For example:


3.
Create config files for tx command.

This process will create .tx/config in the current directory, as well as a ~/.transifexrc file that includes auth information.

$ tx init
Creating .tx folder...
Transifex instance [https://www.transifex.com]:
...
Please enter your transifex username: <transifex-username>
Password: <transifex-password>
...
Done.


4.
Upload pot files to Transifex service.

Register pot files to .tx/config file:

$ cd /your/document/root
$ sphinx-intl update-txconfig-resources --pot-dir _build/locale \

--transifex-project-name sphinx-document-test_1_0


and upload pot files:

$ tx push -s
Pushing translations for resource sphinx-document-test_1_0.builders:
Pushing source file (locale/pot/builders.pot)
Resource does not exist.  Creating...
...
Done.


5.
Forward the translation on Transifex.
6.
Pull translated po files and make translated HTML.

Get translated catalogs and build mo files. For example, to build mo files for German (de):

$ cd /your/document/root
$ tx pull -l de
Pulling translations for resource sphinx-document-test_1_0.builders (...)

-> de: locale/de/LC_MESSAGES/builders.po ... Done.


Invoke make html (for BSD/GNU make):

$ make -e SPHINXOPTS="-D language='de'" html



That's all!

TIP:

Translating locally and on Transifex

If you want to push all language's po files, you can be done by using tx push -t command. Watch out! This operation overwrites translations in Transifex.

In other words, if you have updated each in the service and local po files, it would take much time and effort to integrate them.



Using Weblate service for team translation

Read more in Weblate's documentation.

Contributing to Sphinx reference translation

The recommended way for new contributors to translate Sphinx reference is to join the translation team on Transifex.

There is a sphinx translation page for Sphinx (master) documentation.

1.
Login to Transifex service.
2.
Go to sphinx translation page.
3.
Click Request language and fill form.
4.
Wait acceptance by Transifex sphinx translation maintainers.
5.
(After acceptance) Translate on Transifex.

Detail is here: https://docs.transifex.com/getting-started-1/translators

Translation progress and statistics

Added in version 7.1.0.

During the rendering process, Sphinx marks each translatable node with a translated attribute, indicating if a translation was found for the text in that node.

The translation_progress_classes configuration value can be used to add a class to each element, depending on the value of the translated attribute.

The |translation progress| substitution can be used to display the percentage of nodes that have been translated on a per-document basis.

FOOTNOTES

[1]
See the GNU gettext utilities for details on that software suite.
[2]
Because nobody expects the Spanish Inquisition!

Sphinx Web Support

Added in version 1.1.

Sphinx provides a Python API to easily integrate Sphinx documentation into your web application. To learn more read the Web Support Quick Start.

Web Support Quick Start

Building Documentation Data

To make use of the web support package in your application you'll need to build the data it uses. This data includes pickle files representing documents, search indices, and node data that is used to track where comments and other things are in a document. To do this you will need to create an instance of the WebSupport class and call its build() method:

from sphinxcontrib.websupport import WebSupport
support = WebSupport(srcdir='/path/to/rst/sources/',

builddir='/path/to/build/outdir',
search='xapian') support.build()


This will read reStructuredText sources from srcdir and place the necessary data in builddir. The builddir will contain two sub-directories: one named "data" that contains all the data needed to display documents, search through documents, and add comments to documents. The other directory will be called "static" and contains static files that should be served from "/static".

NOTE:

If you wish to serve static files from a path other than "/static", you can do so by providing the staticdir keyword argument when creating the WebSupport object.


Integrating Sphinx Documents Into Your Webapp

Now that the data is built, it's time to do something useful with it. Start off by creating a WebSupport object for your application:

from sphinxcontrib.websupport import WebSupport
support = WebSupport(datadir='/path/to/the/data',

search='xapian')


You'll only need one of these for each set of documentation you will be working with. You can then call its get_document() method to access individual documents:

contents = support.get_document('contents')


This will return a dictionary containing the following items:

  • body: The main body of the document as HTML
  • sidebar: The sidebar of the document as HTML
  • relbar: A div containing links to related documents
  • title: The title of the document
  • css: Links to CSS files used by Sphinx
  • script: JavaScript containing comment options

This dict can then be used as context for templates. The goal is to be easy to integrate with your existing templating system. An example using Jinja2 is:

{%- extends "layout.html" %}
{%- block title %}

{{ document.title }} {%- endblock %} {% block css %}
{{ super() }}
{{ document.css|safe }}
<link rel="stylesheet" href="/static/websupport-custom.css" type="text/css"> {% endblock %} {%- block script %}
{{ super() }}
{{ document.script|safe }} {%- endblock %} {%- block relbar %}
{{ document.relbar|safe }} {%- endblock %} {%- block body %}
{{ document.body|safe }} {%- endblock %} {%- block sidebar %}
{{ document.sidebar|safe }} {%- endblock %}


Authentication

To use certain features such as voting, it must be possible to authenticate users. The details of the authentication are left to your application. Once a user has been authenticated you can pass the user's details to certain WebSupport methods using the username and moderator keyword arguments. The web support package will store the username with comments and votes. The only caveat is that if you allow users to change their username you must update the websupport package's data:

support.update_username(old_username, new_username)


username should be a unique string which identifies a user, and moderator should be a boolean representing whether the user has moderation privileges. The default value for moderator is False.

An example Flask function that checks whether a user is logged in and then retrieves a document is:

from sphinxcontrib.websupport.errors import *
@app.route('/<path:docname>')
def doc(docname):

username = g.user.name if g.user else ''
moderator = g.user.moderator if g.user else False
try:
document = support.get_document(docname, username, moderator)
except DocumentNotFoundError:
abort(404)
return render_template('doc.html', document=document)


The first thing to notice is that the docname is just the request path. This makes accessing the correct document easy from a single view. If the user is authenticated, then the username and moderation status are passed along with the docname to get_document(). The web support package will then add this data to the COMMENT_OPTIONS that are used in the template.

NOTE:

This only works if your documentation is served from your document root. If it is served from another directory, you will need to prefix the url route with that directory, and give the docroot keyword argument when creating the web support object:

support = WebSupport(..., docroot='docs')
@app.route('/docs/<path:docname>')




Performing Searches

To use the search form built-in to the Sphinx sidebar, create a function to handle requests to the URL 'search' relative to the documentation root. The user's search query will be in the GET parameters, with the key q. Then use the get_search_results() method to retrieve search results. In Flask that would be like this:

@app.route('/search')
def search():

q = request.args.get('q')
document = support.get_search_results(q)
return render_template('doc.html', document=document)


Note that we used the same template to render our search results as we did to render our documents. That's because get_search_results() returns a context dict in the same format that get_document() does.

Comments & Proposals

Now that this is done it's time to define the functions that handle the AJAX calls from the script. You will need three functions. The first function is used to add a new comment, and will call the web support method add_comment():

@app.route('/docs/add_comment', methods=['POST'])
def add_comment():

parent_id = request.form.get('parent', '')
node_id = request.form.get('node', '')
text = request.form.get('text', '')
proposal = request.form.get('proposal', '')
username = g.user.name if g.user is not None else 'Anonymous'
comment = support.add_comment(text, node_id='node_id',
parent_id='parent_id',
username=username, proposal=proposal)
return jsonify(comment=comment)


You'll notice that both a parent_id and node_id are sent with the request. If the comment is being attached directly to a node, parent_id will be empty. If the comment is a child of another comment, then node_id will be empty. Then next function handles the retrieval of comments for a specific node, and is aptly named get_data():

@app.route('/docs/get_comments')
def get_comments():

username = g.user.name if g.user else None
moderator = g.user.moderator if g.user else False
node_id = request.args.get('node', '')
data = support.get_data(node_id, username, moderator)
return jsonify(**data)


The final function that is needed will call process_vote(), and will handle user votes on comments:

@app.route('/docs/process_vote', methods=['POST'])
def process_vote():

if g.user is None:
abort(401)
comment_id = request.form.get('comment_id')
value = request.form.get('value')
if value is None or comment_id is None:
abort(400)
support.process_vote(comment_id, g.user.id, value)
return "success"


Comment Moderation

By default, all comments added through add_comment() are automatically displayed. If you wish to have some form of moderation, you can pass the displayed keyword argument:

comment = support.add_comment(text, node_id='node_id',

parent_id='parent_id',
username=username, proposal=proposal,
displayed=False)


You can then create a new view to handle the moderation of comments. It will be called when a moderator decides a comment should be accepted and displayed:

@app.route('/docs/accept_comment', methods=['POST'])
def accept_comment():

moderator = g.user.moderator if g.user else False
comment_id = request.form.get('id')
support.accept_comment(comment_id, moderator=moderator)
return 'OK'


Rejecting comments happens via comment deletion.

To perform a custom action (such as emailing a moderator) when a new comment is added but not displayed, you can pass callable to the WebSupport class when instantiating your support object:

def moderation_callback(comment):

"""Do something...""" support = WebSupport(..., moderation_callback=moderation_callback)


The moderation callback must take one argument, which will be the same comment dict that is returned by WebSupport.add_comment().

The WebSupport Class

class sphinxcontrib.websupport.WebSupport
The main API class for the web support package. All interactions with the web support package should occur through this class.

The class takes the following keyword arguments:

The directory containing reStructuredText source files.
The directory that build data and static files should be placed in. This should be used when creating a WebSupport object that will be used to build data.
The directory that the web support data is in. This should be used when creating a WebSupport object that will be used to retrieve data.
This may contain either a string (e.g. 'xapian') referencing a built-in search adapter to use, or an instance of a subclass of BaseSearch.
This may contain either a string representing a database uri, or an instance of a subclass of StorageBackend. If this is not provided, a new sqlite database will be created.
A callable to be called when a new comment is added that is not displayed. It must accept one argument: a dictionary representing the comment that was added.
If the static files should be created in a different location and not in '/static', this should be a string with the name of that location (e.g. builddir + '/static_files').

NOTE:

If you specify staticdir, you will typically want to adjust staticroot accordingly.


If the static files are not served from '/static', this should be a string with the name of that location (e.g. '/static_files').
If the documentation is not served from the base path of a URL, this should be a string specifying that path (e.g. 'docs').


Changed in version 1.6: WebSupport class is moved to sphinxcontrib.websupport from sphinx.websupport. Please add sphinxcontrib-websupport package in your dependency and use moved class instead.

Methods

Build the documentation. Places the data into the outdir directory. Use it like this:

support = WebSupport(srcdir, builddir, search='xapian')
support.build()


This will read reStructured text files from srcdir. Then it will build the pickles and search index, placing them into builddir. It will also save node data to the database.


Load and return a document from a pickle. The document will be a dict object which can be used to render a template:

support = WebSupport(datadir=datadir)
support.get_document('index', username, moderator)


In most cases docname will be taken from the request path and passed directly to this function. In Flask, that would be something like this:

@app.route('/<path:docname>')
def index(docname):

username = g.user.name if g.user else ''
moderator = g.user.moderator if g.user else False
try:
document = support.get_document(docname, username,
moderator)
except DocumentNotFoundError:
abort(404)
render_template('doc.html', document=document)


The document dict that is returned contains the following items to be used during template rendering.

  • body: The main body of the document as HTML
  • sidebar: The sidebar of the document as HTML
  • relbar: A div containing links to related documents
  • title: The title of the document
  • css: Links to css files used by Sphinx
  • script: Javascript containing comment options

This raises DocumentNotFoundError if a document matching docname is not found.

docname -- the name of the document to load.


Get the comments and source associated with node_id. If username is given vote information will be included with the returned comments. The default CommentBackend returns a dict with two keys, source, and comments. source is raw source of the node and is used as the starting point for proposals a user can add. comments is a list of dicts that represent a comment, each having the following items:
Key Contents
text The comment text.
username The username that was stored with the comment.
id The comment's unique identifier.
rating The comment's current rating.
age The time in seconds since the comment was added.
time A dict containing time information. It contains the following keys: year, month, day, hour, minute, second, iso, and delta. iso is the time formatted in ISO 8601 format. delta is a printable form of how old the comment is (e.g. "3 hours ago").
vote If user_id was given, this will be an integer representing the vote. 1 for an upvote, -1 for a downvote, or 0 if unvoted.
node The id of the node that the comment is attached to. If the comment's parent is another comment rather than a node, this will be null.
parent The id of the comment that this comment is attached to if it is not attached to a node.
children A list of all children, in this format.
proposal_diff An HTML representation of the differences between the the current source and the user's proposed source.
  • node_id -- the id of the node to get comments for.
  • username -- the username of the user viewing the comments.
  • moderator -- whether the user is a moderator.



Add a comment to a node or another comment. Returns the comment in the same format as get_comments(). If the comment is being attached to a node, pass in the node's id (as a string) with the node keyword argument:

comment = support.add_comment(text, node_id=node_id)


If the comment is the child of another comment, provide the parent's id (as a string) with the parent keyword argument:

comment = support.add_comment(text, parent_id=parent_id)


If you would like to store a username with the comment, pass in the optional username keyword argument:

comment = support.add_comment(text, node=node_id,

username=username)


  • parent_id -- the prefixed id of the comment's parent.
  • text -- the text of the comment.
  • displayed -- for moderation purposes
  • username -- the username of the user making the comment.
  • time -- the time the comment was created, defaults to now.



Process a user's vote. The web support package relies on the API user to perform authentication. The API user will typically receive a comment_id and value from a form, and then make sure the user is authenticated. A unique username must be passed in, which will also be used to retrieve the user's past voting data. An example, once again in Flask:

@app.route('/docs/process_vote', methods=['POST'])
def process_vote():

if g.user is None:
abort(401)
comment_id = request.form.get('comment_id')
value = request.form.get('value')
if value is None or comment_id is None:
abort(400)
support.process_vote(comment_id, g.user.name, value)
return "success"


  • comment_id -- the comment being voted on
  • username -- the unique username of the user voting
  • value -- 1 for an upvote, -1 for a downvote, 0 for an unvote.



Perform a search for the query q, and create a set of search results. Then render the search results as html and return a context dict like the one created by get_document():

document = support.get_search_results(q)


q -- the search query


Search Adapters

To create a custom search adapter you will need to subclass the BaseSearch class. Then create an instance of the new class and pass that as the search keyword argument when you create the WebSupport object:

support = WebSupport(srcdir=srcdir,

builddir=builddir,
search=MySearch())


For more information about creating a custom search adapter, please see the documentation of the BaseSearch class below.

class sphinxcontrib.websupport.search.BaseSearch
Defines an interface for search adapters.

Changed in version 1.6: BaseSearch class is moved to sphinxcontrib.websupport.search from sphinx.websupport.search.

Methods

The following methods are defined in the BaseSearch class. Some methods do not need to be overridden, but some (add_document() and handle_query()) must be overridden in your subclass. For a working example, look at the built-in adapter for whoosh.

Called by the builder to initialize the search indexer. changed is a list of pagenames that will be reindexed. You may want to remove these from the search index before indexing begins.
changed -- a list of pagenames that will be re-indexed


Called by the builder when writing has been completed. Use this to perform any finalization or cleanup actions after indexing is complete.

Called by the builder to add a doctree to the index. Converts the doctree to text and passes it to add_document(). You probably won't want to override this unless you need access to the doctree. Override add_document() instead.
  • pagename -- the name of the page to be indexed
  • filename -- the name of the original source file
  • title -- the title of the page to be indexed
  • doctree -- is the docutils doctree representation of the page



Called by feed() to add a document to the search index. This method should should do everything necessary to add a single document to the search index.

pagename is name of the page being indexed. It is the combination of the source files relative path and filename, minus the extension. For example, if the source file is "ext/builders.rst", the pagename would be "ext/builders". This will need to be returned with search results when processing a query.

  • pagename -- the name of the page being indexed
  • filename -- the name of the original source file
  • title -- the page's title
  • text -- the full text of the page



Called by the web support api to get search results. This method compiles the regular expression to be used when extracting context, then calls handle_query(). You won't want to override this unless you don't want to use the included extract_context() method. Override handle_query() instead.
q -- the search query string.


Called by query() to retrieve search results for a search query q. This should return an iterable containing tuples of the following format:

(<path>, <title>, <context>)


path and title are the same values that were passed to add_document(), and context should be a short text snippet of the text surrounding the search query in the document.

The extract_context() method is provided as a simple way to create the context.

q -- the search query


Extract the context for the search query from the document's full text.
  • text -- the full text of the document to create the context for
  • length -- the length of the context snippet to return.



Storage Backends

To create a custom storage backend you will need to subclass the StorageBackend class. Then create an instance of the new class and pass that as the storage keyword argument when you create the WebSupport object:

support = WebSupport(srcdir=srcdir,

builddir=builddir,
storage=MyStorage())


For more information about creating a custom storage backend, please see the documentation of the StorageBackend class below.

class sphinxcontrib.websupport.storage.StorageBackend
Defines an interface for storage backends.

Changed in version 1.6: StorageBackend class is moved to sphinxcontrib.websupport.storage from sphinx.websupport.storage.

Methods

Called immediately before the build process begins. Use this to prepare the StorageBackend for the addition of nodes.

Add a node to the StorageBackend.
  • id -- a unique id for the comment.
  • document -- the name of the document the node belongs to.
  • source -- the source files name.



Called after a build has completed. Use this to finalize the addition of nodes if needed.

Called when a comment is being added.
  • text -- the text of the comment
  • displayed -- whether the comment should be displayed
  • username -- the name of the user adding the comment
  • time -- a date object with the time the comment was added
  • proposal -- the text of the proposal the user made
  • node_id -- the id of the node that the comment is being added to
  • parent_id -- the id of the comment's parent comment.
  • moderator -- whether the user adding the comment is a moderator



Delete a comment.

Raises UserNotAuthorizedError if moderator is False and username doesn't match the username on the comment.

  • comment_id -- The id of the comment being deleted.
  • username -- The username of the user requesting the deletion.
  • moderator -- Whether the user is a moderator.



Called to retrieve all data for a node. This should return a dict with two keys, source and comments as described by WebSupport's get_data() method.
  • node_id -- The id of the node to get data for.
  • username -- The name of the user requesting the data.
  • moderator -- Whether the requestor is a moderator.



Process a vote that is being cast. value will be either -1, 0, or 1.
  • comment_id -- The id of the comment being voted on.
  • username -- The username of the user casting the vote.
  • value -- The value of the vote being cast.



If a user is allowed to change their username this method should be called so that there is not stagnate data in the storage system.
  • old_username -- The username being changed.
  • new_username -- What the username is being changed to.



Called when a moderator accepts a comment. After the method is called the comment should be displayed to all users.
comment_id -- The id of the comment being accepted.


Writing Sphinx Extensions

This guide is aimed at giving a quick introduction for those wishing to develop their own extensions for Sphinx. Sphinx possesses significant extensibility capabilities including the ability to hook into almost every point of the build process. If you simply wish to use Sphinx with existing extensions, refer to Using Sphinx. For a more detailed discussion of the extension interface see Sphinx Extensions API.

Developing extensions overview

This page contains general information about developing Sphinx extensions.

Make an extension depend on another extension

Sometimes your extension depends on the functionality of another Sphinx extension. Most Sphinx extensions are activated in a project's conf.py file, but this is not available to you as an extension developer.

To ensure that another extension is activated as a part of your own extension, use the sphinx.application.Sphinx.setup_extension() method. This will activate another extension at run-time, ensuring that you have access to its functionality.

For example, the following code activates the recommonmark extension:

def setup(app):

app.setup_extension("recommonmark")


NOTE:

Since your extension will depend on another, make sure to include it as a part of your extension's installation requirements.


Extension tutorials

Refer to the following tutorials to get started with extension development.

Developing a "Hello world" extension

The objective of this tutorial is to create a very basic extension that adds a new directive. This directive will output a paragraph containing "hello world".

Only basic information is provided in this tutorial. For more information, refer to the other tutorials that go into more details.

WARNING:

For this extension, you will need some basic understanding of docutils and Python.


Overview

We want the extension to add the following to Sphinx:

A helloworld directive, that will simply output the text "hello world".

Prerequisites

We will not be distributing this plugin via PyPI and will instead include it as part of an existing project. This means you will need to use an existing project or create a new one using sphinx-quickstart.

We assume you are using separate source (source) and build (build) folders. Your extension file could be in any folder of your project. In our case, let's do the following:

1.
Create an _ext folder in source
2.
Create a new Python file in the _ext folder called helloworld.py

Here is an example of the folder structure you might obtain:

└── source

   ├── _ext
│   └── helloworld.py
   ├── _static
   ├── conf.py
   ├── somefolder
   ├── index.rst
   ├── somefile.rst
   └── someotherfile.rst


Writing the extension

Open helloworld.py and paste the following code in it:

from docutils import nodes
from docutils.parsers.rst import Directive
from sphinx.application import Sphinx
from sphinx.util.typing import ExtensionMetadata
class HelloWorld(Directive):

def run(self):
paragraph_node = nodes.paragraph(text='Hello World!')
return [paragraph_node] def setup(app: Sphinx) -> ExtensionMetadata:
app.add_directive('helloworld', HelloWorld)
return {
'version': '0.1',
'parallel_read_safe': True,
'parallel_write_safe': True,
}


Some essential things are happening in this example, and you will see them for all directives.

The directive class

Our new directive is declared in the HelloWorld class.

from sphinx.util.typing import ExtensionMetadata
class HelloWorld(Directive):

def run(self):


This class extends the docutils' Directive class. All extensions that create directives should extend this class.

SEE ALSO:

The docutils documentation on creating directives


This class contains a run method. This method is a requirement and it is part of every directive. It contains the main logic of the directive and it returns a list of docutils nodes to be processed by Sphinx. These nodes are docutils' way of representing the content of a document. There are many types of nodes available: text, paragraph, reference, table, etc.

SEE ALSO:

The docutils documentation on nodes


The nodes.paragraph class creates a new paragraph node. A paragraph node typically contains some text that we can set during instantiation using the text parameter.

The setup function

This function is a requirement. We use it to plug our new directive into Sphinx.

def setup(app: Sphinx) -> ExtensionMetadata:

app.add_directive('helloworld', HelloWorld)
return {
'version': '0.1',
'parallel_read_safe': True,
'parallel_write_safe': True,
}


The simplest thing you can do is to call the add_directive() method, which is what we've done here. For this particular call, the first argument is the name of the directive itself as used in a reST file. In this case, we would use helloworld. For example:

Some intro text here...
.. helloworld::
Some more text here...


We also return the extension metadata that indicates the version of our extension, along with the fact that it is safe to use the extension for both parallel reading and writing.

Using the extension

The extension has to be declared in your conf.py file to make Sphinx aware of it. There are two steps necessary here:

1.
Add the _ext directory to the Python path using sys.path.append. This should be placed at the top of the file.
2.
Update or create the extensions list and add the extension file name to the list

For example:

import os
import sys
sys.path.append(os.path.abspath("./_ext"))
extensions = ['helloworld']


TIP:

We're not distributing this extension as a Python package, we need to modify the Python path so Sphinx can find our extension. This is why we need the call to sys.path.append.


You can now use the extension in a file. For example:

Some intro text here...
.. helloworld::
Some more text here...


The sample above would generate:

Some intro text here...
Hello World!
Some more text here...


Further reading

This is the very basic principle of an extension that creates a new directive.

For a more advanced example, refer to Developing a "TODO" extension.

Developing a "TODO" extension

The objective of this tutorial is to create a more comprehensive extension than that created in Developing a "Hello world" extension. Whereas that guide just covered writing a custom directive, this guide adds multiple directives, along with custom nodes, additional config values and custom event handlers. To this end, we will cover a todo extension that adds capabilities to include todo entries in the documentation, and to collect these in a central place. This is similar the sphinxext.todo extension distributed with Sphinx.

Overview

NOTE:

To understand the design of this extension, refer to Important objects and Build Phases.


We want the extension to add the following to Sphinx:

  • A todo directive, containing some content that is marked with "TODO" and only shown in the output if a new config value is set. Todo entries should not be in the output by default.
  • A todolist directive that creates a list of all todo entries throughout the documentation.

For that, we will need to add the following elements to Sphinx:

  • New directives, called todo and todolist.
  • New document tree nodes to represent these directives, conventionally also called todo and todolist. We wouldn't need new nodes if the new directives only produced some content representable by existing nodes.
  • A new config value todo_include_todos (config value names should start with the extension name, in order to stay unique) that controls whether todo entries make it into the output.
  • New event handlers: one for the doctree-resolved event, to replace the todo and todolist nodes, one for env-merge-info to merge intermediate results from parallel builds, and one for env-purge-doc (the reason for that will be covered later).

Prerequisites

As with Developing a "Hello world" extension, we will not be distributing this plugin via PyPI so once again we need a Sphinx project to call this from. You can use an existing project or create a new one using sphinx-quickstart.

We assume you are using separate source (source) and build (build) folders. Your extension file could be in any folder of your project. In our case, let's do the following:

1.
Create an _ext folder in source
2.
Create a new Python file in the _ext folder called todo.py

Here is an example of the folder structure you might obtain:

└── source

   ├── _ext
│   └── todo.py
   ├── _static
   ├── conf.py
   ├── somefolder
   ├── index.rst
   ├── somefile.rst
   └── someotherfile.rst


Writing the extension

Open todo.py and paste the following code in it, all of which we will explain in detail shortly:

from docutils import nodes
from docutils.parsers.rst import Directive
from sphinx.application import Sphinx
from sphinx.locale import _
from sphinx.util.docutils import SphinxDirective
from sphinx.util.typing import ExtensionMetadata
class todo(nodes.Admonition, nodes.Element):

pass class todolist(nodes.General, nodes.Element):
pass def visit_todo_node(self, node):
self.visit_admonition(node) def depart_todo_node(self, node):
self.depart_admonition(node) class TodolistDirective(Directive):
def run(self):
return [todolist('')] class TodoDirective(SphinxDirective):
# this enables content in the directive
has_content = True
def run(self):
targetid = 'todo-%d' % self.env.new_serialno('todo')
targetnode = nodes.target('', '', ids=[targetid])
todo_node = todo('\n'.join(self.content))
todo_node += nodes.title(_('Todo'), _('Todo'))
self.state.nested_parse(self.content, self.content_offset, todo_node)
if not hasattr(self.env, 'todo_all_todos'):
self.env.todo_all_todos = []
self.env.todo_all_todos.append({
'docname': self.env.docname,
'lineno': self.lineno,
'todo': todo_node.deepcopy(),
'target': targetnode,
})
return [targetnode, todo_node] def purge_todos(app, env, docname):
if not hasattr(env, 'todo_all_todos'):
return
env.todo_all_todos = [todo for todo in env.todo_all_todos if todo['docname'] != docname] def merge_todos(app, env, docnames, other):
if not hasattr(env, 'todo_all_todos'):
env.todo_all_todos = []
if hasattr(other, 'todo_all_todos'):
env.todo_all_todos.extend(other.todo_all_todos) def process_todo_nodes(app, doctree, fromdocname):
if not app.config.todo_include_todos:
for node in doctree.findall(todo):
node.parent.remove(node)
# Replace all todolist nodes with a list of the collected todos.
# Augment each todo with a backlink to the original location.
env = app.builder.env
if not hasattr(env, 'todo_all_todos'):
env.todo_all_todos = []
for node in doctree.findall(todolist):
if not app.config.todo_include_todos:
node.replace_self([])
continue
content = []
for todo_info in env.todo_all_todos:
para = nodes.paragraph()
filename = env.doc2path(todo_info['docname'], base=None)
description = _(
'(The original entry is located in %s, line %d and can be found '
) % (filename, todo_info['lineno'])
para += nodes.Text(description)
# Create a reference
newnode = nodes.reference('', '')
innernode = nodes.emphasis(_('here'), _('here'))
newnode['refdocname'] = todo_info['docname']
newnode['refuri'] = app.builder.get_relative_uri(fromdocname, todo_info['docname'])
newnode['refuri'] += '#' + todo_info['target']['refid']
newnode.append(innernode)
para += newnode
para += nodes.Text('.)')
# Insert into the todolist
content.extend((
todo_info['todo'],
para,
))
node.replace_self(content) def setup(app: Sphinx) -> ExtensionMetadata:
app.add_config_value('todo_include_todos', False, 'html')
app.add_node(todolist)
app.add_node(
todo,
html=(visit_todo_node, depart_todo_node),
latex=(visit_todo_node, depart_todo_node),
text=(visit_todo_node, depart_todo_node),
)
app.add_directive('todo', TodoDirective)
app.add_directive('todolist', TodolistDirective)
app.connect('doctree-resolved', process_todo_nodes)
app.connect('env-purge-doc', purge_todos)
app.connect('env-merge-info', merge_todos)
return {
'version': '0.1',
'parallel_read_safe': True,
'parallel_write_safe': True,
}


This is far more extensive extension than the one detailed in Developing a "Hello world" extension, however, we will will look at each piece step-by-step to explain what's happening.

The node classes

Let's start with the node classes:

class todo(nodes.Admonition, nodes.Element):

pass class todolist(nodes.General, nodes.Element):
pass def visit_todo_node(self, node):
self.visit_admonition(node)


Node classes usually don't have to do anything except inherit from the standard docutils classes defined in docutils.nodes. todo inherits from Admonition because it should be handled like a note or warning, todolist is just a "general" node.

NOTE:

Many extensions will not have to create their own node classes and work fine with the nodes already provided by docutils and Sphinx.


ATTENTION:

It is important to know that while you can extend Sphinx without leaving your conf.py, if you declare an inherited node right there, you'll hit an unobvious PickleError. So if something goes wrong, please make sure that you put inherited nodes into a separate Python module.

For more details, see:




The directive classes

A directive class is a class deriving usually from docutils.parsers.rst.Directive. The directive interface is also covered in detail in the docutils documentation; the important thing is that the class should have attributes that configure the allowed markup, and a run method that returns a list of nodes.

Looking first at the TodolistDirective directive:

class TodolistDirective(Directive):

def run(self):


It's very simple, creating and returning an instance of our todolist node class. The TodolistDirective directive itself has neither content nor arguments that need to be handled. That brings us to the TodoDirective directive:

class TodoDirective(SphinxDirective):

# this enables content in the directive
has_content = True
def run(self):
targetid = 'todo-%d' % self.env.new_serialno('todo')
targetnode = nodes.target('', '', ids=[targetid])
todo_node = todo('\n'.join(self.content))
todo_node += nodes.title(_('Todo'), _('Todo'))
self.state.nested_parse(self.content, self.content_offset, todo_node)
if not hasattr(self.env, 'todo_all_todos'):
self.env.todo_all_todos = []
self.env.todo_all_todos.append({
'docname': self.env.docname,
'lineno': self.lineno,
'todo': todo_node.deepcopy(),
'target': targetnode,
})
return [targetnode, todo_node]


Several important things are covered here. First, as you can see, we're now subclassing the SphinxDirective helper class instead of the usual Directive class. This gives us access to the build environment instance using the self.env property. Without this, we'd have to use the rather convoluted self.state.document.settings.env. Then, to act as a link target (from TodolistDirective), the TodoDirective directive needs to return a target node in addition to the todo node. The target ID (in HTML, this will be the anchor name) is generated by using env.new_serialno which returns a new unique integer on each call and therefore leads to unique target names. The target node is instantiated without any text (the first two arguments).

On creating admonition node, the content body of the directive are parsed using self.state.nested_parse. The first argument gives the content body, and the second one gives content offset. The third argument gives the parent node of parsed result, in our case the todo node. Following this, the todo node is added to the environment. This is needed to be able to create a list of all todo entries throughout the documentation, in the place where the author puts a todolist directive. For this case, the environment attribute todo_all_todos is used (again, the name should be unique, so it is prefixed by the extension name). It does not exist when a new environment is created, so the directive must check and create it if necessary. Various information about the todo entry's location are stored along with a copy of the node.

In the last line, the nodes that should be put into the doctree are returned: the target node and the admonition node.

The node structure that the directive returns looks like this:

+--------------------+
| target node        |
+--------------------+
+--------------------+
| todo node          |
+--------------------+

\__+--------------------+
| admonition title |
+--------------------+
| paragraph |
+--------------------+
| ... |
+--------------------+


The event handlers

Event handlers are one of Sphinx's most powerful features, providing a way to do hook into any part of the documentation process. There are many events provided by Sphinx itself, as detailed in the API guide, and we're going to use a subset of them here.

Let's look at the event handlers used in the above example. First, the one for the env-purge-doc event:

def purge_todos(app, env, docname):

if not hasattr(env, 'todo_all_todos'):
return
env.todo_all_todos = [todo for todo in env.todo_all_todos if todo['docname'] != docname]


Since we store information from source files in the environment, which is persistent, it may become out of date when the source file changes. Therefore, before each source file is read, the environment's records of it are cleared, and the env-purge-doc event gives extensions a chance to do the same. Here we clear out all todos whose docname matches the given one from the todo_all_todos list. If there are todos left in the document, they will be added again during parsing.

The next handler, for the env-merge-info event, is used during parallel builds. As during parallel builds all threads have their own env, there's multiple todo_all_todos lists that need to be merged:


if not hasattr(env, 'todo_all_todos'):
env.todo_all_todos = []
if hasattr(other, 'todo_all_todos'):
env.todo_all_todos.extend(other.todo_all_todos)


The other handler belongs to the doctree-resolved event:


if not app.config.todo_include_todos:
for node in doctree.findall(todo):
node.parent.remove(node)
# Replace all todolist nodes with a list of the collected todos.
# Augment each todo with a backlink to the original location.
env = app.builder.env
if not hasattr(env, 'todo_all_todos'):
env.todo_all_todos = []
for node in doctree.findall(todolist):
if not app.config.todo_include_todos:
node.replace_self([])
continue
content = []
for todo_info in env.todo_all_todos:
para = nodes.paragraph()
filename = env.doc2path(todo_info['docname'], base=None)
description = _(
'(The original entry is located in %s, line %d and can be found '
) % (filename, todo_info['lineno'])
para += nodes.Text(description)
# Create a reference
newnode = nodes.reference('', '')
innernode = nodes.emphasis(_('here'), _('here'))
newnode['refdocname'] = todo_info['docname']
newnode['refuri'] = app.builder.get_relative_uri(fromdocname, todo_info['docname'])
newnode['refuri'] += '#' + todo_info['target']['refid']
newnode.append(innernode)
para += newnode
para += nodes.Text('.)')
# Insert into the todolist
content.extend((
todo_info['todo'],
para,
))
node.replace_self(content)


The doctree-resolved event is emitted at the end of phase 3 (resolving) and allows custom resolving to be done. The handler we have written for this event is a bit more involved. If the todo_include_todos config value (which we'll describe shortly) is false, all todo and todolist nodes are removed from the documents. If not, todo nodes just stay where and how they are. todolist nodes are replaced by a list of todo entries, complete with backlinks to the location where they come from. The list items are composed of the nodes from the todo entry and docutils nodes created on the fly: a paragraph for each entry, containing text that gives the location, and a link (reference node containing an italic node) with the backreference. The reference URI is built by sphinx.builders.Builder.get_relative_uri() which creates a suitable URI depending on the used builder, and appending the todo node's (the target's) ID as the anchor name.

The setup function

As noted previously, the setup function is a requirement and is used to plug directives into Sphinx. However, we also use it to hook up the other parts of our extension. Let's look at our setup function:

def setup(app: Sphinx) -> ExtensionMetadata:

app.add_config_value('todo_include_todos', False, 'html')
app.add_node(todolist)
app.add_node(
todo,
html=(visit_todo_node, depart_todo_node),
latex=(visit_todo_node, depart_todo_node),
text=(visit_todo_node, depart_todo_node),
)
app.add_directive('todo', TodoDirective)
app.add_directive('todolist', TodolistDirective)
app.connect('doctree-resolved', process_todo_nodes)
app.connect('env-purge-doc', purge_todos)
app.connect('env-merge-info', merge_todos)
return {
'version': '0.1',
'parallel_read_safe': True,
'parallel_write_safe': True,
}


The calls in this function refer to the classes and functions we added earlier. What the individual calls do is the following:

  • add_config_value() lets Sphinx know that it should recognize the new config value todo_include_todos, whose default value should be False (this also tells Sphinx that it is a boolean value).

    If the third argument was 'html', HTML documents would be full rebuild if the config value changed its value. This is needed for config values that influence reading (build phase 1 (reading)).

  • add_node() adds a new node class to the build system. It also can specify visitor functions for each supported output format. These visitor functions are needed when the new nodes stay until phase 4 (writing). Since the todolist node is always replaced in phase 3 (resolving), it doesn't need any.
  • add_directive() adds a new directive, given by name and class.
  • Finally, connect() adds an event handler to the event whose name is given by the first argument. The event handler function is called with several arguments which are documented with the event.

With this, our extension is complete.

Using the extension

As before, we need to enable the extension by declaring it in our conf.py file. There are two steps necessary here:

1.
Add the _ext directory to the Python path using sys.path.append. This should be placed at the top of the file.
2.
Update or create the extensions list and add the extension file name to the list

In addition, we may wish to set the todo_include_todos config value. As noted above, this defaults to False but we can set it explicitly.

For example:

import os
import sys
sys.path.append(os.path.abspath("./_ext"))
extensions = ['todo']
todo_include_todos = False


You can now use the extension throughout your project. For example:

index.rst

Hello, world
============
.. toctree::

somefile.rst
someotherfile.rst Hello world. Below is the list of TODOs. .. todolist::


somefile.rst

foo
===
Some intro text here...
.. todo:: Fix this


someotherfile.rst

bar
===
Some more text here...
.. todo:: Fix that


Because we have configured todo_include_todos to False, we won't actually see anything rendered for the todo and todolist directives. However, if we toggle this to true, we will see the output described previously.

Further reading

For more information, refer to the docutils documentation and Sphinx Extensions API.

Developing a "recipe" extension

The objective of this tutorial is to illustrate roles, directives and domains. Once complete, we will be able to use this extension to describe a recipe and reference that recipe from elsewhere in our documentation.

NOTE:

This tutorial is based on a guide first published on opensource.com and is provided here with the original author's permission.


Overview

We want the extension to add the following to Sphinx:

  • A recipe directive, containing some content describing the recipe steps, along with a :contains: option highlighting the main ingredients of the recipe.
  • A ref role, which provides a cross-reference to the recipe itself.
  • A recipe domain, which allows us to tie together the above role and domain, along with things like indices.

For that, we will need to add the following elements to Sphinx:

  • A new directive called recipe
  • New indexes to allow us to reference ingredient and recipes
  • A new domain called recipe, which will contain the recipe directive and ref role

Prerequisites

We need the same setup as in the previous extensions. This time, we will be putting out extension in a file called recipe.py.

Here is an example of the folder structure you might obtain:

└── source

   ├── _ext
│   └── recipe.py
   ├── conf.py
   └── index.rst


Writing the extension

Open recipe.py and paste the following code in it, all of which we will explain in detail shortly:

from collections import defaultdict
from docutils.parsers.rst import directives
from sphinx import addnodes
from sphinx.application import Sphinx
from sphinx.directives import ObjectDescription
from sphinx.domains import Domain, Index
from sphinx.roles import XRefRole
from sphinx.util.nodes import make_refnode
from sphinx.util.typing import ExtensionMetadata
class RecipeDirective(ObjectDescription):

"""A custom directive that describes a recipe."""
has_content = True
required_arguments = 1
option_spec = {
'contains': directives.unchanged_required,
}
def handle_signature(self, sig, signode):
signode += addnodes.desc_name(text=sig)
return sig
def add_target_and_index(self, name_cls, sig, signode):
signode['ids'].append('recipe' + '-' + sig)
if 'contains' in self.options:
ingredients = [x.strip() for x in self.options.get('contains').split(',')]
recipes = self.env.get_domain('recipe')
recipes.add_recipe(sig, ingredients) class IngredientIndex(Index):
"""A custom index that creates an ingredient matrix."""
name = 'ingredient'
localname = 'Ingredient Index'
shortname = 'Ingredient'
def generate(self, docnames=None):
content = defaultdict(list)
recipes = {
name: (dispname, typ, docname, anchor)
for name, dispname, typ, docname, anchor, _ in self.domain.get_objects()
}
recipe_ingredients = self.domain.data['recipe_ingredients']
ingredient_recipes = defaultdict(list)
# flip from recipe_ingredients to ingredient_recipes
for recipe_name, ingredients in recipe_ingredients.items():
for ingredient in ingredients:
ingredient_recipes[ingredient].append(recipe_name)
# convert the mapping of ingredient to recipes to produce the expected
# output, shown below, using the ingredient name as a key to group
#
# name, subtype, docname, anchor, extra, qualifier, description
for ingredient, recipe_names in ingredient_recipes.items():
for recipe_name in recipe_names:
dispname, typ, docname, anchor = recipes[recipe_name]
content[ingredient].append((dispname, 0, docname, anchor, docname, '', typ))
# convert the dict to the sorted list of tuples expected
content = sorted(content.items())
return content, True class RecipeIndex(Index):
"""A custom index that creates an recipe matrix."""
name = 'recipe'
localname = 'Recipe Index'
shortname = 'Recipe'
def generate(self, docnames=None):
content = defaultdict(list)
# sort the list of recipes in alphabetical order
recipes = self.domain.get_objects()
recipes = sorted(recipes, key=lambda recipe: recipe[0])
# generate the expected output, shown below, from the above using the
# first letter of the recipe as a key to group thing
#
# name, subtype, docname, anchor, extra, qualifier, description
for _name, dispname, typ, docname, anchor, _priority in recipes:
content[dispname[0].lower()].append((
dispname,
0,
docname,
anchor,
docname,
'',
typ,
))
# convert the dict to the sorted list of tuples expected
content = sorted(content.items())
return content, True class RecipeDomain(Domain):
name = 'recipe'
label = 'Recipe Sample'
roles = {
'ref': XRefRole(),
}
directives = {
'recipe': RecipeDirective,
}
indices = {
RecipeIndex,
IngredientIndex,
}
initial_data = {
'recipes': [], # object list
'recipe_ingredients': {}, # name -> object
}
def get_full_qualified_name(self, node):
return f'recipe.{node.arguments[0]}'
def get_objects(self):
yield from self.data['recipes']
def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
match = [
(docname, anchor)
for name, sig, typ, docname, anchor, prio in self.get_objects()
if sig == target
]
if len(match) > 0:
todocname = match[0][0]
targ = match[0][1]
return make_refnode(builder, fromdocname, todocname, targ, contnode, targ)
else:
print('Awww, found nothing')
return None
def add_recipe(self, signature, ingredients):
"""Add a new recipe to the domain."""
name = f'recipe.{signature}'
anchor = f'recipe-{signature}'
self.data['recipe_ingredients'][name] = ingredients
# name, dispname, type, docname, anchor, priority
self.data['recipes'].append((name, signature, 'Recipe', self.env.docname, anchor, 0)) def setup(app: Sphinx) -> ExtensionMetadata:
app.add_domain(RecipeDomain)
return {
'version': '0.1',
'parallel_read_safe': True,
'parallel_write_safe': True,
}


Let's look at each piece of this extension step-by-step to explain what's going on.

The directive class

The first thing to examine is the RecipeDirective directive:

class RecipeDirective(ObjectDescription):

"""A custom directive that describes a recipe."""
has_content = True
required_arguments = 1
option_spec = {
'contains': directives.unchanged_required,
}
def handle_signature(self, sig, signode):
signode += addnodes.desc_name(text=sig)
return sig
def add_target_and_index(self, name_cls, sig, signode):
signode['ids'].append('recipe' + '-' + sig)
if 'contains' in self.options:
ingredients = [x.strip() for x in self.options.get('contains').split(',')]
recipes = self.env.get_domain('recipe')
recipes.add_recipe(sig, ingredients)


Unlike Developing a "Hello world" extension and Developing a "TODO" extension, this directive doesn't derive from docutils.parsers.rst.Directive and doesn't define a run method. Instead, it derives from sphinx.directives.ObjectDescription and defines handle_signature and add_target_and_index methods. This is because ObjectDescription is a special-purpose directive that's intended for describing things like classes, functions, or, in our case, recipes. More specifically, handle_signature implements parsing the signature of the directive and passes on the object's name and type to its superclass, while add_target_and_index adds a target (to link to) and an entry to the index for this node.

We also see that this directive defines has_content, required_arguments and option_spec. Unlike the TodoDirective directive added in the previous tutorial, this directive takes a single argument, the recipe name, and an option, contains, in addition to the nested reStructuredText in the body.

The index classes

Todo

Add brief overview of indices



class IngredientIndex(Index):

"""A custom index that creates an ingredient matrix."""
name = 'ingredient'
localname = 'Ingredient Index'
shortname = 'Ingredient'
def generate(self, docnames=None):
content = defaultdict(list)
recipes = {
name: (dispname, typ, docname, anchor)
for name, dispname, typ, docname, anchor, _ in self.domain.get_objects()
}
recipe_ingredients = self.domain.data['recipe_ingredients']
ingredient_recipes = defaultdict(list)
# flip from recipe_ingredients to ingredient_recipes
for recipe_name, ingredients in recipe_ingredients.items():
for ingredient in ingredients:
ingredient_recipes[ingredient].append(recipe_name)
# convert the mapping of ingredient to recipes to produce the expected
# output, shown below, using the ingredient name as a key to group
#
# name, subtype, docname, anchor, extra, qualifier, description
for ingredient, recipe_names in ingredient_recipes.items():
for recipe_name in recipe_names:
dispname, typ, docname, anchor = recipes[recipe_name]
content[ingredient].append((dispname, 0, docname, anchor, docname, '', typ))
# convert the dict to the sorted list of tuples expected
content = sorted(content.items())
return content, True


class RecipeIndex(Index):

"""A custom index that creates an recipe matrix."""
name = 'recipe'
localname = 'Recipe Index'
shortname = 'Recipe'
def generate(self, docnames=None):
content = defaultdict(list)
# sort the list of recipes in alphabetical order
recipes = self.domain.get_objects()
recipes = sorted(recipes, key=lambda recipe: recipe[0])
# generate the expected output, shown below, from the above using the
# first letter of the recipe as a key to group thing
#
# name, subtype, docname, anchor, extra, qualifier, description
for _name, dispname, typ, docname, anchor, _priority in recipes:
content[dispname[0].lower()].append((
dispname,
0,
docname,
anchor,
docname,
'',
typ,
))
# convert the dict to the sorted list of tuples expected
content = sorted(content.items())
return content, True


Both IngredientIndex and RecipeIndex are derived from Index. They implement custom logic to generate a tuple of values that define the index. Note that RecipeIndex is a simple index that has only one entry. Extending it to cover more object types is not yet part of the code.

Both indices use the method Index.generate() to do their work. This method combines the information from our domain, sorts it, and returns it in a list structure that will be accepted by Sphinx. This might look complicated but all it really is is a list of tuples like ('tomato', 'TomatoSoup', 'test', 'rec-TomatoSoup',...). Refer to the domain API guide for more information on this API.

These index pages can be referenced with the ref role by combining the domain name and the index name value. For example, RecipeIndex can be referenced with :ref:`recipe-recipe` and IngredientIndex can be referenced with :ref:`recipe-ingredient`.

The domain

A Sphinx domain is a specialized container that ties together roles, directives, and indices, among other things. Let's look at the domain we're creating here.

class RecipeDomain(Domain):

name = 'recipe'
label = 'Recipe Sample'
roles = {
'ref': XRefRole(),
}
directives = {
'recipe': RecipeDirective,
}
indices = {
RecipeIndex,
IngredientIndex,
}
initial_data = {
'recipes': [], # object list
'recipe_ingredients': {}, # name -> object
}
def get_full_qualified_name(self, node):
return f'recipe.{node.arguments[0]}'
def get_objects(self):
yield from self.data['recipes']
def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
match = [
(docname, anchor)
for name, sig, typ, docname, anchor, prio in self.get_objects()
if sig == target
]
if len(match) > 0:
todocname = match[0][0]
targ = match[0][1]
return make_refnode(builder, fromdocname, todocname, targ, contnode, targ)
else:
print('Awww, found nothing')
return None
def add_recipe(self, signature, ingredients):
"""Add a new recipe to the domain."""
name = f'recipe.{signature}'
anchor = f'recipe-{signature}'
self.data['recipe_ingredients'][name] = ingredients
# name, dispname, type, docname, anchor, priority
self.data['recipes'].append((name, signature, 'Recipe', self.env.docname, anchor, 0))


There are some interesting things to note about this recipe domain and domains in general. Firstly, we actually register our directives, roles and indices here, via the directives, roles and indices attributes, rather than via calls later on in setup. We can also note that we aren't actually defining a custom role and are instead reusing the sphinx.roles.XRefRole role and defining the sphinx.domains.Domain.resolve_xref method. This method takes two arguments, typ and target, which refer to the cross-reference type and its target name. We'll use target to resolve our destination from our domain's recipes because we currently have only one type of node.

Moving on, we can see that we've defined initial_data. The values defined in initial_data will be copied to env.domaindata[domain_name] as the initial data of the domain, and domain instances can access it via self.data. We see that we have defined two items in initial_data: recipes and recipe_ingredients. Each contains a list of all objects defined (i.e. all recipes) and a hash that maps a canonical ingredient name to the list of objects. The way we name objects is common across our extension and is defined in the get_full_qualified_name method. For each object created, the canonical name is recipe.<recipename>, where <recipename> is the name the documentation writer gives the object (a recipe). This enables the extension to use different object types that share the same name. Having a canonical name and central place for our objects is a huge advantage. Both our indices and our cross-referencing code use this feature.

The setup function

As always, the setup function is a requirement and is used to hook the various parts of our extension into Sphinx. Let's look at the setup function for this extension.

def setup(app: Sphinx) -> ExtensionMetadata:

app.add_domain(RecipeDomain)
return {
'version': '0.1',
'parallel_read_safe': True,
'parallel_write_safe': True,
}


This looks a little different to what we're used to seeing. There are no calls to add_directive() or even add_role(). Instead, we have a single call to add_domain() followed by some initialization of the standard domain. This is because we had already registered our directives, roles and indexes as part of the directive itself.

Using the extension

You can now use the extension throughout your project. For example:

index.rst

Joe's Recipes
=============
Below are a collection of my favourite recipes. I highly recommend the
:recipe:ref:`TomatoSoup` recipe in particular!
.. toctree::

tomato-soup


tomato-soup.rst

The recipe contains `tomato` and `cilantro`.
.. recipe:recipe:: TomatoSoup

:contains: tomato, cilantro, salt, pepper
This recipe is a tasty tomato soup, combine all ingredients
and cook.


The important things to note are the use of the :recipe:ref: role to cross-reference the recipe actually defined elsewhere (using the :recipe:recipe: directive).

Further reading

For more information, refer to the docutils documentation and Sphinx Extensions API.

Developing autodoc extension for IntEnum

The objective of this tutorial is to create an extension that adds support for new type for autodoc. This autodoc extension will format the IntEnum class from Python standard library. (module enum)

Overview

We want the extension that will create auto-documentation for IntEnum. IntEnum is the integer enum class from standard library enum module.

Currently this class has no special auto documentation behavior.

We want to add following to autodoc:

  • A new autointenum directive that will document the IntEnum class.
  • The generated documentation will have all the enum possible values with names.
  • The autointenum directive will have an option :hex: which will cause the integers be printed in hexadecimal form.

Prerequisites

We need the same setup as in the previous extensions. This time, we will be putting out extension in a file called autodoc_intenum.py. The my_enums.py will contain the sample enums we will document.

Here is an example of the folder structure you might obtain:

└── source

   ├── _ext
│   └── autodoc_intenum.py
   ├── conf.py
   ├── index.rst
   └── my_enums.py


Writing the extension

Start with setup function for the extension.

def setup(app: Sphinx) -> None:

app.setup_extension('sphinx.ext.autodoc') # Require autodoc extension
app.add_autodocumenter(IntEnumDocumenter)


The setup_extension() method will pull the autodoc extension because our new extension depends on autodoc. add_autodocumenter() is the method that registers our new auto documenter class.

We want to import certain objects from the autodoc extension:

from __future__ import annotations
from enum import IntEnum
from typing import TYPE_CHECKING, Any
from sphinx.ext.autodoc import ClassDocumenter, bool_option


There are several different documenter classes such as MethodDocumenter or AttributeDocumenter available in the autodoc extension but our new class is the subclass of ClassDocumenter which a documenter class used by autodoc to document classes.

This is the definition of our new the auto-documenter class:

class IntEnumDocumenter(ClassDocumenter):

objtype = 'intenum'
directivetype = ClassDocumenter.objtype
priority = 10 + ClassDocumenter.priority
option_spec = dict(ClassDocumenter.option_spec)
option_spec['hex'] = bool_option
@classmethod
def can_document_member(
cls, member: Any, membername: str, isattr: bool, parent: Any
) -> bool:
try:
return issubclass(member, IntEnum)
except TypeError:
return False
def add_directive_header(self, sig: str) -> None:
super().add_directive_header(sig)
self.add_line(' :final:', self.get_sourcename())
def add_content(
self,
more_content: StringList | None,
no_docstring: bool = False,
) -> None:
super().add_content(more_content, no_docstring)
source_name = self.get_sourcename()
enum_object: IntEnum = self.object
use_hex = self.options.hex
self.add_line('', source_name)
for the_member_name, enum_member in enum_object.__members__.items():
the_member_value = enum_member.value
if use_hex:
the_member_value = hex(the_member_value)
self.add_line(f'**{the_member_name}**: {the_member_value}', source_name)
self.add_line('', source_name)


Important attributes of the new class:

objtype
This attribute determines the auto directive name. In this case the auto directive will be autointenum.
This attribute sets the generated directive name. In this example the generated directive will be .. :py:class::.
the larger the number the higher is the priority. We want our documenter be higher priority than the parent.
option specifications. We copy the parent class options and add a new option hex.

Overridden members:

This member is important to override. It should return True when the passed object can be documented by this class.
This method generates the directive header. We add :final: directive option. Remember to call super or no directive will be generated.
This method generates the body of the class documentation. After calling the super method we generate lines for enum description.

Using the extension

You can now use the new autodoc directive to document any IntEnum.

For example, you have the following IntEnum:

my_enums.py

class Colors(IntEnum):

"""Colors enumerator"""
NONE = 0
RED = 1
GREEN = 2
BLUE = 3


This will be the documentation file with auto-documentation directive:

index.rst

.. autointenum:: my_enums.Colors


Configuring builders

Discover builders by entry point

Added in version 1.6.

builder extensions can be discovered by means of entry points so that they do not have to be listed in the extensions configuration value.

Builder extensions should define an entry point in the "sphinx.builders" group. The name of the entry point needs to match your builder's name attribute, which is the name passed to the sphinx-build -b option. The entry point value should equal the dotted name of the extension module. Here is an example of how an entry point for 'mybuilder' can be defined in the extension's pyproject.toml

[project.entry-points."sphinx.builders"]
mybuilder = "my.extension.module"


Note that it is still necessary to register the builder using add_builder() in the extension's setup() function.

Templating

Sphinx uses the Jinja templating engine for its HTML templates. Jinja is a text-based engine, inspired by Django templates, so anyone having used Django will already be familiar with it. It also has excellent documentation for those who need to make themselves familiar with it.

Do I need to use Sphinx's templates to produce HTML?

No. You have several other options:

  • You can write a TemplateBridge subclass that calls your template engine of choice, and set the template_bridge configuration value accordingly.
  • You can write a custom builder that derives from StandaloneHTMLBuilder and calls your template engine of choice.
  • You can use the PickleHTMLBuilder that produces pickle files with the page contents, and postprocess them using a custom tool, or use them in your Web application.

Jinja/Sphinx Templating Primer

The default templating language in Sphinx is Jinja. It's Django/Smarty inspired and easy to understand. The most important concept in Jinja is template inheritance, which means that you can overwrite only specific blocks within a template, customizing it while also keeping the changes at a minimum.

To customize the output of your documentation you can override all the templates (both the layout templates and the child templates) by adding files with the same name as the original filename into the template directory of the structure the Sphinx quickstart generated for you.

Sphinx will look for templates in the folders of templates_path first, and if it can't find the template it's looking for there, it falls back to the selected theme's templates.

A template contains variables, which are replaced with values when the template is evaluated, tags, which control the logic of the template and blocks which are used for template inheritance.

Sphinx's basic theme provides base templates with a couple of blocks it will fill with data. These are located in the themes/basic subdirectory of the Sphinx installation directory, and used by all builtin Sphinx themes. Templates with the same name in the templates_path override templates supplied by the selected theme.

For example, to add a new link to the template area containing related links all you have to do is to add a new template called layout.html with the following contents:

{% extends "!layout.html" %}
{% block rootrellink %}

<li><a href="https://project.invalid/">Project Homepage</a> &raquo;</li>
{{ super() }} {% endblock %}


By prefixing the name of the overridden template with an exclamation mark, Sphinx will load the layout template from the underlying HTML theme.

IMPORTANT:

If you override a block, call {{ super() }} somewhere to render the block's original content in the extended template -- unless you don't want that content to show up.


Working with the builtin templates

The builtin basic theme supplies the templates that all builtin Sphinx themes are based on. It has the following elements you can override or use:

Blocks

The following blocks exist in the layout.html template:

The doctype of the output format. By default this is XHTML 1.0 Transitional as this is the closest to what Sphinx and Docutils generate and it's a good idea not to change it unless you want to switch to HTML 5 or a different but compatible XHTML doctype.
This block adds a couple of <link> tags to the head section of the template.
This block is empty by default and can be used to add extra contents into the <head> tag of the generated HTML file. This is the right place to add references to JavaScript or extra CSS files.
This block contains the relation bar, the list of related links (the parent documents on the left, and the links to index, modules etc. on the right). relbar1 appears before the document, relbar2 after the document. By default, both blocks are filled; to show the relbar only before the document, you would override relbar2 like this:

{% block relbar2 %}{% endblock %}


Inside the relbar there are three sections: The rootrellink, the links from the documentation and the custom relbaritems. The rootrellink is a block that by default contains a list item pointing to the root document by default, the relbaritems is an empty block. If you override them to add extra links into the bar make sure that they are list items and end with the reldelim1.
The contents of the document itself. It contains the block "body" where the individual content is put by subtemplates like page.html.

NOTE:

In order for the built-in JavaScript search to show a page preview on the results page, the document or body content should be wrapped in an HTML element containing the role="main" attribute. For example:

<div role="main">

{% block document %}{% endblock %} </div>




A possible location for a sidebar. sidebar1 appears before the document and is empty by default, sidebar2 after the document and contains the default sidebar. If you want to swap the sidebar location override this and call the sidebar helper:

{% block sidebar1 %}{{ sidebar() }}{% endblock %}
{% block sidebar2 %}{% endblock %}


(The sidebar2 location for the sidebar is needed by the sphinxdoc.css stylesheet, for example.)

The logo location within the sidebar. Override this if you want to place some content at the top of the sidebar.
The block for the footer div. If you want a custom footer or markup before or after it, override this one.

The following four blocks are only used for pages that do not have assigned a list of custom sidebars in the html_sidebars config value. Their use is deprecated in favor of separate sidebar templates, which can be included via html_sidebars.

The table of contents within the sidebar.

Deprecated since version 1.0.

The relation links (previous, next document) within the sidebar.

Deprecated since version 1.0.

The "Show source" link within the sidebar (normally only shown if this is enabled by html_show_sourcelink).

Deprecated since version 1.0.

The search box within the sidebar. Override this if you want to place some content at the bottom of the sidebar.

Deprecated since version 1.0.


Configuration Variables

Inside templates you can set a couple of variables used by the layout template using the {% set %} tag:

The delimiter for the items on the left side of the related bar. This defaults to ' &raquo;' Each item in the related bar ends with the value of this variable.

The delimiter for the items on the right side of the related bar. This defaults to ' |'. Each item except of the last one in the related bar ends with the value of this variable.

Overriding works like this:

{% extends "!layout.html" %}
{% set reldelim1 = ' &gt;' %}


Add additional script files here, like this:

{% set script_files = script_files + ["_static/myscript.js"] %}


Deprecated since version 1.8.0: Please use .Sphinx.add_js_file() instead.


Helper Functions

Sphinx provides various Jinja functions as helpers in the template. You can use them to generate links or output multiply used elements.

Return the path to a Sphinx document as a URL. Use this to refer to built documents.

Return the path to a file which is a filename relative to the root of the generated output. Use this to refer to static files.

Check if a document with the name document exists.

Return the rendered sidebar.

Return the rendered relation bar.

Emit a warning message.

Global Variables

These global variables are available in every template and are safe to use. There are more, but most of them are an implementation detail and might change in the future.

The name of the builder (e.g. html or htmlhelp).

The value of copyright.

The title of the documentation (the value of html_title), except when the "single-file" builder is used, when it is set to None.

True if the built HTML is meant to be embedded in some viewing application that handles navigation, not the web browser, such as for HTML help or Qt help formats. In this case, the sidebar is not included.

The relative path to the HTML favicon image from the current document, or URL to the favicon, or ''.

Added in version 4.0.


The value of the builder's out_suffix attribute, i.e. the file name extension that the output files will get. For a standard HTML builder, this is usually .html.

True if the reST document sources are copied (if html_copy_source is True).

The value of language.

The build date.

The relative path to the HTML logo image from the current document, or URL to the logo, or ''.

Added in version 4.0.


Same as root_doc.

Changed in version 4.0: Renamed to root_doc.


The value of root_doc, for usage with pathto().

Changed in version 4.0: Renamed from master_doc.


The "page name" of the current file, i.e. either the document name if the file is generated from a reST source, or the equivalent hierarchical name relative to the output directory ([directory/]filename_without_extension).

The value of project.

The value of release.

A list of links to put at the left side of the relbar, next to "next" and "prev". This usually contains links to the general index and other indices, such as the Python module index. If you add something yourself, it must be a tuple (pagename, link title, accesskey, link text).

The value of html_short_title.

True if html_show_sourcelink is True.

The version of Sphinx used to build represented as a string for example "3.5.1".

The version of Sphinx used to build represented as a tuple of five elements. For Sphinx version 3.5.1 beta 3 this would be (3, 5, 1, 'beta', 3). The fourth element can be one of: alpha, beta, rc, final. final always has 0 as the last element.

Added in version 4.2.


The version of Docutils used to build represented as a tuple of five elements. For Docutils version 0.16.1 beta 2 this would be (0, 16, 1, 'beta', 2). The fourth element can be one of: alpha, beta, candidate, final. final always has 0 as the last element.

Added in version 5.0.2.


A list of the names of the main stylesheets as given by the theme or html_style.

Added in version 5.1.


The title of the current document, as used in the <title> tag.

The value of html_use_opensearch.

The value of version.

In addition to these values, there are also all theme options available (prefixed by theme_), as well as the values given by the user in html_context.

In documents that are created from source files (as opposed to automatically-generated files like the module index, or documents that already are in HTML form), these variables are also available:

A string containing the content of the page in HTML form as produced by the HTML builder, before the theme is applied.

A boolean that is True if the toc contains more than one entry.

Document metadata (a dictionary), see File-wide metadata.

A string containing the page's HTML meta tags.

The next document for the navigation. This variable is either false or has two attributes link and title. The title contains HTML markup. For example, to generate a link to the next page, you can use this snippet:

{% if next %}
<a href="{{ next.link|e }}">{{ next.title }}</a>
{% endif %}



The suffix of the file that was rendered. Since we support a list of source_suffix, this will allow you to properly link to the original source file.

A list of parent documents for navigation, structured like the next item.

Like next, but for the previous page.

The name of the copied source file for the current document. This is only nonempty if the html_copy_source value is True. This has empty value on creating automatically-generated files.

The local table of contents for the current page, rendered as HTML bullet lists.

A callable yielding the global TOC tree containing the current page, rendered as HTML bullet lists. Optional keyword arguments:
If true, all TOC entries that are not ancestors of the current page are collapsed. True by default.
The maximum depth of the tree. Set it to -1 to allow unlimited depth. Defaults to the max depth selected in the toctree directive.
If true, put only top-level document titles in the tree. False by default.
If true, the ToC tree will also contain hidden entries. False by default.


HTML theme development

Added in version 0.6.

NOTE:

This document provides information about creating your own theme. If you simply wish to use a pre-existing HTML themes, refer to HTML Theming.


Sphinx supports changing the appearance of its HTML output via themes. A theme is a collection of HTML templates, stylesheet(s) and other static files. Additionally, it has a configuration file which specifies from which theme to inherit, which highlighting style to use, and what options exist for customizing the theme's look and feel.

Themes are meant to be project-unaware, so they can be used for different projects without change.

NOTE:

See Sphinx Extensions API for more information that may be helpful in developing themes.


Creating themes

Themes take the form of either a directory or a zipfile (whose name is the theme name), containing the following:

  • Either a theme.toml file (preferred) or a theme.conf file.
  • HTML templates, if needed.
  • A static/ directory containing any static files that will be copied to the output static directory on build. These can be images, styles, script files.

Theme configuration (theme.toml)

The theme.toml file is a TOML document, containing two tables: [theme] and [options].

The [theme] table defines the theme's settings:

  • inherit (string): The name of the base theme from which to inherit settings, options, templates, and static files. All static files from theme 'ancestors' will be used. The theme will use all options defined in inherited themes. Finally, inherited themes will be used to locate missing templates (for example, if "basic" is used as the base theme, most templates will already be defined).

    If set to "none", the theme will not inherit from any other theme. Inheritance is recursive, forming a chain of inherited themes (e.g. default -> classic -> basic -> none).

  • stylesheets (list of strings): A list of CSS filenames which will be included in generated HTML header. Setting the html_style config value will override this setting.

    Other mechanisms for including multiple stylesheets include @import in CSS or using a custom HTML template with appropriate <link rel="stylesheet"> tags.

  • sidebars (list of strings): A list of sidebar templates. This can be overridden by the user via the html_sidebars config value.
  • pygments_style (table): A TOML table defining the names of Pygments styles to use for highlighting syntax. The table has two recognised keys: default and dark. The style defined in the dark key will be used when the CSS media query (prefers-color-scheme: dark) evaluates to true.

    [theme.pygments_style.default] can be overridden by the user via the pygments_style config value.


The [options] table defines the options for the theme. It is structured such that each key-value pair corresponds to a variable name and the corresponding default value. These options can be overridden by the user in html_theme_options and are accessible from all templates as theme_<name>.

Added in version 7.3: theme.toml support.

Exemplar theme.toml file:

[theme]
inherit = "basic"
stylesheets = [

"main-CSS-stylesheet.css", ] sidebars = [
"localtoc.html",
"relations.html",
"sourcelink.html",
"searchbox.html", ] # Style names from https://pygments.org/styles/ pygments_style = { default = "style_name", dark = "dark_style" } [options] variable = "default value"


Theme configuration (theme.conf)

The theme.conf file is in INI format [1] (readable by the standard Python configparser module) and has the following structure:

[theme]
inherit = base theme
stylesheet = main CSS name
pygments_style = stylename
sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html
[options]
variable = default value


  • The inherit setting gives the name of a "base theme", or none. The base theme will be used to locate missing templates (most themes will not have to supply most templates if they use basic as the base theme), its options will be inherited, and all of its static files will be used as well. If you want to also inherit the stylesheet, include it via CSS' @import in your own.
  • The stylesheet setting gives a list of CSS filenames separated commas which will be referenced in the HTML header. You can also use CSS' @import technique to include one from the other, or use a custom HTML template that adds <link rel="stylesheet"> tags as necessary. Setting the html_style config value will override this setting.
  • The pygments_style setting gives the name of a Pygments style to use for highlighting. This can be overridden by the user in the pygments_style config value.
  • The pygments_dark_style setting gives the name of a Pygments style to use for highlighting when the CSS media query (prefers-color-scheme: dark) evaluates to true. It is injected into the page using add_css_file().
  • The sidebars setting gives the comma separated list of sidebar templates for constructing sidebars. This can be overridden by the user in the html_sidebars config value.
  • The options section contains pairs of variable names and default values. These options can be overridden by the user in html_theme_options and are accessible from all templates as theme_<name>.

Added in version 1.7: sidebar settings

Changed in version 5.1: The stylesheet setting accepts multiple CSS filenames

Convert theme.conf to theme.toml

INI-style theme configuration files (theme.conf) can be converted to TOML via a helper programme distributed with Sphinx. This is intended for one-time use, and may be removed without notice in a future version of Sphinx.

$ python -m sphinx.theming conf_to_toml [THEME DIRECTORY PATH]


The required argument is a path to a directory containing a theme.conf file. The programme will write a theme.toml file in the same directory, and will not modify the original theme.conf file.

Added in version 7.3.

Distribute your theme as a Python package

As a way to distribute your theme, you can use a Python package. This makes it easier for users to set up your theme.

To distribute your theme as a Python package, please define an entry point called sphinx.html_themes in your pyproject.toml file, and write a setup() function to register your theme using the add_html_theme() API:

# pyproject.toml
[project.entry-points."sphinx.html_themes"]
name_of_theme = "your_theme_package"


# your_theme_package.py
from os import path
def setup(app):

app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__)))


If your theme package contains two or more themes, please call add_html_theme() twice or more.

Added in version 1.2: 'sphinx_themes' entry_points feature.

Deprecated since version 1.6: sphinx_themes entry_points has been deprecated.

Added in version 1.6: sphinx.html_themes entry_points feature.

Templating

The guide to templating is helpful if you want to write your own templates. What is important to keep in mind is the order in which Sphinx searches for templates:

  • First, in the user's templates_path directories.
  • Then, in the selected theme.
  • Then, in its base theme, its base's base theme, etc.

When extending a template in the base theme with the same name, use the theme name as an explicit directory: {% extends "basic/layout.html" %}. From a user templates_path template, you can still use the "exclamation mark" syntax as described in the templating document.

Static templates

Since theme options are meant for the user to configure a theme more easily, without having to write a custom stylesheet, it is necessary to be able to template static files as well as HTML files. Therefore, Sphinx supports so-called "static templates", like this:

If the name of a file in the static/ directory of a theme (or in the user's static path, for that matter) ends with _t, it will be processed by the template engine. The _t will be left from the final file name. For example, the classic theme has a file static/classic.css_t which uses templating to put the color options into the stylesheet. When a documentation project is built with the classic theme, the output directory will contain a _static/classic.css file where all template tags have been processed.

Use custom page metadata in HTML templates

Any key / value pairs in field lists that are placed before the page's title will be available to the Jinja template when building the page within the meta attribute. For example, if a page had the following text before its first title:

:mykey: My value
My first title
--------------


Then it could be accessed within a Jinja template like so:

{%- if meta is mapping %}

{{ meta.get("mykey") }} {%- endif %}


Note the check that meta is a dictionary ("mapping" in Jinja terminology) to ensure that using it in this way is valid.

Defining custom template functions

Sometimes it is useful to define your own function in Python that you wish to then use in a template. For example, if you'd like to insert a template value with logic that depends on the user's configuration in the project, or if you'd like to include non-trivial checks and provide friendly error messages for incorrect configuration in the template.

To define your own template function, you'll need to define two functions inside your module:

  • A page context event handler (or registration) function. This is connected to the Sphinx application via an event callback.
  • A template function that you will use in your Jinja template.

First, define the registration function, which accepts the arguments for html-page-context.

Within the registration function, define the template function that you'd like to use within Jinja. The template function should return a string or Python objects (lists, dictionaries) with strings inside that Jinja uses in the templating process

NOTE:

The template function will have access to all of the variables that are passed to the registration function.


At the end of the registration function, add the template function to the Sphinx application's context with context['template_func'] = template_func.

Finally, in your extension's setup() function, add your registration function as a callback for html-page-context.

# The registration function

def setup_my_func(app, pagename, templatename, context, doctree):
# The template function
def my_func(mystring):
return "Your string is %s" % mystring
# Add it to the page's context
context['my_func'] = my_func
# Your extension's setup function
def setup(app):
app.connect("html-page-context", setup_my_func)


Now, you will have access to this function in jinja like so:

<div>
{{ my_func("some string") }}
</div>


Add your own static files to the build assets

By default, Sphinx copies static files on the static/ directory of the template directory. However, if your package needs to place static files outside of the static/ directory for some reasons, you need to copy them to the _static/ directory of HTML outputs manually at the build via an event hook. Here is an example of code to accomplish this:

from os import path
from sphinx.util.fileutil import copy_asset_file
def copy_custom_files(app, exc):

if app.builder.format == 'html' and not exc:
staticdir = path.join(app.builder.outdir, '_static')
copy_asset_file('path/to/myextension/_static/myjsfile.js', staticdir) def setup(app):
app.connect('build-finished', copy_custom_files)


Inject JavaScript based on user configuration

If your extension makes use of JavaScript, it can be useful to allow users to control its behavior using their Sphinx configuration. However, this can be difficult to do if your JavaScript comes in the form of a static library (which will not be built with Jinja).

There are two ways to inject variables into the JavaScript space based on user configuration.

First, you may append _t to the end of any static files included with your extension. This will cause Sphinx to process these files with the templating engine, allowing you to embed variables and control behavior.

For example, the following JavaScript structure:

mymodule/
├── _static
│   └── myjsfile.js_t
└── mymodule.py


Will result in the following static file placed in your HTML's build output:

_build/
└── html

└── _static
   └── myjsfile.js


See Static templates for more information.

Second, you may use the Sphinx.add_js_file() method without pointing it to a file. Normally, this method is used to insert a new JavaScript file into your site. However, if you do not pass a file path, but instead pass a string to the "body" argument, then this text will be inserted as JavaScript into your site's head. This allows you to insert variables into your project's JavaScript from Python.

For example, the following code will read in a user-configured value and then insert this value as a JavaScript variable, which your extension's JavaScript code may use:

# This function reads in a variable and inserts it into JavaScript
def add_js_variable(app):

# This is a configuration that you've specified for users in `conf.py`
js_variable = app.config['my_javascript_variable']
js_text = "var my_variable = '%s';" % js_variable
app.add_js_file(None, body=js_text) # We connect this function to the step after the builder is initialized def setup(app):
# Tell Sphinx about this configuration variable
app.add_config_value('my_javascript_variable', 0, 'html')
# Run the function after the builder is initialized
app.connect('builder-inited', add_js_variable)


As a result, in your theme you can use code that depends on the presence of this variable. Users can control the variable's value by defining it in their conf.py file.

[1]
It is not an executable Python file, as opposed to conf.py, because that would pose an unnecessary security risk if themes are shared.

LaTeX customization

Unlike the HTML builders, the latex builder does not benefit from prepared themes. The Options for LaTeX output, and particularly the latex_elements variable, provides much of the interface for customization. For example:

# inside conf.py
latex_engine = 'xelatex'
latex_elements = {

'fontpkg': r''' \setmainfont{DejaVu Serif} \setsansfont{DejaVu Sans} \setmonofont{DejaVu Sans Mono} ''',
'preamble': r''' \usepackage[titles]{tocloft} \cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm} \setlength{\cftchapnumwidth}{0.75cm} \setlength{\cftsecindent}{\cftchapnumwidth} \setlength{\cftsecnumwidth}{1.25cm} ''',
'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
'printindex': r'\footnotesize\raggedright\printindex', } latex_show_urls = 'footnote'


NOTE:

Keep in mind that backslashes must be doubled in Python string literals to avoid interpretation as escape sequences. Alternatively, you may use raw strings as is done above.


The latex_elements configuration setting

A dictionary that contains LaTeX snippets overriding those Sphinx usually puts into the generated .tex files. Its 'sphinxsetup' key is described separately. It allows also local configurations inserted in generated files, via raw directives. For example, in the PDF documentation this chapter is styled especially, as will be described later.

Keys that you may want to override include:

'papersize'
Paper size option of the document class ('a4paper' or 'letterpaper')

Default: 'letterpaper'

'pointsize'
Point size option of the document class ('10pt', '11pt' or '12pt')

Default: '10pt'

'pxunit'
The value of the px when used in image attributes width and height. The default value is '0.75bp' which achieves 96px=1in (in TeX 1in = 72bp = 72.27pt.) To obtain for example 100px=1in use '0.01in' or '0.7227pt' (the latter leads to TeX computing a more precise value, due to the smaller unit used in the specification); for 72px=1in, simply use '1bp'; for 90px=1in, use '0.8bp' or '0.803pt'.

Default: '0.75bp'

Added in version 1.5.

'passoptionstopackages'
A string which will be positioned early in the preamble, designed to contain \\PassOptionsToPackage{options}{foo} commands.

HINT:

It may be also used for loading LaTeX packages very early in the preamble. For example package fancybox is incompatible with being loaded via the 'preamble' key, it must be loaded earlier.


Default: ''

Added in version 1.4.

'babel'
"babel" package inclusion, default '\\usepackage{babel}' (the suitable document language string is passed as class option, and english is used if no language.) For Japanese documents, the default is the empty string.

With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document to use polyglossia, but one should be aware that current babel has improved its support for Unicode engines in recent years and for some languages it may make sense to prefer babel over polyglossia.

HINT:

After modifying a core LaTeX key like this one, clean up the LaTeX build repertory before next PDF build, else left-over auxiliary files are likely to break the build.


Default: '\\usepackage{babel}' ('' for Japanese documents)

Changed in version 1.5: For latex_engine set to 'xelatex', the default is '\\usepackage{polyglossia}\n\\setmainlanguage{<language>}'.

Changed in version 1.6: 'lualatex' uses same default setting as 'xelatex'

Changed in version 1.7.6: For French, xelatex and lualatex default to using babel, not polyglossia.

'fontpkg'
Font package inclusion. The default is:

r"""\usepackage{tgtermes}
\usepackage{tgheros}
\renewcommand\ttdefault{txtt}
"""


For 'xelatex' and 'lualatex' however the default is to use the GNU FreeFont.

Changed in version 1.2: Defaults to '' when the language uses the Cyrillic script.

Changed in version 2.0: Incorporates some font substitution commands to help support occasional Greek or Cyrillic in a document using 'pdflatex' engine.

Changed in version 4.0.0:

  • The font substitution commands added at 2.0 have been moved to the 'fontsubstitution' key, as their presence here made it complicated for user to customize the value of 'fontpkg'.
  • The default font setting has changed: it still uses Times and Helvetica clones for serif and sans serif, but via better, more complete TeX fonts and associated LaTeX packages. The monospace font has been changed to better match the Times clone.

'fncychap'
Inclusion of the "fncychap" package (which makes fancy chapter titles), default '\\usepackage[Bjarne]{fncychap}' for English documentation (this option is slightly customized by Sphinx), '\\usepackage[Sonny]{fncychap}' for internationalized docs (because the "Bjarne" style uses numbers spelled out in English). Other "fncychap" styles you can try are "Lenny", "Glenn", "Conny", "Rejne" and "Bjornstrup". You can also set this to '' to disable fncychap.

Default: '\\usepackage[Bjarne]{fncychap}' for English documents, '\\usepackage[Sonny]{fncychap}' for internationalized documents, and '' for Japanese documents.

'preamble'
Additional preamble content. One may move all needed macros into some file mystyle.tex.txt of the project source repertory, and get LaTeX to import it at run time:

'preamble': r'\input{mystyle.tex.txt}',
# or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty
'preamble': r'\usepackage{mystyle}',


It is then needed to set appropriately latex_additional_files, for example:

latex_additional_files = ["mystyle.sty"]


Do not use .tex as suffix, else the file is submitted itself to the PDF build process, use .tex.txt or .sty as in the examples above.

Default: ''

'figure_align'
Latex figure float alignment. Whenever an image doesn't fit into the current page, it will be 'floated' into the next page but may be preceded by any other text. If you don't like this behavior, use 'H' which will disable floating and position figures strictly in the order they appear in the source.

Default: 'htbp' (here, top, bottom, page)

Added in version 1.3.

'atendofbody'
Additional document content (right before the indices).

Default: ''

Added in version 1.5.

'extrapackages'
Additional LaTeX packages. For example:

latex_elements = {

'extrapackages': r'\usepackage{isodate}' }


The specified LaTeX packages will be loaded before hyperref package and packages loaded from Sphinx extensions.

HINT:

If you'd like to load additional LaTeX packages after hyperref, use 'preamble' key instead.


Default: ''

Added in version 2.3.

'footer'
Additional footer content (before the indices).

Default: ''

Deprecated since version 1.5: Use 'atendofbody' key instead.


Keys that don't need to be overridden unless in special cases are:

'extraclassoptions'
The default is the empty string. Example: 'extraclassoptions': 'openany' will allow chapters (for documents of the 'manual' type) to start on any page.

Default: ''

Added in version 1.2.

Changed in version 1.6: Added this documentation.

'maxlistdepth'
LaTeX allows by default at most 6 levels for nesting list and quote-like environments, with at most 4 enumerated lists, and 4 bullet lists. Setting this key for example to '10' (as a string) will allow up to 10 nested levels (of all sorts). Leaving it to the empty string means to obey the LaTeX default.

WARNING:

  • Using this key may prove incompatible with some LaTeX packages or special document classes which do their own list customization.
  • The key setting is silently ignored if \usepackage{enumitem} is executed inside the document preamble. Use then rather the dedicated commands of this LaTeX package.



Default: 6

Added in version 1.5.

'inputenc'
"inputenc" package inclusion.

Default: '\\usepackage[utf8]{inputenc}' when using pdflatex, else ''.

NOTE:

If using utf8x in place of utf8 it is mandatory to extend the LaTeX preamble with suitable \PreloadUnicodePage{<number>} commands, as per the utf8x documentation (texdoc ucs on a TeXLive based TeX installation). Else, unexpected and possibly hard-to-spot problems (i.e. not causing a build crash) may arise in the PDF, in particular regarding hyperlinks.

Even if these precautions are taken, PDF build via pdflatex engine may crash due to upstream LaTeX not being fully compatible with utf8x. For example, in certain circumstances related to code-blocks, or attempting to include images whose filenames contain Unicode characters. Indeed, starting in 2015, upstream LaTeX with pdflatex engine has somewhat enhanced native support for Unicode and is becoming more and more incompatible with utf8x. In particular, since the October 2019 LaTeX release, filenames can use Unicode characters, and even spaces. At Sphinx level this means e.g. that the image and figure directives are now compatible with such filenames for PDF via LaTeX output. But this is broken if utf8x is in use.



Changed in version 1.4.3: Previously '\\usepackage[utf8]{inputenc}' was used for all compilers.

'cmappkg'
"cmap" package inclusion.

Default: '\\usepackage{cmap}'

Added in version 1.2.

'fontenc'
Customize this from its default '\\usepackage[T1]{fontenc}' to:
  • '\\usepackage[X2,T1]{fontenc}' if you need occasional Cyrillic letters (физика частиц),
  • '\\usepackage[LGR,T1]{fontenc}' if you need occasional Greek letters (Σωματιδιακή φυσική).

Use [LGR,X2,T1] rather if both are needed.

ATTENTION:

  • Do not use this key for a latex_engine other than 'pdflatex'.
  • If Greek is main language, do not use this key. Since Sphinx 2.2.1, xelatex will be used automatically as latex_engine.
  • The TeX installation may need some extra packages. For example, on Ubuntu xenial, packages texlive-lang-greek and cm-super are needed for LGR to work. And texlive-lang-cyrillic and cm-super are needed for support of Cyrillic.



Changed in version 1.5: Defaults to '\\usepackage{fontspec}' when latex_engine is 'xelatex'.

Changed in version 1.6: 'lualatex' uses fontspec per default like 'xelatex'.

Changed in version 2.0: 'lualatex' executes \defaultfontfeatures[\rmfamily,\sffamily]{} to disable TeX ligatures transforming << and >> as escaping working with pdflatex/xelatex failed with lualatex.

Changed in version 2.0: Detection of LGR, T2A, X2 to trigger support of occasional Greek or Cyrillic letters ('pdflatex').

Changed in version 2.3.0: 'xelatex' executes \defaultfontfeatures[\rmfamily,\sffamily]{} in order to avoid contractions of -- into en-dash or transforms of straight quotes into curly ones in PDF (in non-literal text paragraphs) despite smartquotes being set to False.

'fontsubstitution'
Ignored if 'fontenc' was not configured to use LGR or X2 (or T2A). In case 'fontpkg' key is configured for usage with some TeX fonts known to be available in the LGR or X2 encodings, set this one to be the empty string. Else leave to its default.

Ignored with latex_engine other than 'pdflatex'.

Added in version 4.0.0.

'textgreek'
For the support of occasional Greek letters.

It is ignored with 'platex', 'xelatex' or 'lualatex' as latex_engine and defaults to either the empty string or to '\\usepackage{textalpha}' for 'pdflatex' depending on whether the 'fontenc' key was used with LGR or not. Only expert LaTeX users may want to customize this key.

It can also be used as r'\usepackage{textalpha,alphabeta}' to let 'pdflatex' support Greek Unicode input in math context. For example :math:`α` (U+03B1) will render as \alpha.

Default: '\\usepackage{textalpha}' or '' if fontenc does not include the LGR option.

Added in version 2.0.

'geometry'
"geometry" package inclusion, the default definition is:

'\\usepackage{geometry}'


with an additional [dvipdfm] for Japanese documents. The Sphinx LaTeX style file executes:

\PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry}


which can be customized via corresponding 'sphinxsetup' options.

Default: '\\usepackage{geometry}' (or '\\usepackage[dvipdfm]{geometry}' for Japanese documents)

Added in version 1.5.

Changed in version 1.5.2: dvipdfm option if latex_engine is 'platex'.

Added in version 1.5.3: The 'sphinxsetup' keys for the margins.

Changed in version 1.5.3: The location in the LaTeX file has been moved to after \usepackage{sphinx} and \sphinxsetup{..}, hence also after insertion of 'fontpkg' key. This is in order to handle the paper layout options in a special way for Japanese documents: the text width will be set to an integer multiple of the zenkaku width, and the text height to an integer multiple of the baseline. See the hmargin documentation for more.

'hyperref'
"hyperref" package inclusion; also loads package "hypcap" and issues \urlstyle{same}. This is done after sphinx.sty file is loaded and before executing the contents of 'preamble' key.

ATTENTION:

Loading of packages "hyperref" and "hypcap" is mandatory.


Added in version 1.5: Previously this was done from inside sphinx.sty.

'maketitle'
"maketitle" call. Override if you want to generate a differently styled title page.

HINT:

If the key value is set to r'\newcommand\sphinxbackoftitlepage{<Extra material>}\sphinxmaketitle', then <Extra material> will be typeset on back of title page ('manual' docclass only).


Default: '\\sphinxmaketitle'

Changed in version 1.8.3: Original \maketitle from document class is not overwritten, hence is reusable as part of some custom setting for this key.

Added in version 1.8.3: \sphinxbackoftitlepage optional macro. It can also be defined inside 'preamble' key rather than this one.

'releasename'
Value that prefixes 'release' element on title page. As for title and author used in the tuples of latex_documents, it is inserted as LaTeX markup.

Default: 'Release'

'tableofcontents'
"tableofcontents" call. The default of '\\sphinxtableofcontents' is a wrapper of unmodified \tableofcontents, which may itself be customized by user loaded packages. Override if you want to generate a different table of contents or put content between the title page and the TOC.

Default: '\\sphinxtableofcontents'

Changed in version 1.5: Previously the meaning of \tableofcontents itself was modified by Sphinx. This created an incompatibility with dedicated packages modifying it also such as "tocloft" or "etoc".

'transition'
Commands used to display transitions. Override if you want to display transitions differently.

Default: '\n\n\\bigskip\\hrule\\bigskip\n\n'

Added in version 1.2.

Changed in version 1.6: Remove unneeded {} after \\hrule.

'makeindex'
"makeindex" call, the last thing before \begin{document}. With '\\usepackage[columns=1]{idxlayout}\\makeindex' the index will use only one column. You may have to install idxlayout LaTeX package.

Default: '\\makeindex'

'printindex'
"printindex" call, the last thing in the file. Override if you want to generate the index differently, append some content after the index, or change the font. As LaTeX uses two-column mode for the index it is often advisable to set this key to '\\footnotesize\\raggedright\\printindex'. Or, to obtain a one-column index, use '\\def\\twocolumn[#1]{#1}\\printindex' (this trick may fail if using a custom document class; then try the idxlayout approach described in the documentation of the 'makeindex' key).

Default: '\\printindex'

'fvset'
Customization of fancyvrb LaTeX package.

The default value is '\\fvset{fontsize=auto}' which means that the font size will adjust correctly if a code-block ends up in a footnote. You may need to modify this if you use custom fonts: '\\fvset{fontsize=\\small}' if the monospace font is Courier-like.

Default: '\\fvset{fontsize=auto}'

Added in version 1.8.

Changed in version 2.0: For 'xelatex' and 'lualatex' defaults to '\\fvset{fontsize=\\small}' as this is adapted to the relative widths of the FreeFont family.

Changed in version 4.0.0: Changed default for 'pdflatex'. Previously it was using '\\fvset{fontsize=\\small}'.

Changed in version 4.1.0: Changed default for Chinese documents to '\\fvset{fontsize=\\small,formatcom=\\xeCJKVerbAddon}'


Keys that are set by other options and therefore should not be overridden are:

'docclass' 'classoptions' 'title' 'release' 'author'

The sphinxsetup configuration setting

Added in version 1.5.

The 'sphinxsetup' key of latex_elements provides a LaTeX-type customization interface:

latex_elements = {

'sphinxsetup': 'key1=value1, key2=value2, ...', }


It defaults to empty. If non-empty, it will be passed as argument to the \sphinxsetup macro inside the document preamble, like this:

\usepackage{sphinx}
\sphinxsetup{key1=value1, key2=value2,...}


The colors used in the above are provided by the svgnames option of the "xcolor" package:

latex_elements = {

'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}', }


It is possible to insert uses of the \sphinxsetup LaTeX macro directly into the body of the document, via the raw directive. This chapter is styled in the PDF output using the following insertion at its start. This uses keys described later in Additional CSS-like 'sphinxsetup' keys.

.. raw:: latex

\begingroup
\sphinxsetup{%
TitleColor={named}{DarkGoldenrod},
% pre_border-width is 5.1.0 alias for verbatimborder
pre_border-width=2pt,
pre_border-right-width=8pt,
% pre_padding is a 5.1.0 alias for verbatimsep
pre_padding=5pt,
% Rounded boxes are new at 5.1.0
pre_border-radius=5pt,
% TeXcolor reminds that syntax must be as for LaTeX \definecolor
pre_background-TeXcolor={named}{OldLace},
% ... and since 5.3.0 also xcolor \colorlet syntax is accepted and we
% can thus drop the {named}{...} thing if xcolor is available!
pre_border-TeXcolor=Gold,
% ... and even take more advantage of xcolor syntax:
pre_border-TeXcolor=Gold!90,
% add a shadow to code-blocks
pre_box-shadow=6pt 6pt,
pre_box-shadow-TeXcolor=gray!20,
%
% This 5.1.0 CSS-named option is alias for warningborder
div.warning_border-width=3pt,
% Prior to 5.1.0, padding for admonitions was not customizable
div.warning_padding=6pt,
div.warning_padding-right=18pt,
div.warning_padding-bottom=18pt,
% Assume xcolor has been loaded with its svgnames option
div.warning_border-TeXcolor=DarkCyan,
div.warning_background-TeXcolor=LightCyan,
% This one is the only option with space separated input:
div.warning_box-shadow=-12pt -12pt inset,
div.warning_box-shadow-TeXcolor=Cyan,
%
% The 5.1.0 new name would be div.attention_border-width
attentionborder=3pt,
% The 5.1.0 name here would be div.attention_border-TeXcolor
attentionBorderColor=Crimson,
% The 5.1.0 name would be div.attention_background-TeXcolor
attentionBgColor=FloralWhite,
%
% For note/hint/important/tip, the CSS syntax was added at 6.2.0
% Legacy syntax still works
noteborder=1pt,
noteBorderColor=Olive,
% But setting a background color via the new noteBgColor means that
% it will be rendered using the same interface as warning type
noteBgColor=Olive!10,
% We can customize separately the four border-widths, and mimic
% the legacy "light" rendering, but now with a background color:
% div.note_border-left-width=0pt,
% div.note_border-right-width=0pt,
% Let's rather for variety use lateral borders:
div.note_border-top-width=0pt,
div.note_border-bottom-width=0pt,
%
% As long as only border width and border color are set, *and* using
% for this the old interface, the rendering will be the "light" one
hintBorderColor=LightCoral,
% but if we had used div.hint_border-TeXcolor or *any* CSS-named
% option we would have triggered the more complex "heavybox" code.
}


And this is placed at the end of the chapter source to end the scope of the configuration:

.. raw:: latex

\endgroup


LaTeX syntax for boolean keys requires lowercase true or false e.g 'sphinxsetup': "verbatimwrapslines=false". If setting the boolean key to true, =true is optional. Spaces around the commas and equal signs are ignored, spaces inside LaTeX macros may be significant. Do not use quotes to enclose values, whether numerical or strings.

Controls the depth of the collapsible bookmarks panel in the PDF. May be either a number (e.g. 3) or a LaTeX sectioning name (e.g. subsubsection, i.e. without backslash). For details, refer to the hyperref LaTeX docs.

Default: 5

Added in version 4.0.0.


The dimensions of the horizontal (resp. vertical) margins, passed as hmargin (resp. vmargin) option to the geometry package. Example:

'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in',


Japanese documents currently accept only the one-dimension format for these parameters. The geometry package is then passed suitable options to get the text width set to an exact multiple of the zenkaku width, and the text height set to an integer multiple of the baselineskip, with the closest fit for the margins.

Default: 1in (equivalent to {1in,1in})

HINT:

For Japanese 'manual' docclass with pointsize 11pt or 12pt, use the nomag extra document class option (cf. 'extraclassoptions' key of latex_elements) or so-called TeX "true" units:

'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw',




Added in version 1.5.3.

The \marginparwidth LaTeX dimension. For Japanese documents, the value is modified to be the closest integer multiple of the zenkaku width.

Default: 0.5in

Added in version 1.5.3.

Boolean to specify if code-blocks and literal includes are framed. Setting it to false does not deactivate use of package "framed", because it is still in use for the optional background color.

Default: true.

Boolean to specify if long lines in code-block's contents are wrapped.

If true, line breaks may happen at spaces (the last space before the line break will be rendered using a special symbol), and at ascii punctuation characters (i.e. not at letters or digits). Whenever a long string has no break points, it is moved to next line. If its length is longer than the line width it will overflow.

Default: true


Boolean to specify if long lines in code-block's contents should be forcefully wrapped to never overflow due to long strings.

NOTE:

It is assumed that the Pygments LaTeXFormatter has not been used with its texcomments or similar options which allow additional (arbitrary) LaTeX mark-up.

Also, in case of latex_engine set to 'pdflatex', only the default LaTeX handling of Unicode code points, i.e. utf8 not utf8x is allowed.



Default: false

Added in version 3.5.0.

A number. If an unbreakable long string has length larger than the total linewidth plus this number of characters, and if verbatimforcewraps mode is on, the input line will be reset using the forceful algorithm which applies breakpoints at each character.

Default: 3

Added in version 3.5.0.

A number. If verbatimforcewraps mode applies, and if after applying the line wrapping at spaces and punctuation, the first part of the split line is lacking at least that number of characters to fill the available width, then the input line will be reset using the forceful algorithm.

As the default is set to a high value, the forceful algorithm is triggered only in overfull case, i.e. in presence of a string longer than full linewidth. Set this to 0 to force all input lines to be hard wrapped at the current available linewidth:

latex_elements = {

'sphinxsetup': "verbatimforcewraps, verbatimmaxunderfull=0", }


This can be done locally for a given code-block via the use of raw latex directives to insert suitable \sphinxsetup (before and after) into the latex file.

Default: 100

Added in version 3.5.0.

Boolean to specify if code-blocks display "continued on next page" and "continued from previous page" hints in case of page breaks.

Default: true

Added in version 1.6.3.

Changed in version 1.7: the default changed from false to true.

Horizontal position relative to the framed contents: either l (left aligned), r (right aligned) or c (centered).

Default: r

Added in version 1.7.

Boolean to specify if long lines in parsed-literal's contents should wrap.

Default: true

Added in version 1.5.2: set this option value to false to recover former behavior.

Boolean to specify if line breaks are allowed inside inline literals: but extra potential break-points (additionally to those allowed by LaTeX at spaces or for hyphenation) are currently inserted only after the characters . , ; ? ! / and \. Due to TeX internals, white space in the line will be stretched (or shrunk) in order to accommodate the linebreak.

Default: true

Added in version 1.5: set this option value to false to recover former behavior.

Changed in version 2.3.0: added potential breakpoint at \ characters.

When a long code line is split, the last space character from the source code line right before the linebreak location is typeset using this.

Default: \textcolor{red}{\textvisiblespace}

A LaTeX macro inserted at start of continuation code lines. Its (complicated...) default typesets a small red hook pointing to the right:

\makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}}


Changed in version 1.5: The breaking of long code lines was added at 1.4.2. The default definition of the continuation symbol was changed at 1.5 to accommodate various font sizes (e.g. code-blocks can be in footnotes).


NOTE:

Values for color keys must either:
  • obey the syntax of the \definecolor LaTeX command, e.g. something such as VerbatimColor={rgb}{0.2,0.3,0.5} or {RGB}{37,23,255} or {gray}{0.75} or (only with package xcolor) {HTML}{808080} or ...
  • or obey the syntax of the \colorlet command from package xcolor (which then must exist in the LaTeX installation), e.g. VerbatimColor=red!10 or red!50!green or -red!75 or MyPreviouslyDefinedColor or... Refer to xcolor documentation for this syntax.

Changed in version 5.3.0: Formerly only the \definecolor syntax was accepted.



The color for titles (as configured via use of package "titlesec".)

Default: {rgb}{0.126,0.263,0.361}

A color passed to hyperref as value of linkcolor and citecolor.

Default: {rgb}{0.208,0.374,0.486}.

A color passed to hyperref as value of filecolor, menucolor, and urlcolor.

Default: {rgb}{0.216,0.439,0.388}

The background color for code-blocks.

Default: {gray}{0.95}

Changed in version 6.0.0: Formerly, it was {rgb}{1,1,1} (white).

The frame color.

Default: {RGB}{32,32,32}

Changed in version 6.0.0: Formerly it was {rgb}{0,0,0} (black).

The color for highlighted lines.

Default: {rgb}{0.878,1,1}

Added in version 1.6.6.


Sets the background color for (all) the header rows of tables.

It will have an effect only if either the latex_table_style contains 'colorrows' or if the table is assigned the colorrows class. It is ignored for tables with nocolorrows class.

As for the other 'sphinxsetup' keys, it can also be set or modified from a \sphinxsetup{...} LaTeX command inserted via the raw directive, or also from a LaTeX environment associated to a container class and using such \sphinxsetup{...}.

Default: {gray}{0.86}

There is also TableMergeColorHeader. If used, sets a specific color for merged single-row cells in the header.

Added in version 5.3.0.

Sets the background color for odd rows in tables (the row count starts at 1 at the first non-header row). Has an effect only if the latex_table_style contains 'colorrows' or for specific tables assigned the colorrows class.

Default: {gray}{0.92}

There is also TableMergeColorOdd.

Added in version 5.3.0.

Sets the background color for even rows in tables.

Default {gray}{0.98}

There is also TableMergeColorEven.

Added in version 5.3.0.

The separation between code lines and the frame.

See Additional CSS-like 'sphinxsetup' keys for its alias pre_padding and additional keys.

Default: \fboxsep

The width of the frame around code-blocks. See also Additional CSS-like 'sphinxsetup' keys for pre_border-width.

Default: \fboxrule

The separation between contents and frame for contents and topic boxes.

See Additional CSS-like 'sphinxsetup' keys for the alias div.topic_padding.

Default: 5pt

The width of the lateral "shadow" to the right and bottom.

See Additional CSS-like 'sphinxsetup' keys for div.topic_box-shadow which allows to configure separately the widths of the vertical and horizontal shadows.

Default: 4pt

Changed in version 6.1.2: Fixed a regression introduced at 5.1.0 which modified unintentionally the width of topic boxes and worse had made usage of this key break PDF builds.

The width of the frame around topic boxes. See also Additional CSS-like 'sphinxsetup' keys for div.topic_border-width.

Default: \fboxrule

importantBorderColor, tipBorderColor The color for the two horizontal rules used by Sphinx in LaTeX for styling a note type admonition.

Default: {rgb}{0,0,0} (black)

importantBgColor, tipBgColor The optional color for the background. It is a priori set to white, but is not used, unless it has been set explicitly, and doing this triggers Sphinx into switching to the more complex LaTeX code which is employed also for warning type admonitions. There are then additional options which are described in Additional CSS-like 'sphinxsetup' keys.

Default: {rgb}{1,1,1} (white)

Added in version 6.2.0.

importantTextColor, tipTextColor The optional color for the contents.

Default: unset (uses ambient text color, a priori black)

Added in version 6.2.0: To be considered experimental until 7.0.0. These options have aliases div.note_TeXcolor (etc) described in Additional CSS-like 'sphinxsetup' keys. Using the latter will let Sphinx switch to a more complex LaTeX code, which supports the customizability described in Additional CSS-like 'sphinxsetup' keys.

importantTeXextras, tipTeXextras Some extra LaTeX code (such as \bfseries or \footnotesize) to be executed at start of the contents.

Default: empty

Added in version 6.2.0: To be considered experimental until 7.0.0. These options have aliases div.note_TeXextras (etc) described in Additional CSS-like 'sphinxsetup' keys.

The width of the two horizontal rules.

If the background color is set, or the alternative Additional CSS-like 'sphinxsetup' keys syntax is used (e.g. div.note_border-width=1pt in place of noteborder=1pt), or any option with a CSS-alike name is used, then the border is a full frame and this parameter sets its width also for left and right.

Default: 0.5pt


attentionBorderColor, dangerBorderColor, errorBorderColor The color for the admonition frame.

Default: {rgb}{0,0,0} (black)

attentionBgColor, dangerBgColor, errorBgColor The background colors for the respective admonitions.

Default: {rgb}{1,1,1} (white)

attentionborder, dangerborder, errorborder The width of the frame. See Additional CSS-like 'sphinxsetup' keys for keys allowing to configure separately each border width.

Default: 1pt

LaTeX macros inserted at the start of the footnote text at bottom of page, after the footnote number.

Default: \mbox{ }

LaTeX macros inserted before the footnote mark. The default removes possible space before it (else, TeX could insert a line break there).

Default: \leavevmode\unskip

Added in version 1.5.

default \sffamily\bfseries. Sets the font used by headings.

Additional CSS-like 'sphinxsetup' keys

Added in version 5.1.0: For code-block, topic and contents directive, and strong-type admonitions (warning, error, ...).

Added in version 6.2.0: Also the note, hint, important and tip admonitions can be styled this way. Using for them any of the listed options will trigger usage of a more complex LaTeX code than the one used per default (sphinxheavybox vs sphinxlightbox). Setting the new noteBgColor (or hintBgColor, ...) also triggers usage of sphinxheavybox for note (or hint, ...).

Perhaps in future these 5.1.0 (and 6.2.0) novel settings will be optionally imported from some genuine CSS external file, but currently they have to be used via the 'sphinxsetup' interface (or the \sphinxsetup LaTeX command inserted via the raw directive) and the CSS syntax is only imitated.

IMPORTANT:

Low-level LaTeX errors causing a build failure can happen if the input syntax is not respected.
In particular colors must be input as for the other color related options previously described, i.e. either in the \definecolor syntax or, if package xcolor is available (it is then automatically used) also the \colorlet syntax:

...<other options>
div.warning_border-TeXcolor={rgb}{1,0,0},% (always works)
div.error_background-TeXcolor=red!10,% (works only if xcolor is available)
...<other options>


  • A colon in place of the equal sign will break LaTeX.
  • ...border-width or ...padding expect a single dimension: they can not be used so far with space separated dimensions.
  • ...top-right-radius et al. values may be either a single or two space separated dimensions.
  • Dimension specifications must use TeX units such as pt or cm or in. The px unit is recognized by pdflatex and lualatex but not by xelatex or platex.
  • It is allowed for such specifications to be so-called "dimensional expressions", e.g. \fboxsep+2pt or 0.5\baselineskip are valid inputs. The expressions will be evaluated only at the typesetting time. Be careful though if using as in these examples TeX control sequences to double the backslash or to employ a raw Python string for the value of the 'sphinxsetup' key.
  • As a rule, avoid inserting unneeded spaces in the key values: especially for the radii an input such 2 pt 3pt will break LaTeX. Beware also that \fboxsep \fboxsep will not be seen as space separated in LaTeX. You must use something such as {\fboxsep} \fboxsep. Or use directly 3pt 3pt which is a priori equivalent and simpler.



The options are all named in a similar pattern which depends on a prefix, which is then followed by an underscore, then the property name.

Directive Option prefix LaTeX environment
code-block pre sphinxVerbatim
topic div.topic sphinxShadowBox
contents div.topic sphinxShadowBox
note div.note sphinxnote using sphinxheavybox
warning div.warning sphinxwarning (uses sphinxheavybox)
admonition type div.<type> sphinx<type> (using sphinxheavybox)

Here are now these options as well as their common defaults. Replace below <prefix> by the actual prefix as explained above. Don't forget the underscore separating the prefix from the property names.

<prefix>_border-top-width,
<prefix>_border-right-width,
<prefix>_border-bottom-width,
<prefix>_border-left-width,
<prefix>_border-width.  The latter can (currently) be only a single
dimension which then sets all four others.

The default is that all those dimensions are equal. They are set to:

  • \fboxrule (i.e. a priori 0.4pt) for code-block,
  • \fboxrule for topic or contents directive,
  • 1pt for warning and other "strong" admonitions,
  • 0.5pt for note and other "light" admonitions. The framing style of the "lighbox" used for them in absence of usage of CSS-named options will be emulated by the richer "heavybox" if setting border-left-width and border-right-width both to 0pt.

  • <prefix>_box-decoration-break can be set to either clone or slice and configures the behavior at page breaks. It defaults to slice for code-block (i.e. for <prefix>=pre) since 6.0.0. For other directives the default is clone.
  • <prefix>_padding-top,
    <prefix>_padding-right,
    <prefix>_padding-bottom,
    <prefix>_padding-left,
    <prefix>_padding.  The latter can (currently) be only a single
    dimension which then sets all four others.

    The default is that all those dimensions are equal. They are set to:

  • \fboxsep (i.e. a priori 3pt) for code-block,
  • 5pt for topic or contents directive,
  • a special value for warning and other "strong" admonitions, which ensures a backward compatible behavior.

    IMPORTANT:

Prior to 5.1.0 there was no separate customizability of padding for warning-type boxes in PDF via LaTeX output. The sum of padding and border-width (as set for example for warning by warningborder, now also named div.warning_border-width) was kept to a certain constant value. This limited the border-width to small values else the border could overlap the text contents. This behavior is kept as default.


the same padding behavior is obeyed per default for note or other "light" admonitions when using sphinxheavybox.

<prefix>_border-top-left-radius,
<prefix>_border-top-right-radius,
<prefix>_border-bottom-right-radius,
<prefix>_border-bottom-left-radius,
<prefix>_border-radius.  This last key sets the first four to
its assigned value.  Each key value can be either a single, or two,
dimensions which are then space separated.

The default is that all four corners are either circular or straight, with common radii:

  • \fboxsep (i.e. a priori 3pt) for code-block (since 6.0.0).
  • 0pt for all other directives; this means to use straight corners.

See a remark above about traps with spaces in LaTeX.

<prefix>_box-shadow is special in so far as it may be:
  • the none keyword,
  • or a single dimension (giving both x-offset and y-offset),
  • or two dimensions (separated by a space),
  • or two dimensions followed by the keyword inset.

The x-offset and y-offset may be negative. The default is none, except for the topic or contents directives, for which it is 4pt 4pt, i.e. the shadow has a width of 4pt and extends to the right and below the frame. The lateral shadow then extends into the page right margin.

  • <prefix>_border-TeXcolor,
    <prefix>_background-TeXcolor,
    <prefix>_box-shadow-TeXcolor,
    <prefix>_TeXcolor.
    These are colors.

    The shadow color defaults in all cases to {rgb}{0,0,0} i.e. to black.

    Since 6.0.0 the border color and background color of code-block, i.e. pre prefix, default respectively to {RGB}{32,32,32} and {gray}{0.95}. They previously defaulted to black, respectively white.

    For all other types, the border color defaults to black and the background color to white.

    The <prefix>_TeXcolor stands for the CSS property "color", i.e. it influences the text color of the contents. As for the three other options, the naming TeXcolor is to stress that the input syntax is the TeX one for colors not an HTML/CSS one. If package xcolor is available in the LaTeX installation, one can use directly named colors as key values. Consider passing options such as dvipsnames, svgnames or x11names to xcolor via 'passoptionstopackages' key of latex_elements.

    If <prefix>_TeXcolor is set, a \color command is inserted at start of the directive contents; for admonitions, this happens after the heading which reproduces the admonition type.

  • <prefix>_TeXextras: if set, its value must be some LaTeX command or commands, for example \itshape. These commands will be inserted at the start of the contents; for admonitions, this happens after the heading which reproduces the admonition type.

NOTE:

  • All directives support box-decoration-break to be set to slice.

    Changed in version 6.2.0: Formerly, only code-block did. The default remains clone for all other directives, but this will probably change at 7.0.0.

  • The corners of rounded boxes may be elliptical.

    Changed in version 6.2.0: Formerly, only circular rounded corners were supported and a rounded corner forced the whole frame to use the same constant width from <prefix>_border-width.

  • Inset shadows are incompatible with rounded corners. In case both are specified the inset shadow will simply be ignored.

    Changed in version 6.2.0: Formerly it was to the contrary the rounded corners which were ignored in case an inset shadow was specified.

  • <prefix>_TeXcolor and <prefix>_TeXextras are new with 6.2.0.

    Usefulness is doubtful in the case of code-block:

  • pre_TeXcolor will influence only the few non-Pygments highlighted tokens; it does color the line numbers, but if one wants to color only them one has to go through the fancyvrb interface.
  • pre_TeXextras=\footnotesize for example may be replaced by usage of the latex_elements key 'fvset'. For 'lualatex' or 'xelatex' Sphinx includes in the preamble already \fvset{fontsize=\small} and this induces fancyvrb into overriding a \footnotesize coming from pre_TeXextras. One has to use pre_TeXextras=\fvset{fontsize=\footnotesize} syntax. Simpler to set directly the latex_elements key 'fvset'...

Consider these options experimental and that some implementation details may change. For example if the pre_TeXextras LaTeX commands were put by Sphinx in another location it could override the 'fvset' effect, perhaps this is what will be done in a future release.

  • Rounded boxes are done using the pict2e interface to some basic PDF graphics operations. If this LaTeX package can not be found the build will proceed and render all boxes with straight corners.
  • Elliptic corners use the ellipse LaTeX package which extends pict2e. If this LaTeX package can not be found rounded corners will be circular arcs (or straight if pict2e is not available).



The following legacy behavior is currently not customizable:

  • For code-block, padding and border-width and shadow (if one adds one) will go into the margin; the code lines remain at the same place independently of the values of the padding and border-width, except for being shifted vertically of course to not overwrite other text due to the width of the border or external shadow.
  • For topic (and contents) the shadow (if on right) goes into the page margin, but the border and the extra padding are kept within the text area. Same for admonitions.
  • The contents and topic directives are governed by the same options with div.topic prefix: the Sphinx LaTeX mark-up uses for both directives the same sphinxShadowBox environment which has currently no additional branching, contrarily to the sphinxadmonition environment which branches according to the admonition directive name, e.g. either to sphinxnote or sphinxwarning etc...

LaTeX macros and environments

The "LaTeX package" file sphinx.sty loads various components providing support macros (aka commands), and environments, which are used in the mark-up produced on output from the latex builder, before conversion to pdf via the LaTeX toolchain. Also the "LaTeX class" files sphinxhowto.cls and sphinxmanual.cls define or customize some environments. All of these files can be found in the latex build repertory.

Some of these provide facilities not available from pre-existing LaTeX packages and work around LaTeX limitations with lists, table cells, verbatim rendering, footnotes, etc...

Others simply define macros with public names to make overwriting their defaults easy via user-added contents to the preamble. We will survey most of those public names here, but defaults have to be looked at in their respective definition files.

HINT:

Sphinx LaTeX support code is split across multiple smaller-sized files. Rather than adding code to the preamble via latex_elements['preamble'] it is also possible to replace entirely one of the component files of Sphinx LaTeX code with a custom version, simply by including a modified copy in the project source and adding the filename to the latex_additional_files list. Check the LaTeX build repertory for the filenames and contents.


Changed in version 4.0.0: split of sphinx.sty into multiple smaller units, to facilitate customization of many aspects simultaneously.

Macros

  • Text styling commands:
    Name maps argument #1 to:
    \sphinxstrong \textbf{#1}
    \sphinxcode \texttt{#1}
    \sphinxbfcode \textbf{\sphinxcode{#1}}
    \sphinxemail \textsf{#1}
    \sphinxtablecontinued \textsf{#1}
    \sphinxtitleref \emph{#1}
    \sphinxmenuselection \emph{#1}
    \sphinxguilabel \emph{#1}
    \sphinxkeyboard \sphinxcode{#1}
    \sphinxaccelerator \underline{#1}
    \sphinxcrossref \emph{#1}
    \sphinxtermref \emph{#1}
    \sphinxsamedocref \emph{#1}
    \sphinxparam \emph{#1}
    \sphinxtypeparam \emph{#1}
    \sphinxoptional [#1] with larger brackets, see source

    Added in version 1.4.5: Use of \sphinx prefixed macro names to limit possibilities of conflict with LaTeX packages.

    Added in version 1.8: \sphinxguilabel

    Added in version 3.0: \sphinxkeyboard

    Added in version 6.2.0: \sphinxparam, \sphinxsamedocref

    Added in version 7.1.0: \sphinxparamcomma which defaults to a comma followed by a space and \sphinxparamcommaoneperline which is used for one-parameter-per-line signatures (see maximum_signature_line_length). It defaults to \texttt{,} to make these end-of-line separators more distinctive.

    Signatures of Python functions are rendered as name<space>(parameters) or name<space>[type parameters]<space>(parameters) (see PEP 695) where the length of <space> is set to 0pt by default. This can be changed via \setlength{\sphinxsignaturelistskip}{1ex} for instance.

  • More text styling:
    Name maps argument #1 to:
    \sphinxstyleindexentry \texttt{#1}
    \sphinxstyleindexextra (\emph{#1}) (with a space upfront)
    \sphinxstyleindexpageref , \pageref{#1}
    \sphinxstyleindexpagemain \textbf{#1}
    \sphinxstyleindexlettergroup {\Large\sffamily#1}\nopagebreak\vspace{1mm}
    \sphinxstyleindexlettergroupDefault check source, too long for here
    \sphinxstyletopictitle \textbf{#1}\par\medskip
    \sphinxstylesidebartitle \textbf{#1}\par\medskip
    \sphinxstyleothertitle \textbf{#1}
    \sphinxstylesidebarsubtitle ~\\\textbf{#1} \smallskip
    \sphinxstyletheadfamily \sffamily (this one has no argument)
    \sphinxstyleemphasis \emph{#1}
    \sphinxstyleliteralemphasis \emph{\sphinxcode{#1}}
    \sphinxstylestrong \textbf{#1}
    \sphinxstyleliteralstrong \sphinxbfcode{#1}
    \sphinxstyleabbreviation \textsc{#1}
    \sphinxstyleliteralintitle \sphinxcode{#1}
    \sphinxstylecodecontinued {\footnotesize(#1)}}
    \sphinxstylecodecontinues {\footnotesize(#1)}}
    \sphinxstylenotetitle \sphinxstrong{#1}<space>
    \sphinxstylehinttitle idem
    \sphinxstyleimportanttitle idem
    \sphinxstyletiptitle idem
    \sphinxstylewarningtitle idem
    \sphinxstylecautiontitle idem
    \sphinxstyleattentiontitle idem
    \sphinxstyledangertitle idem
    \sphinxstyleerrortitle idem
    \sphinxstyleseealsotitle \sphinxstrong{#1}\par\nopagebreak

    Added in version 1.5: These macros were formerly hard-coded as non customizable \texttt, \emph, etc...

    Added in version 1.6: \sphinxstyletheadfamily which defaults to \sffamily and allows multiple paragraphs in header cells of tables.

    Added in version 1.6.3: \sphinxstylecodecontinued and \sphinxstylecodecontinues.

    Added in version 1.8: \sphinxstyleindexlettergroup, \sphinxstyleindexlettergroupDefault.

    Added in version 6.2.0: \sphinxstylenotetitle et al. The #1 is the localized name of the directive, with a final colon. Wrap it as \sphinxremovefinalcolon{#1} if this final colon is to be removed. Examples:

\renewcommand\sphinxstylewarningtitle[1]{%

\underline{\textbf{\sphinxremovefinalcolon{#1}}}\par } \renewcommand{\sphinxstylenotetitle}[1]{%
\textit{\textbf{\sphinxremovefinalcolon{#1}}}\par\nobreak
% LaTeX syntax is complex and we would be better off using \hrule.
{\parskip0pt\noindent}%
\raisebox{1ex}%
{\makebox[\linewidth]{\textcolor{sphinxnoteBorderColor}{\dotfill}}}
% It is complex to obtain nice vertical spacing for both a paragraph
% or a list following up; this set-up is better for a paragraph next.
\par\vskip-\parskip }


\sphinxtableofcontents: A wrapper (defined differently in sphinxhowto.cls and in sphinxmanual.cls) of standard \tableofcontents. The macro \sphinxtableofcontentshook is executed during its expansion right before \tableofcontents itself.

Changed in version 1.5: Formerly, the meaning of \tableofcontents was modified by Sphinx.

Changed in version 2.0: Hard-coded redefinitions of \l@section and \l@subsection formerly done during loading of 'manual' docclass are now executed later via \sphinxtableofcontentshook. This macro is also executed by the 'howto' docclass, but defaults to empty with it.

HINT:

If adding to preamble the loading of tocloft package, also add to preamble \renewcommand\sphinxtableofcontentshook{} else it will reset \l@section and \l@subsection cancelling tocloft customization.


  • \sphinxmaketitle: Used as the default setting of the 'maketitle' latex_elements key. Defined in the class files sphinxmanual.cls and sphinxhowto.cls.

    Changed in version 1.8.3: Formerly, \maketitle from LaTeX document class was modified by Sphinx.

  • \sphinxbackoftitlepage: For 'manual' docclass, and if it is defined, it gets executed at end of \sphinxmaketitle, before the final \clearpage. Use either the 'maketitle' key or the 'preamble' key of latex_elements to add a custom definition of \sphinxbackoftitlepage.

    Added in version 1.8.3.

  • \sphinxcite: A wrapper of standard \cite for citation references.

The \sphinxbox command

Added in version 6.2.0.

The \sphinxbox[key=value,...]{inline text} command can be used to "box" inline text elements with all the customizability which has been described in Additional CSS-like 'sphinxsetup' keys. It is a LaTeX command with one optional argument, which is a comma-separated list of key=value pairs, as for The sphinxsetup configuration setting. Here is the complete list of keys. They don't use any prefix.

  • border-width,
  • border-top-width, border-right-width, border-bottom-width, border-left-width,
  • padding,
  • padding-top, padding-right, padding-bottom, padding-left,
  • border-radius,
  • border-top-left-radius, border-top-right-radius, border-bottom-right-radius, border-bottom-left-radius,
  • box-shadow,
  • border-TeXcolor, background-TeXcolor, box-shadow-TeXcolor, TeXcolor,
  • TeXextras,
  • and addstrut which is a boolean key, i.e. to be used as addstrut=true, or addstrut alone where =true is omitted, or addstrut=false.

This last key is specific to \sphinxbox and it means to add a \strut so that heights and depths are equalized across various instances on the same line with varying contents. The default is addstrut=false.

IMPORTANT:

Perhaps the default will turn into addstrut=true at 7.0.0 depending on feedback until then.


The combination addstrut, padding-bottom=0pt, padding-top=1pt is often satisfactory.

Refer to Additional CSS-like 'sphinxsetup' keys for important syntax information regarding the other keys. The default configuration uses no shadow, a border-width of \fboxrule, a padding of \fboxsep, circular corners with radii \fboxsep and background and border colors as for the default rendering of code-blocks.

When a \sphinxbox usage is nested within another one, it will ignore the options of the outer one: it first resets all options to their default state as they were prior to applying the outer box options, then it applies its own specific ones.

One can modify these defaults via the command \sphinxboxsetup{key=value,...}. The effect is cumulative, if one uses this command multiple times. Here the options are a mandatory argument so are within curly braces, not square brackets.

Here is some example of use:

latex_elements = {

'preamble': r''' % modify globally the defaults \sphinxboxsetup{border-width=2pt,%
border-radius=4pt,%
background-TeXcolor=yellow!20} % configure some styling element with some extra specific options: \protected\def\sphinxkeyboard#1{\sphinxbox[border-TeXcolor=green]{\sphinxcode{#1}}} ''', }


A utility \newsphinxbox is provided to create a new boxing macro, say \foo which will act exactly like \sphinxbox but with a given extra configuration:

% the specific options to \foo are within brackets
\newsphinxbox[border-radius=0pt, box-shadow=2pt 2pt]{\foo}
% then use this \foo, possibly with some extra options still:
\protected\def\sphinxguilabel#1{\foo{#1}}
\protected\def\sphinxmenuselection#1{\foo[box-shadow-TeXcolor=gray]{#1}}


Boxes rendered with \foo obey as the ones using directly \sphinxbox the current configuration as set possibly mid-way in document via \sphinxboxsetup (from a raw LaTeX mark-up), the only difference is that they have an initial additional set of default extras.

In the above examples, you can probably use \renewcommand syntax if you prefer it to \protected\def (with [1] in place of #1 then).

Environments

  • A figure may have an optional legend with arbitrary body elements: they are rendered in a sphinxlegend environment. The default definition issues \small, and ends with \par.

    Added in version 1.5.6: Formerly, the \small was hardcoded in LaTeX writer and the ending \par was lacking.

  • Environments associated with admonitions:
  • sphinxnote,
  • sphinxhint,
  • sphinximportant,
  • sphinxtip,
  • sphinxwarning,
  • sphinxcaution,
  • sphinxattention,
  • sphinxdanger,
  • sphinxerror.

They may be \renewenvironment 'd individually, and must then be defined with one argument (it is the heading of the notice, for example Warning: for warning directive, if English is the document language). Their default definitions use either the sphinxheavybox (for the last 5 ones) or the sphinxlightbox environments, configured to use the parameters (colors, border thickness) specific to each type, which can be set via 'sphinxsetup' string.

Changed in version 1.5: Use of public environment names, separate customizability of the parameters, such as noteBorderColor, noteborder, warningBgColor, warningBorderColor, warningborder, ...

  • Environment for the seealso directive: sphinxseealso. It takes one argument which will be the localized string See also followed with a colon.

    Added in version 6.1.0.

    Changed in version 6.2.0: Colon made part of the mark-up rather than being inserted by the environment for coherence with how admonitions are handled generally.

  • The contents directive (with :local: option) and the topic directive are implemented by environment sphinxShadowBox.

    Added in version 1.4.2: Former code refactored into an environment allowing page breaks.

    Changed in version 1.5: Options shadowsep, shadowsize, shadowrule.

  • The literal blocks (via :: or code-block), are implemented using sphinxVerbatim environment which is a wrapper of Verbatim environment from package fancyvrb.sty. It adds the handling of the top caption and the wrapping of long lines, and a frame which allows page breaks. Inside tables the used environment is sphinxVerbatimintable (it does not draw a frame, but allows a caption).

    Changed in version 1.5: Verbatim keeps exact same meaning as in fancyvrb.sty (also under the name OriginalVerbatim); sphinxVerbatimintable is used inside tables.

    Added in version 1.5: Options verbatimwithframe, verbatimwrapslines, verbatimsep, verbatimborder.

    Added in version 1.6.6: Support for :emphasize-lines: option

    Added in version 1.6.6: Easier customizability of the formatting via exposed to user LaTeX macros such as \sphinxVerbatimHighlightLine.

  • The bibliography uses sphinxthebibliography and the Python Module index as well as the general index both use sphinxtheindex; these environments are wrappers of the thebibliography and respectively theindex environments as provided by the document class (or packages).

    Changed in version 1.5: Formerly, the original environments were modified by Sphinx.


Miscellany

  • Every text paragraph in document body starts with \sphinxAtStartPar. Currently, this is used to insert a zero width horizontal skip which is a trick to allow TeX hyphenation of the first word of a paragraph in a narrow context (like a table cell). For 'lualatex' which does not need the trick, the \sphinxAtStartPar does nothing.

    Added in version 3.5.0.

  • The section, subsection, ... headings are set using titlesec's \titleformat command.
  • For the 'manual' docclass, the chapter headings can be customized using fncychap's commands \ChNameVar, \ChNumVar, \ChTitleVar. File sphinx.sty has custom re-definitions in case of fncychap option Bjarne.

    Changed in version 1.5: Formerly, use of fncychap with other styles than Bjarne was dysfunctional.


Docutils container directives are supported in LaTeX output: to let a container class with name foo influence the final PDF via LaTeX, it is only needed to define in the preamble an environment sphinxclassfoo. A simple example would be:

\newenvironment{sphinxclassred}{\color{red}}{}


Currently the class names must contain only ascii characters and avoid characters special to LaTeX such as \.

Added in version 4.1.0.


HINT:

As an experimental feature, Sphinx can use user-defined template file for LaTeX source if you have a file named _templates/latex.tex_t in your project.

Additional files longtable.tex_t, tabulary.tex_t and tabular.tex_t can be added to _templates/ to configure some aspects of table rendering (such as the caption position).

Added in version 1.6: currently all template variables are unstable and undocumented.



Sphinx Extensions API

Since many projects will need special features in their documentation, Sphinx is designed to be extensible on several levels.

Here are a few things you can do in an extension:

  • Add new builders to support new output formats or actions on the parsed documents.
  • Register custom reStructuredText roles and directives, extending the markup using the Docutils markup API.
  • Add custom code to so-called "hook points" at strategic places throughout the build process, allowing you to register a hook and run specialized code. For example, see the Sphinx core events.

An extension is simply a Python module with a setup() function. A user activates the extension by placing the extension's module name (or a sub-module) in their extensions configuration value.

When sphinx-build is executed, Sphinx will attempt to import each module that is listed, and execute yourmodule.setup(app). This function is used to prepare the extension (e.g., by executing Python code), linking resources that Sphinx uses in the build process (like CSS or HTML files), and notifying Sphinx of everything the extension offers (such as directive or role definitions). The app argument is an instance of Sphinx and gives you control over most aspects of the Sphinx build.

NOTE:

The configuration file itself can be treated as an extension if it contains a setup() function. All other extensions to load must be listed in the extensions configuration value.


The rest of this page describes some high-level aspects of developing extensions and various parts of Sphinx's behavior that you can control. For some examples of how extensions can be built and used to control different parts of Sphinx, see the Extension tutorials.

Important objects

There are several key objects whose API you will use while writing an extension. These are:

The application object (usually called app) is an instance of Sphinx. It controls most high-level functionality, such as the setup of extensions, event dispatching and producing output (logging).

If you have the environment object, the application is available as env.app.

Environment
The build environment object (usually called env) is an instance of BuildEnvironment. It is responsible for parsing the source documents, stores all metadata about the document collection and is serialized to disk after each build.

Its API provides methods to do with access to metadata, resolving references, etc. It can also be used by extensions to cache information that should persist for incremental rebuilds.

If you have the application or builder object, the environment is available as app.env or builder.env.

The builder object (usually called builder) is an instance of a specific subclass of Builder. Each builder class knows how to convert the parsed documents into an output format, or otherwise process them (e.g. check external links).

If you have the application object, the builder is available as app.builder.

The config object (usually called config) provides the values of configuration values set in conf.py as attributes. It is an instance of Config.

The config is available as app.config or env.config.


To see an example of use of these objects, refer to Extension tutorials.

Build Phases

One thing that is vital in order to understand extension mechanisms is the way in which a Sphinx project is built: this works in several phases.

Phase 0: Initialization

In this phase, almost nothing of interest to us happens. The source directory is searched for source files, and extensions are initialized. Should a stored build environment exist, it is loaded, otherwise a new one is created.

Phase 1: Reading

In Phase 1, all source files (and on subsequent builds, those that are new or changed) are read and parsed. This is the phase where directives and roles are encountered by docutils, and the corresponding code is executed. The output of this phase is a doctree for each source file; that is a tree of docutils nodes. For document elements that aren't fully known until all existing files are read, temporary nodes are created.

There are nodes provided by docutils, which are documented in the docutils documentation. Additional nodes are provided by Sphinx and documented here.

During reading, the build environment is updated with all meta- and cross reference data of the read documents, such as labels, the names of headings, described Python objects and index entries. This will later be used to replace the temporary nodes.

The parsed doctrees are stored on the disk, because it is not possible to hold all of them in memory.

Phase 2: Consistency checks

Some checking is done to ensure no surprises in the built documents.

Phase 3: Resolving

Now that the metadata and cross-reference data of all existing documents is known, all temporary nodes are replaced by nodes that can be converted into output using components called transforms. For example, links are created for object references that exist, and simple literal nodes are created for those that don't.

Phase 4: Writing

This phase converts the resolved doctrees to the desired output format, such as HTML or LaTeX. This happens via a so-called docutils writer that visits the individual nodes of each doctree and produces some output in the process.

NOTE:

Some builders deviate from this general build plan, for example, the builder that checks external links does not need anything more than the parsed doctrees and therefore does not have phases 2--4.


To see an example of application, refer to Developing a "TODO" extension.

Extension metadata

Added in version 1.3.

The setup() function can return a dictionary. This is treated by Sphinx as metadata of the extension. Metadata keys currently recognized are:

  • 'version': a string that identifies the extension version. It is used for extension version requirement checking (see needs_extensions) and informational purposes. If not given, "unknown version" is substituted.
  • 'env_version': an integer that identifies the version of env data structure if the extension stores any data to environment. It is used to detect the data structure has been changed from last build. The extensions have to increment the version when data structure has changed. If not given, Sphinx considers the extension does not stores any data to environment.
  • 'parallel_read_safe': a boolean that specifies if parallel reading of source files can be used when the extension is loaded. It defaults to False, i.e. you have to explicitly specify your extension to be parallel-read-safe after checking that it is.

    NOTE:

The parallel-read-safe extension must satisfy the following conditions:
  • The core logic of the extension is parallelly executable during the reading phase.
  • It has event handlers for env-merge-info and env-purge-doc events if it stores data to the build environment object (env) during the reading phase.



'parallel_write_safe': a boolean that specifies if parallel writing of output files can be used when the extension is loaded. Since extensions usually don't negatively influence the process, this defaults to True.

NOTE:

The parallel-write-safe extension must satisfy the following conditions:
The core logic of the extension is parallelly executable during the writing phase.




APIs used for writing extensions

These sections provide a more complete description of the tools at your disposal when developing Sphinx extensions. Some are core to Sphinx (such as the Application API) while others trigger specific behavior (such as the i18n API)

Application API

Each Sphinx extension is a Python module with at least a setup() function. This function is called at initialization time with one argument, the application object representing the Sphinx process.

class sphinx.application.Sphinx
This application object has the public API described in the following.

Extension setup

These methods are usually called in an extension's setup() function.

Examples of using the Sphinx extension API can be seen in the sphinx.ext package.

Import and setup a Sphinx extension module.

Load the extension given by the module name. Use this if your extension needs the features provided by another extension. No-op if called twice.


Check the Sphinx version if requested.

Compare version with the version of the running Sphinx, and abort the build when it is too old.

version -- The required version in the form of major.minor or (major, minor).

Added in version 1.0.

Changed in version 7.1: Type of version now allows (major, minor) form.


Register callback to be called when event is emitted.

For details on available core events and the arguments of callback functions, please see Sphinx core events.

  • event -- The name of target event
  • callback -- Callback function for the event
  • priority -- The priority of the callback. The callbacks will be invoked in order of priority (ascending).

A listener ID. It can be used for disconnect().

Changed in version 3.0: Support priority


Unregister callback by listener_id.
listener_id -- A listener_id that connect() returns


Register a new builder.
  • builder -- A builder class
  • override -- If true, install the builder forcedly even if another builder is already installed as the same name


Changed in version 1.8: Add override keyword.


Register a configuration value.

This is necessary for Sphinx to recognize new values and set default values accordingly.

  • name -- The name of the configuration value. It is recommended to be prefixed with the extension name (ex. html_logo, epub_title)
  • default -- The default value of the configuration.
  • rebuild --

    The condition of rebuild. It must be one of those values:

  • 'env' if a change in the setting only takes effect when a document is parsed -- this means that the whole environment must be rebuilt.
  • 'html' if a change in the setting needs a full rebuild of HTML documents.
  • '' if a change in the setting will not need any special rebuild.

types -- The type of configuration value. A list of types can be specified. For example, [str] is used to describe a configuration that takes string value.


Changed in version 0.4: If the default value is a callable, it will be called with the config object as its argument in order to get the default value. This can be used to implement config values whose default depends on other values.

Changed in version 0.6: Changed rebuild from a simple boolean (equivalent to '' or 'env') to a string. However, booleans are still accepted and converted internally.


Register an event called name.

This is needed to be able to emit it.

name -- The name of the event


<