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:
o Output formats: HTML (including Windows HTML Help), LaTeX (for
printable PDF versions), ePub, Texinfo, manual pages, plain text
o Extensive cross-references: semantic markup and automatic links for
functions, classes, citations, glossary terms and similar pieces of
information
o Hierarchical structure: easy definition of a document tree, with
automatic links to siblings, parents and children
o Automatic indices: general index as well as a language-specific
module indices
o Code handling: automatic highlighting using the Pygments highlighter
o 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.
o Themes: modify the look and feel of outputs via creating themes, and
reuse many third-party themes.
o 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.
How do I generate PDF documents?
make latexpdf runs the LaTeX builder and readily invokes the
pdfTeX toolchain for you.
Todo
Move this whole section into a guide on rST or directives
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:
enumerate(sequence[, start=0])
Return an iterator that yields tuples of an index and an item of
the sequence. (And so on.)
The argument of the directive is the signature of the object you
describe, the content is the documentation for it. Multiple
signatures can be given, each in its own line.
The Python domain also happens to be the default domain, so you
don't need to prefix the markup with the domain name.
.. function:: enumerate(sequence[, start=0])
...
does the same job if you keep the default setting for the
default domain.
There are several more directives for documenting other types of
Python objects, for example py:class or py:method. There is
also a cross-referencing role for each of these object types.
This markup will create a link to the documentation of
enumerate().
The :py:func:`enumerate` function can be used for ...
And here is the proof: A link to enumerate().
Again, the py: can be left out if the Python domain is the
default one. It doesn't matter which file contains the actual
documentation for enumerate(); Sphinx will find it and create a
link to it.
Each domain will have special rules for how the signatures can
look like, and make the formatted output look pretty, or add
specific features like links to parameter types, e.g. in the
C/C++ domains.
[image: more info] [image]
See Domains for all the available domains and their
directives/roles.
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
o Other extensions:
o Static files
o Selecting a theme
o Templating
o Using extensions
o 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
o Overview
o Linux
o macOS
o Windows
o Installation from PyPI
o Docker
o 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:
o sphinxdoc/sphinx
o 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 .
$ pip install git+https://github.com/sphinx-doc/sphinx
You can also download a snapshot of the Git repo in
either tar.gz or zip format. Once downloaded and
extracted, these can be installed with pip as above.
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:
o > Separate source and build directories (y/n) [n]: Write "y" (without
quotes) and press Enter.
o > Project name: Write "Lumache" (without quotes) and press Enter.
o > Author name(s): Write "Graziella" (without quotes) and press Enter.
o > Project release []: Write "0.1" (without quotes) and press Enter.
o > Project language [en]: Leave it empty (the default, English) and
press Enter.
After the last question, you will see the new docs
directory with the following content.
docs
>>> build
>>> make.bat
>>> Makefile
>>> source
>>> conf.py
>>> index.rst
>>> _static
>>> _templates
The purpose of each of these files is:
build/ An empty directory (for now) that will hold the rendered
documentation.
make.bat and Makefile
Convenience scripts to simplify some common Sphinx operations,
such as rendering the content.
source/conf.py
A Python script holding the configuration of the Sphinx project.
It contains the project name and release you specified to
sphinx-quickstart, as well as some extra configuration keys.
source/index.rst
The root document of the project, which serves as welcome page
and contains the root of the "table of contents tree" (or
toctree).
Thanks to this bootstrapping step, you already have
everything needed to render the documentation as HTML for
the first time. To do that, run this command:
(.venv) $ sphinx-build -M html docs/source/ docs/build/
And finally, open docs/build/html/index.html in your
browser. You should see something like this:
[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 `_ and offers a *simple* and
*intuitive* API.
.. note::
This project is under active development.
This showcases several features of the reStructuredText
syntax, including:
o a section header using === for the underline,
o two examples of Inline markup: **strong emphasis** (typically bold)
and *emphasis* (typically italics),
o an inline external link,
o 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 ` 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
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:
o Sphinx parsed the argument of the .. py:function directive and
highlighted the module, the function name, and the parameters
appropriately.
o 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
o Fortran,
o Julia, or
o PHP.
For example, to document a C++ type definition, you would
use the built-in cpp:type directive, as follows:
.. cpp:type:: std::vector CustomList
A typedef-like declaration of a type.
Which would give the following result:
typedef std::vector CustomList
A typedef-like declaration of a type.
All such directives then generate references that can be
cross-referenced by using the corresponding role. For
example, to reference the previous type definition, you
can use the cpp:type role as follows:
Cross reference to :cpp:type:`CustomList`.
Which would produce a hyperlink to the previous
definition: CustomList.
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:
o 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).
o 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
Read the Docs is an online service specialized in hosting
technical documentation written in Sphinx, as well as MkDocs.
They have a number of extra features, such as versioned
documentation, traffic and search analytics, custom domains,
user-defined redirects, and more.
GitHub Pages
GitHub Pages is a simple static web hosting tightly integrated
with GitHub: static HTML is served from one of the branches of a
project, and usually sources are stored in another branch so
that the output can be updated every time the sources change
(for example using GitHub Actions). It is free to use and
supports custom domains.
GitLab Pages
GitLab Pages is a similar concept to GitHub Pages, integrated
with GitLab and usually automated with GitLab CI instead.
Netlify
Netlify is a sophisticated hosting for static sites enhanced by
client-side web technologies like JavaScript (so-called
"Jamstack"). They offer support for headless content management
systems and serverless computing.
Your own server
You can always use your own web server to host Sphinx HTML
documentation. It is the option that gives more flexibility,
but also more complexity.
All these options have zero cost, with the option of
paying for extra features.
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:
o Follow this tutorial to install Git on your machine.
o 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
o one asterisk: *text* for emphasis (italics),
o two asterisks: **text** for strong emphasis (boldface), and
o 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:
o it may not be nested,
o content may not start or end with whitespace: * text* is wrong,
o 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:
o field lists (ref, with caveats noted in Field Lists)
o option lists (ref)
o quoted literal blocks (ref)
o 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:
o If it occurs as a paragraph of its own, that paragraph is completely
left out of the document.
o If it is preceded by whitespace, the marker is removed.
o 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.
Hyperlinks
External links
Use `Link text `_ 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 links
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:
o # with overline, for parts
o * with overline, for chapters
o = for sections
o - for subsections
o ^ for subsubsections
o " 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:
o emphasis -- equivalent of *emphasis*
o strong -- equivalent of **strong**
o literal -- equivalent of ``literal``
o subscript -- subscript text
o superscript -- superscript text
o 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:
o Admonitions: attention, caution, danger, error, hint, important,
note, tip, warning and the generic admonition. (Most themes style
only "note" and "warning" specially.)
o Images:
o image (see also Images below)
o figure (an image with caption and optional legend)
o Additional body elements:
o contents (a local, i.e. for the current file only, table of
contents)
o container (a container with a custom class, useful to generate an
outer
in HTML)
o rubric (a heading without relation to the document sectioning)
o topic, sidebar (special highlighted body elements)
o parsed-literal (literal block that supports inline markup)
o epigraph (a block quote with optional attribution line)
o highlights, pull-quote (block quotes with their own class
attribute)
o compound (a compound paragraph)
o Special tables:
o table (a table with title)
o csv-table (a table generated from comma-separated values)
o list-table (a table generated from a list of lists)
o Special directives:
o raw (include raw target-format markup)
o 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
o 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.
o HTML specifics:
o meta (generation of HTML tags, see also HTML Metadata below)
o title (override document title)
o Influencing markup:
o default-role (set a new default role)
o 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:
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:
o pleasefindthiskey, pleasefindthiskeytoo to English builds;
o bittediesenkeyfinden to German builds;
o 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:
o 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.
o 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:
o any
o doc
o download
o envvar
o keyword
o numref
o option (and the deprecated cmdoption)
o ref
o term
o 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 ` 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:
o 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.
o 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
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:
o 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.
o 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:
o Do not use the colon : for HTML based formats. Links to other
parts may not work.
o 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 `_
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:
o using reST doctest blocks;
o using reST literal blocks, optionally in combination with the
highlight directive;
o using the code-block directive;
o 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:
o none (no highlighting)
o default (similar to python3 but with a fallback to none without
warning highlighting fails; the default when highlight_language isn't
set)
o guess (let Pygments guess the lexer based on contents, only works
with certain well-recognizable languages)
o python
o rest
o c
o ... 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 ` 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
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
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
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
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::
This directive contains one or more index entries. Each entry
consists of a type and a value, separated by a colon.
For example:
.. index::
single: execution; context
pair: module; __main__
pair: module; sys
triple: module; search; path
seealso: scope
The execution context
---------------------
...
This directive contains five entries, which
will be converted to entries in the generated
index which link to the exact location of the
index statement (or, in case of offline media,
the corresponding page number).
Since index directives generate cross-reference
targets at their location in the source, it
makes sense to put them before the thing they
refer to -- e.g. a heading, as in the example
above.
The possible entry types are:
single Creates a single index entry. Can be made a sub-entry by
separating the sub-entry text with a semicolon (this
notation is also used below to describe what entries are
created). Examples:
.. index:: single: execution
single: execution; context
o single: execution creates an index entry labelled
execution.
o single: execution; context creates an sub-entry of
execution labelled context.
pair A shortcut to create two index entries. The pair of
values must be separated by a semicolon. Example:
.. index:: pair: loop; statement
This would create two index entries;
loop; statement and statement; loop.
triple A shortcut to create three index entries. All three
values must be separated by a semicolon. Example:
.. index:: triple: module; search; path
This would create three index entries;
module; search path, search; path,
module, and path; module search.
see A shortcut to create an index entry that refers to
another entry. Example:
.. index:: see: entry; other
This would create an index entry
referring from entry to other (i.e.
'entry': See 'other').
seealso
Like see, but inserts 'see also' instead of 'see'.
module, keyword, operator, object, exception, statement, builtin
These deprecated shortcuts all create two index entries.
For example, module: hashlib creates the entries module;
hashlib and hashlib; module.
Deprecated since version 1.0: These Python-specific entry
types are deprecated.
Changed in version 7.1: Removal version set to Sphinx
9.0. Using these entry types will now emit warnings with
the index category.
You can mark up "main" index entries by
prefixing them with an exclamation mark. The
references to "main" entries are emphasized in
the generated index. For example, if two pages
contain
.. index:: Python
and one page contains
.. index:: ! Python
then the backlink to the latter page is
emphasized among the three backlinks.
For index directives containing only "single"
entries, there is a shorthand notation:
.. index:: BNF, grammar, syntax, notation
This creates four index entries.
Changed in version 1.1: Added see and seealso
types, as well as marking main entries.
options
:name: a label for hyperlink (text)
Define implicit target name that can be referenced by
using ref. For example:
.. index:: Python
:name: py-index
Added in version 3.0.
:index:
While the index directive is a block-level markup and links to
the beginning of the next paragraph, there is also a
corresponding role that sets the link target directly where it
is used.
The content of the role can be a simple phrase, which is then
kept in the text and used as an index entry. It can also be a
combination of text and index entry, styled like with explicit
targets of cross-references. In that case, the "target" part
can be a full entry as described for the directive above. For
example:
This is a normal reST :index:`paragraph` that contains several
:index:`index entries `.
Added in version 1.1.
Including content based on tags
.. only::
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
o grid table syntax (ref),
o simple table syntax (ref),
o csv-table syntax,
o 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:
o 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}).
o 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 "), 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:
tocdepth
The maximum depth for a table of contents of this file.
:tocdepth: 2
NOTE:
This metadata effects to the depth of local toctree. But it
does not effect to the depth of global toctree. So this
would not be change the sidebar of some themes which uses
global one.
Added in version 0.4.
nocomments
If set, the web application won't display a comment form for a
page generated from this source file.
:nocomments:
orphan If set, warnings about this file not being included in any
toctree will be suppressed.
:orphan:
Added in version 1.0.
nosearch
If set, full text search for this file is disabled.
:nosearch:
NOTE:
object search is still available even if nosearch option is
set.
Added in version 3.0.
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:
o You may supply an explicit title and reference target, like in reST
direct hyperlinks: :role:`title ` will refer to target, but
the link text will be title.
o If you prefix the content with !, no reference/hyperlink will be
created.
o 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.
o 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.
o 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:
o Python
o C
o C++
o JavaScript
o 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:
o 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.
o 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 `.
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 `), 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// 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) `), 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:
o If not otherwise documented, values must be strings, and their
default is the empty string.
o 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.
o Remember that document names use / as the path separator and don't
contain the file name extension.
o Since conf.py is read as a Python file, the usual rules apply for
encodings and Unicode support.
o 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.
o 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
project
The documented project's name.
author The author name(s) of the document. The default value is
'unknown'.
copyright
A copyright statement in the style '2008, Author Name'.
Changed in version 7.1: The value may now be a sequence of
copyright statements in the above form, which will be displayed
each to their own line.
project_copyright
An alias of copyright.
Added in version 3.5.
version
The major project version, used as the replacement for
|version|. For example, for the Python documentation, this may
be something like 2.6.
release
The full project version, used as the replacement for |release|
and e.g. in the HTML templates. For example, for the Python
documentation, this may be something like 2.6.0rc1.
If you don't need the separation provided between version and
release, just set them both to the same value.
General configuration
extensions
A list of strings that are module names of extensions. These can
be extensions coming with Sphinx (named sphinx.ext.*) or custom
ones.
Note that you can extend sys.path within the conf file if your
extensions live in another directory -- but make sure you use
absolute paths. If your extension path is relative to the
configuration directory, use os.path.abspath() like so:
import sys, os
sys.path.append(os.path.abspath('sphinxext'))
extensions = ['extname']
That way, you can load an extension called
extname from the subdirectory sphinxext.
The configuration file itself can be an
extension; for that, you only need to provide a
setup() function in it.
source_suffix
The file extensions of source files. Sphinx considers the files
with this suffix as sources. The value can be a dictionary
mapping file extensions to file types. For example:
source_suffix = {
'.rst': 'restructuredtext',
'.txt': 'restructuredtext',
'.md': 'markdown',
}
By default, Sphinx only supports
'restructuredtext' file type. You can add a
new file type using source parser extensions.
Please read a document of the extension to know
which file type the extension supports.
The value may also be a list of file
extensions: then Sphinx will consider that they
all map to the 'restructuredtext' file type.
Default is {'.rst': 'restructuredtext'}.
NOTE:
file extensions have to start with a dot (e.g. .rst).
Changed in version 1.3: Can now be a list of
extensions.
Changed in version 1.8: Support file type
mapping
source_encoding
The encoding of all reST source files. The recommended
encoding, and the default value, is 'utf-8-sig'.
Added in version 0.5: Previously, Sphinx accepted only UTF-8
encoded sources.
source_parsers
If given, a dictionary of parser classes for different source
suffices. The keys are the suffix, the values can be either a
class or a string giving a fully-qualified name of a parser
class. The parser class can be either docutils.parsers.Parser
or sphinx.parsers.Parser. Files with a suffix that is not in
the dictionary will be parsed with the default reStructuredText
parser.
For example:
source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
NOTE:
Refer to Markdown for more information on using Markdown with
Sphinx.
Added in version 1.3.
Deprecated since version 1.8: Now Sphinx
provides an API Sphinx.add_source_parser() to
register a source parser. Please use it
instead.
master_doc
Same as root_doc.
Changed in version 4.0: Renamed master_doc to root_doc.
root_doc
The document name of the "root" document, that is, the document
that contains the root toctree directive. Default is 'index'.
Changed in version 2.0: The default is changed to 'index' from
'contents'.
Changed in version 4.0: Renamed root_doc from master_doc.
exclude_patterns
A list of glob-style patterns [1] that should be excluded when
looking for source files. They are matched against the source
file names relative to the source directory, using slashes as
directory separators on all platforms.
Example patterns:
o 'library/xml.rst' -- ignores the library/xml.rst file
o 'library/xml' -- ignores the library/xml directory
o 'library/xml*' -- ignores all files and directories starting
with library/xml
o '**/.svn' -- ignores all .svn directories
exclude_patterns is also consulted when looking
for static files in html_static_path and
html_extra_path.
Added in version 1.0.
include_patterns
A list of glob-style patterns [1] that are used to find source
files. They are matched against the source file names relative
to the source directory, using slashes as directory separators
on all platforms. The default is **, meaning that all files are
recursively included from the source directory.
exclude_patterns has priority over include_patterns.
Example patterns:
o '**' -- all files in the source directory and subdirectories,
recursively
o 'library/xml' -- just the library/xml directory
o 'library/xml*' -- all files and directories starting with
library/xml
o '**/doc' -- all doc directories (this might be useful if
documentation is co-located with source files)
Added in version 5.1.
templates_path
A list of paths that contain extra templates (or templates that
overwrite builtin/theme-specific templates). Relative paths are
taken as relative to the configuration directory.
Changed in version 1.3: As these files are not meant to be
built, they are automatically added to exclude_patterns.
template_bridge
A string with the fully-qualified name of a callable (or simply
a class) that returns an instance of TemplateBridge. This
instance is then used to render HTML documents, and possibly the
output of other builders (currently the changes builder). (Note
that the template bridge must be made theme-aware if HTML themes
are to be used.)
rst_epilog
A string of reStructuredText that will be included at the end of
every source file that is read. This is a possible place to add
substitutions that should be available in every file (another
being rst_prolog). An example:
rst_epilog = """
.. |psf| replace:: Python Software Foundation
"""
Added in version 0.6.
rst_prolog
A string of reStructuredText that will be included at the
beginning of every source file that is read. This is a possible
place to add substitutions that should be available in every
file (another being rst_epilog). An example:
rst_prolog = """
.. |psf| replace:: Python Software Foundation
"""
Added in version 1.0.
primary_domain
The name of the default domain. Can also be None to disable a
default domain. The default is 'py'. Those objects in other
domains (whether the domain name is given explicitly, or
selected by a default-domain directive) will have the domain
name explicitly prepended when named (e.g., when the default
domain is C, Python functions will be named "Python function",
not just "function").
Added in version 1.0.
default_role
The name of a reST role (builtin or Sphinx extension) to use as
the default role, that is, for text marked up `like this`. This
can be set to 'py:obj' to make `filter` a cross-reference to the
Python function "filter". The default is None, which doesn't
reassign the default role.
The default role can always be set within individual documents
using the standard reST default-role directive.
Added in version 0.4.
keep_warnings
If true, keep warnings as "system message" paragraphs in the
built documents. Regardless of this setting, warnings are
always written to the standard error stream when sphinx-build is
run.
The default is False, the pre-0.5 behavior was to always keep
them.
Added in version 0.5.
show_warning_types
If True, the type of each warning is added as a suffix to the
warning message, e.g., WARNING: [...] [index] or WARNING: [...]
[toc.circular]. The default is False.
Added in version 7.3.0.
suppress_warnings
A list of warning types to suppress arbitrary warning messages.
Sphinx core supports following warning types:
o app.add_node
o app.add_directive
o app.add_role
o app.add_generic_role
o app.add_source_parser
o config.cache
o download.not_readable
o epub.unknown_project_files
o epub.duplicated_toc_entry
o i18n.inconsistent_references
o index
o image.not_readable
o ref.term
o ref.ref
o ref.numref
o ref.keyword
o ref.option
o ref.citation
o ref.footnote
o ref.doc
o ref.python
o misc.highlighting_failure
o toc.circular
o toc.excluded
o toc.not_readable
o toc.secnum
Extensions can also define their own warning
types. Those defined by the first-party
sphinx.ext extensions are:
o autodoc
o autodoc.import_object
o autosectionlabel.
o autosummary
o 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.
Changed in version 3.3.0: Added
epub.duplicated_toc_entry
Changed in version 4.3: Added toc.excluded and
toc.not_readable
Added in version 4.5: Added
i18n.inconsistent_references
Added in version 7.1: Added index warning type.
Added in version 7.3: Added config.cache
warning type.
needs_sphinx
If set to a major.minor version string like '1.1', Sphinx will
compare it with its version and refuse to build if it is too
old. Default is no requirement.
Added in version 1.0.
Changed in version 1.4: also accepts micro version string
needs_extensions
This value can be a dictionary specifying version requirements
for extensions in extensions, e.g. needs_extensions =
{'sphinxcontrib.something': '1.5'}. The version strings should
be in the form major.minor. Requirements do not have to be
specified for all extensions, only for those you want to check.
This requires that the extension specifies its version to Sphinx
(see Sphinx Extensions API for how to do that).
Added in version 1.3.
manpages_url
A URL to cross-reference manpage roles. If this is defined to
https://manpages.debian.org/{path}, the :manpage:`man(1)` role
will link to . The patterns
available are:
o page - the manual page (man)
o section - the manual section (1)
o path - the original manual page and section specified (man(1))
This also supports manpages specified as man.1.
NOTE:
This currently affects only HTML writers but could be
expanded in the future.
Added in version 1.7.
nitpicky
If true, Sphinx will warn about all references where the target
cannot be found. Default is False. You can activate this mode
temporarily using the -n command-line switch.
Added in version 1.0.
nitpick_ignore
A set or list of (type, target) tuples (by default empty) that
should be ignored when generating warnings in "nitpicky mode".
Note that type should include the domain name if present.
Example entries would be ('py:func', 'int') or ('envvar',
'LD_LIBRARY_PATH').
Added in version 1.1.
Changed in version 6.2: Changed allowable container types to a
set, list, or tuple
nitpick_ignore_regex
An extended version of nitpick_ignore, which instead interprets
the type and target strings as regular expressions. Note, that
the regular expression must match the whole string (as if the ^
and $ markers were inserted).
For example, (r'py:.*', r'foo.*bar\.B.*') will ignore nitpicky
warnings for all python entities that start with 'foo' and have
'bar.B' in them, such as ('py:const',
'foo_package.bar.BAZ_VALUE') or ('py:class', 'food.bar.Barman').
Added in version 4.1.
Changed in version 6.2: Changed allowable container types to a
set, list, or tuple
numfig If true, figures, tables and code-blocks are automatically
numbered if they have a caption. The numref role is enabled.
Obeyed so far only by HTML and LaTeX builders. Default is False.
NOTE:
The LaTeX builder always assigns numbers whether this option
is enabled or not.
Added in version 1.3.
numfig_format
A dictionary mapping 'figure', 'table', 'code-block' and
'section' to strings that are used for format of figure numbers.
As a special character, %s will be replaced to figure number.
Default is to use 'Fig. %s' for 'figure', 'Table %s' for
'table', 'Listing %s' for 'code-block' and 'Section %s' for
'section'.
Added in version 1.3.
numfig_secnum_depth
o if set to 0, figures, tables and code-blocks are continuously
numbered starting at 1.
o 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.
o 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.)
o etc...
Added in version 1.3.
Changed in version 1.7: The LaTeX builder obeys
this setting (if numfig is set to True).
smartquotes
If true, the Docutils Smart Quotes transform, originally based
on SmartyPants (limited to English) and currently applying to
many languages, will be used to convert quotes and dashes to
typographically correct entities. Default: True.
Added in version 1.6.6: It replaces deprecated
html_use_smartypants. It applies by default to all builders
except man and text (see smartquotes_excludes.)
A docutils.conf file located in the configuration directory (or
a global ~/.docutils file) is obeyed unconditionally if it
deactivates smart quotes via the corresponding Docutils option.
But if it activates them, then smartquotes does prevail.
smartquotes_action
This string customizes the Smart Quotes transform. See the file
smartquotes.py at the Docutils repository for details. The
default 'qDe' educates normal quote characters ", ', em- and
en-Dashes ---, --, and ellipses ....
Added in version 1.6.6.
smartquotes_excludes
This is a dict whose default is:
{'languages': ['ja'], 'builders': ['man', 'text']}
Each entry gives a sufficient condition to
ignore the smartquotes setting and deactivate
the Smart Quotes transform. Accepted keys are
as above 'builders' or 'languages'. The values
are lists.
NOTE:
Currently, in case of invocation of make with multiple
targets, the first target name is the only one which is
tested against the 'builders' entry and it decides for all.
Also, a make text following make html needs to be issued in
the form make text O="-E" to force re-parsing of source
files, as the cached ones are already transformed. On the
other hand the issue does not arise with direct usage of
sphinx-build as it caches (in its default usage) the parsed
source files in per builder locations.
HINT:
An alternative way to effectively deactivate (or customize)
the smart quotes for a given builder, for example latex, is
to use make this way:
make latex O="-D smartquotes_action="
This can follow some make html with no
problem, in contrast to the situation from
the prior note.
Added in version 1.6.6.
user_agent
A User-Agent of Sphinx. It is used for a header on HTTP access
(ex. linkcheck, intersphinx and so on). Default is
"Sphinx/X.Y.Z requests/X.Y.Z python/X.Y.Z".
Added in version 2.3.
tls_verify
If true, Sphinx verifies server certifications. Default is
True.
Added in version 1.5.
tls_cacerts
A path to a certification file of CA or a path to directory
which contains the certificates. This also allows a dictionary
mapping hostname to the path to certificate file. The
certificates are used to verify server certifications.
Added in version 1.5.
TIP:
Sphinx uses requests as a HTTP library internally.
Therefore, Sphinx refers a certification file on the
directory pointed REQUESTS_CA_BUNDLE environment variable if
tls_cacerts not set.
today
today_fmt
These values determine how to format the current date, used as
the replacement for |today|.
o If you set today to a non-empty value, it is used.
o Otherwise, the current time is formatted using time.strftime()
and the format given in today_fmt.
The default is now today and a today_fmt of '%b
%d, %Y' (or, if translation is enabled with
language, an equivalent format for the selected
locale).
highlight_language
The default language to highlight source code in. The default
is 'default'. It is similar to 'python3'; it is mostly a
superset of 'python' but it fallbacks to 'none' without warning
if failed. 'python3' and other languages will emit warning if
failed.
The value should be a valid Pygments lexer name, see Showing
code examples for more details.
Added in version 0.5.
Changed in version 1.4: The default is now 'default'. If you
prefer Python 2 only highlighting, you can set it back to
'python'.
highlight_options
A dictionary that maps language names to options for the lexer
modules of Pygments. These are lexer-specific; for the options
understood by each, see the Pygments documentation.
Example:
highlight_options = {
'default': {'stripall': True},
'php': {'startinline': True},
}
A single dictionary of options are also
allowed. Then it is recognized as options to
the lexer specified by highlight_language:
# configuration for the ``highlight_language``
highlight_options = {'stripall': True}
Added in version 1.3.
Changed in version 3.5: Allow to configure
highlight options for multiple languages
pygments_style
The style name to use for Pygments highlighting of source code.
If not set, either the theme's default style or 'sphinx' is
selected for HTML output.
Changed in version 0.3: If the value is a fully-qualified name
of a custom Pygments style class, this is then used as custom
style.
maximum_signature_line_length
If a signature's length in characters exceeds the number set,
each parameter within the signature will be displayed on an
individual logical line.
When None (the default), there is no maximum length and the
entire signature will be displayed on a single logical line.
A 'logical line' is similar to a hard line break---builders or
themes may choose to 'soft wrap' a single logical line, and this
setting does not affect that behaviour.
Domains may provide options to suppress any hard wrapping on an
individual object directive, such as seen in the C, C++, and
Python domains (e.g. py:function:single-line-parameter-list).
Added in version 7.1.
add_function_parentheses
A boolean that decides whether parentheses are appended to
function and method role text (e.g. the content of
:func:`input`) to signify that the name is callable. Default is
True.
add_module_names
A boolean that decides whether module names are prepended to all
object names (for object types where a "module" of some kind is
defined), e.g. for py:function directives. Default is True.
toc_object_entries
Create table of contents entries for domain objects (e.g.
functions, classes, attributes, etc.). Default is True.
toc_object_entries_show_parents
A string that determines how domain objects (e.g. functions,
classes, attributes, etc.) are displayed in their table of
contents entry.
Use domain to allow the domain to determine the appropriate
number of parents to show. For example, the Python domain would
show Class.method() and function(), leaving out the module.
level of parents. This is the default setting.
Use hide to only show the name of the element without any
parents (i.e. method()).
Use all to show the fully-qualified name for the object (i.e.
module.Class.method()), displaying all parents.
Added in version 5.2.
show_authors
A boolean that decides whether codeauthor and sectionauthor
directives produce any output in the built files.
modindex_common_prefix
A list of prefixes that are ignored for sorting the Python
module index (e.g., if this is set to ['foo.'], then foo.bar is
shown under B, not F). This can be handy if you document a
project that consists of a single package. Works only for the
HTML builder currently. Default is [].
Added in version 0.6.
trim_footnote_reference_space
Trim spaces before footnote references that are necessary for
the reST parser to recognize the footnote, but do not look too
nice in the output.
Added in version 0.6.
trim_doctest_flags
If true, doctest flags (comments looking like # doctest: FLAG,
...) at the ends of lines and 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 .
strip_signature_backslash
Default is False. When backslash stripping is enabled then
every occurrence of \\ in a domain directive will be changed to
\, even within string literals. This was the behaviour before
version 3.0, and setting this variable to True will reinstate
that behaviour.
Added in version 3.0.
option_emphasise_placeholders
Default is False. When enabled, emphasise placeholders in
option directives. To display literal braces, escape with a
backslash (\{). For example, option_emphasise_placeholders=True
and .. option:: -foption={TYPE} would render with TYPE
emphasised.
Added in version 5.1.
Options for internationalization
These options influence Sphinx's Native Language Support. See the
documentation on Internationalization for details.
language
The code for the language the docs are written in. Any text
automatically generated by Sphinx will be in that language.
Also, Sphinx will try to substitute individual paragraphs from
your documents with the translation sets obtained from
locale_dirs. Sphinx will search language-specific figures named
by figure_language_filename (e.g. the German version of
myfigure.png will be myfigure.de.png by default setting) and
substitute them for original figures. In the LaTeX builder, a
suitable language will be selected as an option for the Babel
package. Default is 'en'.
Added in version 0.5.
Changed in version 1.4: Support figure substitution
Changed in version 5.0.
Currently supported languages by Sphinx are:
o ar -- Arabic
o bg -- Bulgarian
o bn -- Bengali
o ca -- Catalan
o cak -- Kaqchikel
o cs -- Czech
o cy -- Welsh
o da -- Danish
o de -- German
o el -- Greek
o en -- English (default)
o eo -- Esperanto
o es -- Spanish
o et -- Estonian
o eu -- Basque
o fa -- Iranian
o fi -- Finnish
o fr -- French
o he -- Hebrew
o hi -- Hindi
o hi_IN -- Hindi (India)
o hr -- Croatian
o hu -- Hungarian
o id -- Indonesian
o it -- Italian
o ja -- Japanese
o ko -- Korean
o lt -- Lithuanian
o lv -- Latvian
o mk -- Macedonian
o nb_NO -- Norwegian Bokmal
o ne -- Nepali
o nl -- Dutch
o pl -- Polish
o pt -- Portuguese
o pt_BR -- Brazilian Portuguese
o pt_PT -- European Portuguese
o ro -- Romanian
o ru -- Russian
o si -- Sinhala
o sk -- Slovak
o sl -- Slovenian
o sq -- Albanian
o sr -- Serbian
o sr@latin -- Serbian (Latin)
o sr_RS -- Serbian (Cyrillic)
o sv -- Swedish
o ta -- Tamil
o te -- Telugu
o tr -- Turkish
o uk_UA -- Ukrainian
o ur -- Urdu
o vi -- Vietnamese
o zh_CN -- Simplified Chinese
o zh_TW -- Traditional Chinese
locale_dirs
Added in version 0.5.
Directories in which to search for additional message catalogs
(see language), relative to the source directory. The
directories on this path are searched by the standard gettext
module.
Internal messages are fetched from a text domain of sphinx; so
if you add the directory ./locale to this setting, the message
catalogs (compiled from .po format using msgfmt) must be in
./locale/language/LC_MESSAGES/sphinx.mo. The text domain of
individual documents depends on gettext_compact.
The default is ['locales'].
NOTE:
The -v option for sphinx-build command is useful to check the
locale_dirs config works as expected. It emits debug
messages if message catalog directory not found.
Changed in version 1.5: Use locales directory
as a default value
gettext_allow_fuzzy_translations
If true, "fuzzy" messages in the message catalogs are used for
translation. The default is False.
Added in version 4.3.
gettext_compact
Added in version 1.1.
If true, a document's text domain is its docname if it is a
top-level project file and its very base directory otherwise.
If set to string, all document's text domain is this string,
making all documents use single text domain.
By default, the document markup/code.rst ends up in the markup
text domain. With this option set to False, it is markup/code.
Changed in version 3.3: The string value is now accepted.
gettext_uuid
If true, Sphinx generates uuid information for version tracking
in message catalogs. It is used for:
o Add uid line for each msgids in .pot files.
o Calculate similarity between new msgids and previously saved
old msgids. This calculation takes a long time.
If you want to accelerate the calculation, you
can use python-levenshtein 3rd-party package
written in C by using pip install
python-levenshtein.
The default is False.
Added in version 1.3.
gettext_location
If true, Sphinx generates location information for messages in
message catalogs.
The default is True.
Added in version 1.3.
gettext_auto_build
If true, Sphinx builds mo file for each translation catalog
files.
The default is True.
Added in version 1.3.
gettext_additional_targets
To specify names to enable gettext extracting and translation
applying for i18n additionally. You can specify below names:
Index index terms
Literal-block
literal blocks (:: annotation and code-block directive)
Doctest-block
doctest block
Raw raw content
Image image/figure uri
For example: gettext_additional_targets =
['literal-block', 'image'].
The default is [].
Added in version 1.3.
Changed in version 4.0: The alt text for image
is translated by default.
figure_language_filename
The filename format for language-specific figures. The default
value is {root}.{language}{ext}. It will be expanded to
dirname/filename.en.png from .. image:: dirname/filename.png.
The available format tokens are:
o {root} - the filename, including any path component, without
the file extension, e.g. dirname/filename
o {path} - the directory path component of the filename, with a
trailing slash if non-empty, e.g. dirname/
o {docpath} - the directory path component for the current
document, with a trailing slash if non-empty.
o {basename} - the filename without the directory path or file
extension components, e.g. filename
o {ext} - the file extension, e.g. .png
o {language} - the translation language, e.g. en
For example, setting this to
{path}{language}/{basename}{ext} will expand to
dirname/en/filename.png instead.
Added in version 1.4.
Changed in version 1.5: Added {path} and
{basename} tokens.
Changed in version 3.2: Added {docpath} token.
translation_progress_classes
Control which, if any, classes are added to indicate translation
progress. This setting would likely only be used by translators
of documentation, in order to quickly indicate translated and
untranslated content.
o True: add translated and untranslated classes to all nodes
with translatable content.
o translated: only add the translated class.
o untranslated: only add the untranslated class.
o 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.
math_number_all
Set this option to True if you want all displayed math to be
numbered. The default is False.
math_eqref_format
A string used for formatting the labels of references to
equations. The {number} place-holder stands for the equation
number.
Example: 'Eq.{number}' gets rendered as, for example, Eq.10.
math_numfig
If True, displayed math equations are numbered across pages when
numfig is enabled. The numfig_secnum_depth setting is
respected. The eq, not numref, role must be used to reference
equation numbers. Default is True.
Added in version 1.7.
Options for HTML output
These options influence HTML as well as HTML Help output, and other
builders that use Sphinx's HTMLWriter class.
html_theme
The "theme" that the HTML output should use. See the section
about theming. The default is 'alabaster'.
Added in version 0.6.
html_theme_options
A dictionary of options that influence the look and feel of the
selected theme. These are theme-specific. For the options
understood by the builtin themes, see this section.
Added in version 0.6.
html_theme_path
A list of paths that contain custom themes, either as
subdirectories or as zip files. Relative paths are taken as
relative to the configuration directory.
Added in version 0.6.
html_style
The style sheet to use for HTML pages. A file of that name must
exist either in Sphinx's static/ path, or in one of the custom
paths given in html_static_path. Default is the stylesheet
given by the selected theme. If you only want to add or
override a few things compared to the theme's stylesheet, use
CSS @import to import the theme's stylesheet.
html_title
The "title" for HTML documentation generated with Sphinx's own
templates. This is appended to the tag of individual
pages, and used in the navigation bar as the "topmost" element.
It defaults to ' v documentation'.
html_short_title
A shorter "title" for the HTML docs. This is used for links in
the header and in the HTML Help docs. If not given, it defaults
to the value of html_title.
Added in version 0.4.
html_baseurl
The base URL which points to the root of the HTML documentation.
It is used to indicate the location of document using The
Canonical Link Relation. Default: ''.
Added in version 1.8.
html_codeblock_linenos_style
The style of line numbers for code-blocks.
o 'table' -- display line numbers using
tag
o 'inline' -- display line numbers using tag (default)
Added in version 3.2.
Changed in version 4.0: It defaults to
'inline'.
Deprecated since version 4.0.
html_context
A dictionary of values to pass into the template engine's
context for all pages. Single values can also be put in this
dictionary using the -A command-line option of sphinx-build.
Added in version 0.5.
html_logo
If given, this must be the name of an image file (path relative
to the configuration directory) that is the logo of the docs, or
URL that points an image file for the logo. It is placed at the
top of the sidebar; its width should therefore not exceed 200
pixels. Default: None.
Added in version 0.4.1: The image file will be copied to the
_static directory of the output HTML, but only if the file does
not already exist there.
Changed in version 4.0: Also accepts the URL for the logo file.
html_favicon
If given, this must be the name of an image file (path relative
to the configuration directory) that is the favicon of the docs,
or URL that points an image file for the favicon. Modern
browsers use this as the icon for tabs, windows and bookmarks.
It should be a Windows-style icon file (.ico), which is 16x16 or
32x32 pixels large. Default: None.
Added in version 0.4: The image file will be copied to the
_static directory of the output HTML, but only if the file does
not already exist there.
Changed in version 4.0: Also accepts the URL for the favicon.
html_css_files
A list of CSS files. The entry must be a filename string or a
tuple containing the filename string and the attributes
dictionary. The filename must be relative to the
html_static_path, or a full URI with scheme like
https://example.org/style.css. The attributes is used for
attributes of tag. It defaults to an empty list.
Example:
html_css_files = ['custom.css',
'https://example.com/css/custom.css',
('print.css', {'media': 'print'})]
As a special attribute, priority can be set as
an integer to load the CSS file at an earlier
or lazier step. For more information, refer
Sphinx.add_css_file().
Added in version 1.8.
Changed in version 3.5: Support priority
attribute
html_js_files
A list of JavaScript filename. The entry must be a filename
string or a tuple containing the filename string and the
attributes dictionary. The filename must be relative to the
html_static_path, or a full URI with scheme like
https://example.org/script.js. The attributes is used for
attributes of
app.add_js_file('example.js', loading_method="async")
# =>
app.add_js_file(None, body="var myVariable = 'foo';")
# =>
priority range for JavaScript files
+---------+--------------------------------------+
|Priority | Main purpose in Sphinx |
+---------+--------------------------------------+
|200 | default priority for built-in |
| | JavaScript files |
+---------+--------------------------------------+
|500 | default priority for extensions |
+---------+--------------------------------------+
|800 | default priority for html_js_files |
+---------+--------------------------------------+
A JavaScript file can be added to the specific HTML page when an
extension calls this method on html-page-context event.
Added in version 0.5.
Changed in version 1.8: Renamed from app.add_javascript(). And it
allows keyword arguments as attributes of script tag.
Changed in version 3.5: Take priority argument. Allow to add a
JavaScript file to the specific page.
Changed in version 4.4: Take loading_method argument. Allow to change
the loading method of the JavaScript file.
Sphinx.add_css_file(filename: str, priority: int = 500, **kwargs: Any)
-> None
Register a stylesheet to include in the HTML output.
Parameters
o filename -- The name of a CSS file that the default
HTML template will include. It must be relative to the
HTML static path, or a full URI with scheme.
o priority -- Files are included in ascending order of
priority. If multiple CSS files have the same priority,
those files will be included in order of registration.
See list of "priority range for CSS files" below.
o kwargs -- Extra keyword arguments are included as
attributes of the tag.
Example:
app.add_css_file('custom.css')
# =>
app.add_css_file('print.css', media='print')
# =>
app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
# =>
priority range for CSS files
+---------+----------------------------------------+
|Priority | Main purpose in Sphinx |
+---------+----------------------------------------+
|200 | default priority for built-in CSS |
| | files |
+---------+----------------------------------------+
|500 | default priority for extensions |
+---------+----------------------------------------+
|800 | default priority for html_css_files |
+---------+----------------------------------------+
A CSS file can be added to the specific HTML page when an extension
calls this method on html-page-context event.
Added in version 1.0.
Changed in version 1.6: Optional alternate and/or title attributes can
be supplied with the arguments alternate (a Boolean) and title (a
string). The default is no title and alternate = False. For more
information, refer to the documentation.
Changed in version 1.8: Renamed from app.add_stylesheet(). And it
allows keyword arguments as attributes of link tag.
Changed in version 3.5: Take priority argument. Allow to add a CSS
file to the specific page.
Sphinx.add_latex_package(packagename: str, options: str | None = None,
after_hyperref: bool = False) -> None
Register a package to include in the LaTeX source code.
Add packagename to the list of packages that LaTeX source code
will include. If you provide options, it will be taken to the
usepackage declaration. If you set after_hyperref truthy, the
package will be loaded after hyperref package.
app.add_latex_package('mypackage')
# => \usepackage{mypackage}
app.add_latex_package('mypackage', 'foo,bar')
# => \usepackage[foo,bar]{mypackage}
Added in version 1.3.
Added in version 3.1:
after_hyperref option.
Sphinx.add_lexer(alias: str, lexer: type[Lexer]) -> None
Register a new lexer for source code.
Use lexer to highlight code blocks with the given language
alias.
Added in version 0.6.
Changed in version 2.1: Take a lexer class as an argument.
Changed in version 4.0: Removed support for lexer instances as
an argument.
Sphinx.add_autodocumenter(cls: Any, override: bool = False) -> None
Register a new documenter class for the autodoc extension.
Add cls as a new documenter class for the sphinx.ext.autodoc
extension. It must be a subclass of
sphinx.ext.autodoc.Documenter. This allows auto-documenting new
types of objects. See the source of the autodoc module for
examples on how to subclass Documenter.
If override is True, the given cls is forcedly installed even if
a documenter having the same name is already installed.
See Developing autodoc extension for IntEnum.
Added in version 0.6.
Changed in version 2.2: Add override keyword.
Sphinx.add_autodoc_attrgetter(typ: type, getter: Callable[[Any, str,
Any], Any]) -> None
Register a new getattr-like function for the autodoc extension.
Add getter, which must be a function with an interface
compatible to the getattr() builtin, as the autodoc attribute
getter for objects that are instances of typ. All cases where
autodoc needs to get an attribute of a type are then handled by
this function instead of getattr().
Added in version 0.6.
Sphinx.add_search_language(cls: Any) -> None
Register a new language for the HTML search index.
Add cls, which must be a subclass of
sphinx.search.SearchLanguage, as a support language for building
the HTML full-text search index. The class must have a lang
attribute that indicates the language it should be used for.
See html_search_language.
Added in version 1.1.
Sphinx.add_source_suffix(suffix: str, filetype: str, override: bool =
False) -> None
Register a suffix of source files.
Same as source_suffix. The users can override this using the
config setting.
Parameters
override -- If false, do not install it the same suffix
is already installed. If true, unconditionally install
the suffix.
Added in version 1.8.
Sphinx.add_source_parser(parser: type[Parser], override: bool = False)
-> None
Register a parser class.
Parameters
override -- If false, do not install it if another parser
is already installed for the same suffix. If true,
unconditionally install the parser.
Added in version 1.4.
Changed in version 1.8:
suffix argument is
deprecated. It only
accepts parser argument.
Use add_source_suffix()
API to register suffix
instead.
Changed in version 1.8:
Add override keyword.
Sphinx.add_env_collector(collector: type[EnvironmentCollector]) -> None
Register an environment collector class.
Refer to Environment Collector API.
Added in version 1.6.
Sphinx.add_html_theme(name: str, theme_path: str) -> None
Register a HTML Theme.
The name is a name of theme, and theme_path is a full path to
the theme (refs: Distribute your theme as a Python package).
Added in version 1.6.
Sphinx.add_html_math_renderer(name: str, inline_renderers:
tuple[Callable, Callable | None] | None = None, block_renderers:
tuple[Callable, Callable | None] | None = None) -> None
Register a math renderer for HTML.
The name is a name of math renderer. Both inline_renderers and
block_renderers are used as visitor functions for the HTML
writer: the former for inline math node (nodes.math), the latter
for block math node (nodes.math_block). Regarding visitor
functions, see add_node() for details.
Added in version 1.8.
Sphinx.add_message_catalog(catalog: str, locale_dir: str) -> None
Register a message catalog.
Parameters
o catalog -- The name of the catalog
o locale_dir -- The base path of the message catalog
For more details, see
sphinx.locale.get_translation().
Added in version 1.8.
Sphinx.is_parallel_allowed(typ: str) -> bool
Check whether parallel processing is allowed or not.
Parameters
typ -- A type of processing; 'read' or 'write'.
exception sphinx.application.ExtensionError
All these methods raise this exception if something went wrong
with the extension API.
Emitting events
class sphinx.application.Sphinx
emit(event: str, *args: Any, allowed_exceptions:
tuple[type[Exception], ...] = ()) -> list
Emit event and pass arguments to the callback functions.
Return the return values of all callbacks as a list. Do
not emit core Sphinx events in extensions!
Parameters
o event -- The name of event that will be emitted
o args -- The arguments for the event
o allowed_exceptions -- The list of exceptions
that are allowed in the callbacks
Changed in version
3.1: Added
allowed_exceptions
to specify
path-through
exceptions
emit_firstresult(event: str, *args: Any, allowed_exceptions:
tuple[type[Exception], ...] = ()) -> Any
Emit event and pass arguments to the callback functions.
Return the result of the first callback that doesn't
return None.
Parameters
o event -- The name of event that will be emitted
o args -- The arguments for the event
o allowed_exceptions -- The list of exceptions
that are allowed in the callbacks
Added in version
0.5.
Changed in version
3.1: Added
allowed_exceptions
to specify
path-through
exceptions
Sphinx runtime information
The application object also provides runtime information as attributes.
Sphinx.project
Target project. See Project.
Sphinx.srcdir
Source directory.
Sphinx.confdir
Directory containing conf.py.
Sphinx.doctreedir
Directory for storing pickled doctrees.
Sphinx.outdir
Directory for storing built document.
Sphinx core events
These events are known to the core. The arguments shown are given to
the registered event handlers. Use Sphinx.connect() in an extension's
setup function (note that conf.py can also have a setup function) to
connect handlers to the events. Example:
def source_read_handler(app, docname, source):
print('do something here...')
def setup(app):
app.connect('source-read', source_read_handler)
Below is an overview of each
event that happens during a
build. In the list below, we
include the event name, its
callback parameters, and the
input and output type for that
event:
1. event.config-inited(app,config)
2. event.builder-inited(app)
3. event.env-get-outdated(app, env, added, changed, removed)
4. event.env-before-read-docs(app, env, docnames)
for docname in docnames:
5. event.env-purge-doc(app, env, docname)
if doc changed and not removed:
6. source-read(app, docname, source)
7. run source parsers: text -> docutils.document
- parsers can be added with the app.add_source_parser() API
8. apply transforms based on priority: docutils.document -> docutils.document
- event.doctree-read(app, doctree) is called in the middle of transforms,
transforms come before/after this event depending on their priority.
9. event.env-merge-info(app, env, docnames, other)
- if running in parallel mode, this event will be emitted for each process
10. event.env-updated(app, env)
11. event.env-get-updated(app, env)
12. event.env-check-consistency(app, env)
# The updated-docs list can be builder dependent, but generally includes all new/changed documents,
# plus any output from `env-get-updated`, and then all "parent" documents in the ToC tree
# For builders that output a single page, they are first joined into a single doctree before post-transforms
# or the doctree-resolved event is emitted
for docname in updated-docs:
13. apply post-transforms (by priority): docutils.document -> docutils.document
14. event.doctree-resolved(app, doctree, docname)
- In the event that any reference nodes fail to resolve, the following may emit:
- event.missing-reference(env, node, contnode)
- event.warn-missing-reference(domain, node)
15. Generate output files
16. event.build-finished(app, exception)
Here is a more detailed list of
these events.
builder-inited(app)
Emitted when the builder object has been created. It is
available as app.builder.
config-inited(app, config)
Emitted when the config object has been initialized.
Added in version 1.8.
env-get-outdated(app, env, added, changed, removed)
Emitted when the environment determines which source files have
changed and should be re-read. added, changed and removed are
sets of docnames that the environment has determined. You can
return a list of docnames to re-read in addition to these.
Added in version 1.1.
env-purge-doc(app, env, docname)
Emitted when all traces of a source file should be cleaned from
the environment, that is, if the source file is removed or
before it is freshly read. This is for extensions that keep
their own caches in attributes of the environment.
For example, there is a cache of all modules on the environment.
When a source file has been changed, the cache's entries for the
file are cleared, since the module declarations could have been
removed from the file.
Added in version 0.5.
env-before-read-docs(app, env, docnames)
Emitted after the environment has determined the list of all
added and changed files and just before it reads them. It
allows extension authors to reorder the list of docnames
(inplace) before processing, or add more docnames that Sphinx
did not consider changed (but never add any docnames that are
not in env.found_docs).
You can also remove document names; do this with caution since
it will make Sphinx treat changed files as unchanged.
Added in version 1.3.
source-read(app, docname, source)
Emitted when a source file has been read. The source argument
is a list whose single element is the contents of the source
file. You can process the contents and replace this item to
implement source-level transformations.
For example, if you want to use $ signs to delimit inline math,
like in LaTeX, you can use a regular expression to replace $...$
by :math:`...`.
Added in version 0.5.
include-read(app, relative_path, parent_docname, content)
Emitted when a file has been read with the include directive.
The relative_path argument is a Path object representing the
relative path of the included file from the source directory.
The parent_docname argument is the name of the document that
contains the include directive. The source argument is a list
whose single element is the contents of the included file. You
can process the contents and replace this item to transform the
included content, as with the source-read event.
Added in version 7.2.5.
SEE ALSO:
The include directive and the source-read event.
object-description-transform(app, domain, objtype, contentnode)
Emitted when an object description directive has run. The
domain and objtype arguments are strings indicating object
description of the object. And contentnode is a content for the
object. It can be modified in-place.
Added in version 2.4.
doctree-read(app, doctree)
Emitted when a doctree has been parsed and read by the
environment, and is about to be pickled. The doctree can be
modified in-place.
missing-reference(app, env, node, contnode)
Emitted when a cross-reference to an object cannot be resolved.
If the event handler can resolve the reference, it should return
a new docutils node to be inserted in the document tree in place
of the node node. Usually this node is a reference node
containing contnode as a child. If the handler can not resolve
the cross-reference, it can either return None to let other
handlers try, or raise NoUri to prevent other handlers in trying
and suppress a warning about this cross-reference being
unresolved.
Parameters
o env -- The build environment (app.builder.env).
o node -- The pending_xref node to be resolved. Its
reftype, reftarget, modname and classname attributes
determine the type and target of the reference.
o contnode -- The node that carries the text and
formatting inside the future reference and should be a
child of the returned reference node.
Added in version 0.5.
warn-missing-reference(app, domain, node)
Emitted when a cross-reference to an object cannot be resolved
even after missing-reference. If the event handler can emit
warnings for the missing reference, it should return True. The
configuration variables nitpick_ignore and nitpick_ignore_regex
prevent the event from being emitted for the corresponding
nodes.
Added in version 3.4.
doctree-resolved(app, doctree, docname)
Emitted when a doctree has been "resolved" by the environment,
that is, all references have been resolved and TOCs have been
inserted. The doctree can be modified in place.
Here is the place to replace custom nodes that don't have
visitor methods in the writers, so that they don't cause errors
when the writers encounter them.
env-merge-info(app, env, docnames, other)
This event is only emitted when parallel reading of documents is
enabled. It is emitted once for every subprocess that has read
some documents.
You must handle this event in an extension that stores data in
the environment in a custom location. Otherwise the environment
in the main process will not be aware of the information stored
in the subprocess.
other is the environment object from the subprocess, env is the
environment from the main process. docnames is a set of
document names that have been read in the subprocess.
Added in version 1.3.
env-updated(app, env)
Emitted after reading all documents, when the environment and
all doctrees are now up-to-date.
You can return an iterable of docnames from the handler. These
documents will then be considered updated, and will be
(re-)written during the writing phase.
Added in version 0.5.
Changed in version 1.3: The handlers' return value is now used.
env-check-consistency(app, env)
Emitted when Consistency checks phase. You can check
consistency of metadata for whole of documents.
Added in version 1.6: As a experimental event
html-collect-pages(app)
Emitted when the HTML builder is starting to write non-document
pages. You can add pages to write by returning an iterable from
this event consisting of (pagename, context, templatename).
Added in version 1.0.
html-page-context(app, pagename, templatename, context, doctree)
Emitted when the HTML builder has created a context dictionary
to render a template with -- this can be used to add custom
elements to the context.
The pagename argument is the canonical name of the page being
rendered, that is, without .html suffix and using slashes as
path separators. The templatename is the name of the template
to render, this will be 'page.html' for all pages from reST
documents.
The context argument is a dictionary of values that are given to
the template engine to render the page and can be modified to
include custom values. Keys must be strings.
The doctree argument will be a doctree when the page is created
from a reST documents; it will be None when the page is created
from an HTML template alone.
You can return a string from the handler, it will then replace
'page.html' as the HTML template for this page.
NOTE:
You can install JS/CSS files for the specific page via
Sphinx.add_js_file() and Sphinx.add_css_file() since v3.5.0.
Added in version 0.4.
Changed in version 1.3:
The return value can now
specify a template name.
linkcheck-process-uri(app, uri)
Emitted when the linkcheck builder collects hyperlinks from
document. uri is a collected URI. The event handlers can
modify the URI by returning a string.
Added in version 4.1.
build-finished(app, exception)
Emitted when a build has finished, before Sphinx exits, usually
used for cleanup. This event is emitted even when the build
process raised an exception, given as the exception argument.
The exception is reraised in the application after the event
handlers have run. If the build process raised no exception,
exception will be None. This allows to customize cleanup
actions depending on the exception status.
Added in version 0.5.
Checking the Sphinx version
Use this to adapt your extension to API changes in Sphinx.
sphinx.version_info = (7, 3, 7, 'final', 0)
Version info for better programmatic use.
A tuple of five elements; for Sphinx version 1.2.1 beta 3 this
would be (1, 2, 1, 'beta', 3). The fourth element can be one of:
alpha, beta, rc, final. final always has 0 as the last element.
Added in version 1.2: Before version 1.2, check the string
sphinx.__version__.
The Config object
class sphinx.config.Config(config: dict[str, Any] | None = None,
overrides: dict[str, Any] | None = None)
Configuration file abstraction.
The Config object makes the values of all config options
available as attributes.
It is exposed via the Sphinx.config and
sphinx.environment.BuildEnvironment.config attributes. For
example, to get the value of language, use either
app.config.language or env.config.language.
The template bridge
class sphinx.application.TemplateBridge
This class defines the interface for a "template bridge", that
is, a class that renders templates given a template name and a
context.
init(builder: Builder, theme: Theme | None = None, dirs:
list[str] | None = None) -> None
Called by the builder to initialize the template system.
builder is the builder object; you'll probably want to
look at the value of builder.config.templates_path.
theme is a sphinx.theming.Theme object or None; in the
latter case, dirs can be list of fixed directories to
look for templates.
newest_template_mtime() -> float
Called by the builder to determine if output files are
outdated because of template changes. Return the mtime
of the newest template file that was changed. The
default implementation returns 0.
render(template: str, context: dict) -> None
Called by the builder to render a template given as a
filename with a specified context (a Python dictionary).
render_string(template: str, context: dict) -> str
Called by the builder to render a template given as a
string with a specified context (a Python dictionary).
Exceptions
exception sphinx.errors.SphinxError
Base class for Sphinx errors.
This is the base class for "nice" exceptions. When such an
exception is raised, Sphinx will abort the build and present the
exception category and message to the user.
Extensions are encouraged to derive from this exception for
their custom errors.
Exceptions not derived from SphinxError are treated as
unexpected and shown to the user with a part of the traceback
(and the full traceback saved in a temporary file).
category
Description of the exception "category", used in
converting the exception to a string ("category:
message"). Should be set accordingly in subclasses.
exception sphinx.errors.ConfigError
Configuration error.
exception sphinx.errors.ExtensionError(message: str, orig_exc:
Exception | None = None, modname: str | None = None)
Extension error.
exception sphinx.errors.ThemeError
Theme error.
exception sphinx.errors.VersionRequirementError
Incompatible Sphinx version error.
Project API
class sphinx.project.Project(srcdir: str | os.PathLike[str],
source_suffix: Iterable[str])
A project is the source code set of the Sphinx document(s).
discover(exclude_paths: Iterable[str] = (), include_paths:
Iterable[str] = ('**',)) -> set[str]
Find all document files in the source directory and put
them in docnames.
doc2path(docname: str, absolute: bool) -> str
Return the filename for the document name.
If absolute is True, return as an absolute path. Else,
return as a relative path to the source directory.
path2doc(filename: str | PathLike[str]) -> str | None
Return the docname for the filename if the file is a
document.
filename should be absolute or relative to the source
directory.
restore(other: Project) -> None
Take over a result of last build.
docnames: set[str]
The name of documents belonging to this project.
source_suffix
source_suffix. Same as source_suffix.
srcdir Source directory.
Build environment API
class sphinx.environment.BuildEnvironment
Attributes
app Reference to the Sphinx (application) object.
config Reference to the Config object.
project
Target project. See Project.
srcdir Source directory.
doctreedir
Directory for storing pickled doctrees.
events An EventManager object.
found_docs
A set of all existing docnames.
metadata
Dictionary mapping docnames to "metadata" (see File-wide
metadata).
titles Dictionary mapping docnames to the docutils node for
their main title.
docname
Returns the docname of the document currently being
parsed.
Utility methods
doc2path(docname: str, base: bool = True) -> str
Return the filename for the document name.
If base is True, return absolute path under self.srcdir.
If base is False, return relative path to self.srcdir.
relfn2path(filename: str, docname: str | None = None) ->
tuple[str, str]
Return paths to a file referenced from a document,
relative to documentation root and absolute.
In the input "filename", absolute filenames are taken as
relative to the source dir, while relative filenames are
relative to the dir of the containing document.
note_dependency(filename: str) -> None
Add filename as a dependency of the current document.
This means that the document will be rebuilt if this file
changes.
filename should be absolute or relative to the source
directory.
new_serialno(category: str = '') -> int
Return a serial number, e.g. for index entry targets.
The number is guaranteed to be unique in the current
document.
note_reread() -> None
Add the current document to the list of documents that
will automatically be re-read at the next build.
Builder API
Todo
Expand this.
class sphinx.builders.Builder
This is the base class for all builders.
These attributes should be set on builder classes:
name = ''
The builder's name, for the -b command line option.
format = ''
The builder's output format, or '' if no document output
is produced.
epilog = ''
The message emitted upon successful build completion.
This can be a printf-style template string with the
following keys: outdir, project
allow_parallel = False
allow parallel write_doc() calls
supported_image_types: list[str] = []
The list of MIME types of image formats supported by the
builder. Image files are searched in the order in which
they appear here.
supported_remote_images = False
The builder supports remote images or not.
supported_data_uri_images = False
The builder supports data URIs or not.
default_translator_class: type[nodes.NodeVisitor]
default translator class for the builder. This can be
overridden by set_translator().
These methods are
predefined and will be
called from the
application:
get_relative_uri(from_: str, to: str, typ: str | None = None) ->
str Return a relative URI between two source filenames.
May raise environment.NoUri if there's no way to return a
sensible URI.
build_all() -> None
Build all source files.
build_specific(filenames: list[str]) -> None
Only rebuild as much as needed for changes in the
filenames.
build_update() -> None
Only rebuild what was changed or added since last build.
build(docnames: Iterable[str] | None, summary: str | None =
None, method: str = 'update') -> None
Main build method.
First updates the environment, and then calls write().
These methods can be
overridden in concrete
builder classes:
init() -> None
Load necessary templates and perform initialization. The
default implementation does nothing.
get_outdated_docs() -> str | Iterable[str]
Return an iterable of output files that are outdated, or
a string describing what an update build will build.
If the builder does not output individual files
corresponding to source files, return a string here. If
it does, return an iterable of those files that need to
be written.
get_target_uri(docname: str, typ: str | None = None) -> str
Return the target URI for a document name.
typ can be used to qualify the link characteristic for
individual builders.
prepare_writing(docnames: set[str]) -> None
A place where you can add logic before write_doc() is run
write_doc(docname: str, doctree: document) -> None
Where you actually write something to the filesystem.
finish() -> None
Finish the building process.
The default implementation does nothing.
Attributes
events An EventManager object.
Environment Collector API
class sphinx.environment.collectors.EnvironmentCollector
An EnvironmentCollector is a specific data collector from each
document.
It gathers data and stores BuildEnvironment as a database.
Examples of specific data would be images, download files,
section titles, metadatas, index entries and toctrees, etc.
clear_doc(app: Sphinx, env: BuildEnvironment, docname: str) ->
None Remove specified data of a document.
This method is called on the removal of the document.
get_outdated_docs(app: Sphinx, env: BuildEnvironment, added:
set[str], changed: set[str], removed: set[str]) -> list[str]
Return a list of docnames to re-read.
This methods is called before reading the documents.
get_updated_docs(app: Sphinx, env: BuildEnvironment) ->
list[str]
Return a list of docnames to re-read.
This methods is called after reading the whole of
documents (experimental).
merge_other(app: Sphinx, env: BuildEnvironment, docnames:
set[str], other: BuildEnvironment) -> None
Merge in specified data regarding docnames from a
different BuildEnvironment object which coming from a
subprocess in parallel builds.
process_doc(app: Sphinx, doctree: nodes.document) -> None
Process a document and gather specific data from it.
This method is called after the document is read.
Docutils markup API
This section describes the API for adding ReST markup elements (roles
and directives).
Roles
Directives
Directives are handled by classes derived from
docutils.parsers.rst.Directive. They have to be registered by an
extension using Sphinx.add_directive() or
Sphinx.add_directive_to_domain().
class docutils.parsers.rst.Directive
The markup syntax of the new directive is determined by the
follow five class attributes:
required_arguments = 0
Number of required directive arguments.
optional_arguments = 0
Number of optional arguments after the required
arguments.
final_argument_whitespace = False
May the final argument contain whitespace?
option_spec = None
Mapping of option names to validator functions.
Option validator functions take a single parameter, the
option argument (or None if not given), and should
validate it or convert it to the proper form. They raise
ValueError or TypeError to indicate failure.
There are several predefined and possibly useful
validators in the docutils.parsers.rst.directives module.
has_content = False
May the directive have content?
New directives must
implement the run()
method:
run() This method must process the directive arguments, options
and content, and return a list of Docutils/Sphinx nodes
that will be inserted into the document tree at the point
where the directive was encountered.
Instance attributes
that are always set on
the directive are:
name The directive name (useful when registering the same
directive class under multiple names).
arguments
The arguments given to the directive, as a list.
options
The options given to the directive, as a dictionary
mapping option names to validated/converted values.
content
The directive content, if given, as a ViewList.
lineno The absolute line number on which the directive appeared.
This is not always a useful value; use srcline instead.
content_offset
Internal offset of the directive content. Used when
calling nested_parse (see below).
block_text
The string containing the entire directive.
state
state_machine
The state and state machine which controls the parsing.
Used for nested_parse.
ViewLists
Docutils represents document source lines in a class
docutils.statemachine.ViewList. This is a list with extended
functionality -- for one, slicing creates views of the original list,
and also the list contains information about the source line numbers.
The Directive.content attribute is a ViewList. If you generate content
to be parsed as ReST, you have to create a ViewList yourself.
Important for content generation are the following points:
o The constructor takes a list of strings (lines) and a source
(document) name.
o The .append() method takes a line and a source name as well.
Parsing directive content as ReST
Many directives will contain more markup that must be parsed. To do
this, use one of the following APIs from the Directive.run() method:
o self.state.nested_parse
o sphinx.util.nodes.nested_parse_with_titles() -- this allows titles in
the parsed content.
Both APIs parse the content
into a given node. They are
used like this:
node = docutils.nodes.paragraph()
# either
nested_parse_with_titles(self.state, self.result, node)
# or
self.state.nested_parse(self.result, 0, node)
NOTE:
sphinx.util.docutils.switch_source_input() allows to change a target
file during nested_parse. It is useful to mixed contents. For
example, sphinx. ext.autodoc uses it to parse docstrings:
from sphinx.util.docutils import switch_source_input
# Switch source_input between parsing content.
# Inside this context, all parsing errors and warnings are reported as
# happened in new source_input (in this case, ``self.result``).
with switch_source_input(self.state, self.result):
node = docutils.nodes.paragraph()
self.state.nested_parse(self.result, 0, node)
Deprecated since version
1.7: Until Sphinx 1.6,
sphinx.ext.autodoc.AutodocReporter
was used for this purpose.
It is replaced by
switch_source_input().
If you don't need the
wrapping node, you can use
any concrete node type and
return node.children from the
Directive.
SEE ALSO:
Creating directives HOWTO of the Docutils documentation
Domain API
class sphinx.domains.Domain(env: BuildEnvironment)
A Domain is meant to be a group of "object" description
directives for objects of a similar nature, and corresponding
roles to create references to them. Examples would be Python
modules, classes, functions etc., elements of a templating
language, Sphinx roles and directives, etc.
Each domain has a separate storage for information about
existing objects and how to reference them in self.data, which
must be a dictionary. It also must implement several functions
that expose the object information in a uniform way to parts of
Sphinx that allow the user to reference or search for objects in
a domain-agnostic way.
About self.data: since all object and cross-referencing
information is stored on a BuildEnvironment instance, the
domain.data object is also stored in the env.domaindata dict
under the key domain.name. Before the build process starts,
every active domain is instantiated and given the environment
object; the domaindata dict must then either be nonexistent or a
dictionary whose 'version' key is equal to the domain class'
data_version attribute. Otherwise, OSError is raised and the
pickled environment is discarded.
add_object_type(name: str, objtype: ObjType) -> None
Add an object type.
check_consistency() -> None
Do consistency checks (experimental).
clear_doc(docname: str) -> None
Remove traces of a document in the domain-specific
inventories.
directive(name: str) -> Callable | None
Return a directive adapter class that always gives the
registered directive its full name ('domain:name') as
self.name.
get_enumerable_node_type(node: Node) -> str | None
Get type of enumerable nodes (experimental).
get_full_qualified_name(node: Element) -> str | None
Return full qualified name for given node.
get_objects() -> Iterable[tuple[str, str, str, str, str, int]]
Return an iterable of "object descriptions".
Object descriptions are tuples with six items:
name Fully qualified name.
dispname
Name to display when searching/linking.
type Object type, a key in self.object_types.
docname
The document where it is to be found.
anchor The anchor name for the object.
priority
How "important" the object is (determines
placement in search results). One of:
1 Default priority (placed before full-text
matches).
0 Object is important (placed before
default-priority objects).
2 Object is unimportant (placed after
full-text matches).
-1 Object should not show up in search at all.
get_type_name(type: ObjType, primary: bool = False) -> str
Return full name for given ObjType.
merge_domaindata(docnames: list[str], otherdata: dict[str, Any])
-> None
Merge in data regarding docnames from a different
domaindata inventory (coming from a subprocess in
parallel builds).
process_doc(env: BuildEnvironment, docname: str, document:
nodes.document) -> None
Process a document after it is read by the environment.
process_field_xref(pnode: pending_xref) -> None
Process a pending xref created in a doc field. For
example, attach information about the current scope.
resolve_any_xref(env: BuildEnvironment, fromdocname: str,
builder: Builder, target: str, node: pending_xref, contnode:
Element) -> list[tuple[str, Element]]
Resolve the pending_xref node with the given target.
The reference comes from an "any" or similar role, which
means that we don't know the type. Otherwise, the
arguments are the same as for resolve_xref().
The method must return a list (potentially empty) of
tuples ('domain:role', newnode), where 'domain:role' is
the name of a role that could have created the same
reference, e.g. 'py:func'. newnode is what
resolve_xref() would return.
Added in version 1.3.
resolve_xref(env: BuildEnvironment, fromdocname: str, builder:
Builder, typ: str, target: str, node: pending_xref, contnode:
Element) -> Element | None
Resolve the pending_xref node with the given typ and
target.
This method should return a new node, to replace the xref
node, containing the contnode which is the markup content
of the cross-reference.
If no resolution can be found, None can be returned; the
xref node will then given to the missing-reference event,
and if that yields no resolution, replaced by contnode.
The method can also raise sphinx.environment.NoUri to
suppress the missing-reference event being emitted.
role(name: str) -> RoleFunction | None
Return a role adapter function that always gives the
registered role its full name ('domain:name') as the
first argument.
setup() -> None
Set up domain object.
dangling_warnings: dict[str, str] = {}
role name -> a warning message if reference is missing
data: dict
data value
data_version = 0
data version, bump this when the format of self.data
changes
directives: dict[str, type[Directive]] = {}
directive name -> directive class
enumerable_nodes: dict[type[Node], tuple[str, TitleGetter |
None]] = {}
node_class -> (enum_node_type, title_getter)
indices: list[type[Index]] = []
a list of Index subclasses
initial_data: dict = {}
data value for a fresh environment
label = ''
domain label: longer, more descriptive (used in messages)
name = ''
domain name: should be short, but unique
object_types: dict[str, ObjType] = {}
type (usually directive) name -> ObjType instance
roles: dict[str, RoleFunction | XRefRole] = {}
role name -> role callable
class sphinx.domains.ObjType(lname: str, *roles: Any, **attrs: Any)
An ObjType is the description for a type of object that a domain
can document. In the object_types attribute of Domain
subclasses, object type names are mapped to instances of this
class.
Constructor arguments:
o lname: localized name of the type (do not include domain name)
o roles: all the roles that can refer to an object of this type
o attrs: object attributes -- currently only "searchprio" is
known, which defines the object's priority in the full-text
search index, see Domain.get_objects().
class sphinx.domains.Index(domain: Domain)
An Index is the description for a domain-specific index. To add
an index to a domain, subclass Index, overriding the three name
attributes:
o name is an identifier used for generating file names. It is
also used for a hyperlink target for the index. Therefore,
users can refer the index page using ref role and a string
which is combined domain name and name attribute (ex.
:ref:`py-modindex`).
o localname is the section title for the index.
o shortname is a short name for the index, for use in the
relation bar in HTML output. Can be empty to disable entries
in the relation bar.
and providing a
generate() method.
Then, add the index
class to your domain's
indices list.
Extensions can add
indices to existing
domains using
add_index_to_domain().
Changed in version
3.0: Index pages can
be referred by domain
name and index name
via ref role.
abstract generate(docnames: Iterable[str] | None = None) ->
tuple[list[tuple[str, list[IndexEntry]]], bool]
Get entries for the index.
If docnames is given, restrict to entries referring to
these docnames.
The return value is a tuple of (content, collapse):
collapse
A boolean that determines if sub-entries should
start collapsed (for output formats that support
collapsing sub-entries).
content:
A sequence of (letter, entries) tuples, where
letter is the "heading" for the given entries,
usually the starting letter, and entries is a
sequence of single entries. Each entry is a
sequence [name, subtype, docname, anchor, extra,
qualifier, descr]. The items in this sequence have
the following meaning:
name The name of the index entry to be
displayed.
subtype
The sub-entry related type. One of:
0 A normal entry.
1 An entry with sub-entries.
2 A sub-entry.
docname
docname where the entry is located.
anchor Anchor for the entry within docname
extra Extra info for the entry.
qualifier
Qualifier for the description.
descr Description for the entry.
Qualifier and
description are
not rendered
for some output
formats such as
LaTeX.
class sphinx.directives.ObjectDescription(name, arguments, options,
content, lineno, content_offset, block_text, state, state_machine)
Directive to describe a class, function or similar object. Not
used directly, but subclassed (in domain-specific directives) to
add custom behavior.
_object_hierarchy_parts(sig_node: desc_signature) -> tuple[str,
...] Returns a tuple of strings, one entry for each part of
the object's hierarchy (e.g. ('module', 'submodule',
'Class', 'method')). The returned tuple is used to
properly nest children within parents in the table of
contents, and can also be used within the
_toc_entry_name() method.
This method must not be used outwith table of contents
generation.
_toc_entry_name(sig_node: desc_signature) -> str
Returns the text of the table of contents entry for the
object.
This function is called once, in run(), to set the name
for the table of contents entry (a special attribute
_toc_name is set on the object node, later used in
environment.collectors.toctree.TocTreeCollector.process_doc().build_toc()
when the table of contents entries are collected).
To support table of contents entries for their objects,
domains must override this method, also respecting the
configuration setting toc_object_entries_show_parents.
Domains must also override _object_hierarchy_parts(),
with one (string) entry for each part of the object's
hierarchy. The result of this method is set on the
signature node, and can be accessed as
sig_node['_toc_parts'] for use within this method. The
resulting tuple is also used to properly nest children
within parents in the table of contents.
An example implementations of this method is within the
python domain (PyObject._toc_entry_name()). The python
domain sets the _toc_parts attribute within the
handle_signature() method.
add_target_and_index(name: ObjDescT, sig: str, signode:
desc_signature) -> None
Add cross-reference IDs and entries to self.indexnode, if
applicable.
name is whatever handle_signature() returned.
after_content() -> None
Called after parsing content. Used to reset information
about the current directive context on the build
environment.
before_content() -> None
Called before parsing content. Used to set information
about the current directive context on the build
environment.
get_signatures() -> list[str]
Retrieve the signatures to document from the directive
arguments. By default, signatures are given as
arguments, one per line.
handle_signature(sig: str, signode: desc_signature) -> ObjDescT
Parse the signature sig into individual nodes and append
them to signode. If ValueError is raised, parsing is
aborted and the whole sig is put into a single desc_name
node.
The return value should be a value that identifies the
object. It is passed to add_target_and_index()
unchanged, and otherwise only used to skip duplicates.
run() -> list[Node]
Main directive entry function, called by docutils upon
encountering the directive.
This directive is meant to be quite easily subclassable,
so it delegates to several additional methods. What it
does:
o find out if called as a domain-specific directive, set
self.domain
o create a desc node to fit all description inside
o parse standard options, currently no-index
o create an index node if needed as self.indexnode
o parse all given signatures (as returned by
self.get_signatures()) using self.handle_signature(),
which should either return a name or raise ValueError
o add index entries using self.add_target_and_index()
o parse the content and handle doc fields in it
transform_content(contentnode: desc_content) -> None
Called after creating the content through nested parsing,
but before the object-description-transform event is
emitted, and before the info-fields are transformed. Can
be used to manipulate the content.
final_argument_whitespace = True
May the final argument contain whitespace?
has_content = True
May the directive have content?
option_spec: ClassVar[dict[str, Callable[[str], Any]]] =
{'no-contents-entry': , 'no-index': , 'no-index-entry': , 'no-typesetting':
, 'nocontentsentry': , 'noindex':
, 'noindexentry': }
Mapping of option names to validator functions.
optional_arguments = 0
Number of optional arguments after the required
arguments.
required_arguments = 1
Number of required directive arguments.
Python Domain
class sphinx.domains.python.PythonDomain(env: BuildEnvironment)
Python language domain.
objects
modules
note_object(name: str, objtype: str, node_id: str, aliased: bool
= False, location: Any = None) -> None
Note a python object for cross reference.
Added in version 2.1.
note_module(name: str, node_id: str, synopsis: str, platform:
str, deprecated: bool) -> None
Note a python module for cross reference.
Added in version 2.1.
Parser API
The docutils documentation describes parsers as follows:
The Parser analyzes the input document and creates a node tree
representation.
In Sphinx, the parser modules
works as same as docutils.
The parsers are registered to
Sphinx by extensions using
Application APIs;
Sphinx.add_source_suffix()
and
Sphinx.add_source_parser().
The source suffix is a
mapping from file suffix to
file type. For example, .rst
file is mapped to
'restructuredtext' type.
Sphinx uses the file type to
looking for parsers from
registered list. On
searching, Sphinx refers to
the Parser.supported
attribute and picks up a
parser which contains the
file type in the attribute.
The users can override the
source suffix mappings using
source_suffix like following:
# a mapping from file suffix to file types
source_suffix = {
'.rst': 'restructuredtext',
'.md': 'markdown',
}
You should indicate file
types your parser supports.
This will allow users to
configure their settings
appropriately.
class sphinx.parsers.Parser
A base class of source parsers. The additional parsers should
inherit this class instead of docutils.parsers.Parser. Compared
with docutils.parsers.Parser, this class improves accessibility
to Sphinx APIs.
The subclasses can access sphinx core runtime objects (app,
config and env).
set_application(app: Sphinx) -> None
set_application will be called from Sphinx to set app and
other instance variables
Parameters
app (sphinx.application.Sphinx) -- Sphinx
application object
config: Config
The config object
env: BuildEnvironment
The environment object
Doctree node classes added by Sphinx
Nodes for domain-specific object descriptions
Top-level nodes
These nodes form the top-most levels of object descriptions.
class sphinx.addnodes.desc(rawsource='', *children, **attributes)
Node for a list of object signatures and a common description of
them.
Contains one or more desc_signature nodes and then a single
desc_content node.
This node always has two classes:
o The name of the domain it belongs to, e.g., py or cpp.
o The name of the object type in the domain, e.g., function.
class sphinx.addnodes.desc_signature(*args: Any, **kwargs: Any)
Node for a single object signature.
As default the signature is a single-line signature. Set
is_multiline = True to describe a multi-line signature. In that
case all child nodes must be desc_signature_line nodes.
This node always has the classes sig, sig-object, and the domain
it belongs to.
class sphinx.addnodes.desc_signature_line(rawsource='', text='',
*children, **attributes)
Node for a line in a multi-line object signature.
It should only be used as a child of a desc_signature with
is_multiline set to True. Set add_permalink = True for the line
that should get the permalink.
class sphinx.addnodes.desc_content(rawsource='', *children,
**attributes)
Node for object description content.
Must be the last child node in a desc node.
class sphinx.addnodes.desc_inline(domain: str, *args: Any, **kwargs:
Any) Node for a signature fragment in inline text.
This is for example used for roles like cpp:expr.
This node always has the classes sig, sig-inline, and the name
of the domain it belongs to.
Nodes for high-level structure in signatures
These nodes occur in in non-multiline desc_signature nodes and in
desc_signature_line nodes.
class sphinx.addnodes.desc_name(*args: Any, **kwargs: Any)
Node for the main object name.
For example, in the declaration of a Python class
MyModule.MyClass, the main name is MyClass.
This node always has the class sig-name.
class sphinx.addnodes.desc_addname(*args: Any, **kwargs: Any)
Node for additional name parts for an object.
For example, in the declaration of a Python class
MyModule.MyClass, the additional name part is MyModule..
This node always has the class sig-prename.
class sphinx.addnodes.desc_type(rawsource='', text='', *children,
**attributes)
Node for return types or object type names.
class sphinx.addnodes.desc_returns(rawsource='', text='', *children,
**attributes)
Node for a "returns" annotation (a la -> in Python).
class sphinx.addnodes.desc_parameterlist(rawsource='', text='',
*children, **attributes)
Node for a general parameter list.
As default the parameter list is written in line with the rest
of the signature. Set multi_line_parameter_list = True to
describe a multi-line parameter list. In that case each
parameter will then be written on its own, indented line.
class sphinx.addnodes.desc_parameter(rawsource='', text='', *children,
**attributes)
Node for a single parameter.
class sphinx.addnodes.desc_optional(rawsource='', text='', *children,
**attributes)
Node for marking optional parts of the parameter list.
class sphinx.addnodes.desc_annotation(rawsource='', text='', *children,
**attributes)
Node for signature annotations (not Python 3-style annotations).
Nodes for signature text elements
These nodes inherit desc_sig_element and are generally translated to
docutils.nodes.inline by SigElementFallbackTransform.
Extensions may create additional desc_sig_*-like nodes but in order for
SigElementFallbackTransform to translate them to inline nodes
automatically, they must be added to SIG_ELEMENTS via the class keyword
argument _sig_element=True of desc_sig_element, e.g.:
class desc_custom_sig_node(desc_sig_element, _sig_element=True): ...
For backwards compatibility,
it is still possible to add
the nodes directly using
SIG_ELEMENTS.add(desc_custom_sig_node).
sphinx.addnodes.SIG_ELEMENTS: set[type[desc_sig_element]]
A set of classes inheriting desc_sig_element. Each node class is
expected to be handled by the builder's translator class if the
latter does not inherit from SphinxTranslator.
This set can be extended manually by third-party extensions or
by subclassing desc_sig_element and using the class keyword
argument _sig_element=True.
class sphinx.addnodes.desc_sig_element(rawsource: str = '', text: str =
'', *children: Element, **attributes: Any)
Common parent class of nodes for inline text of a signature.
class sphinx.addnodes.desc_sig_space(rawsource: str = '', text: str = '
', *children: Element, **attributes: Any)
Node for a space in a signature.
class sphinx.addnodes.desc_sig_name(rawsource: str = '', text: str =
'', *children: Element, **attributes: Any)
Node for an identifier in a signature.
class sphinx.addnodes.desc_sig_operator(rawsource: str = '', text: str
= '', *children: Element, **attributes: Any)
Node for an operator in a signature.
class sphinx.addnodes.desc_sig_punctuation(rawsource: str = '', text:
str = '', *children: Element, **attributes: Any)
Node for punctuation in a signature.
class sphinx.addnodes.desc_sig_keyword(rawsource: str = '', text: str =
'', *children: Element, **attributes: Any)
Node for a general keyword in a signature.
class sphinx.addnodes.desc_sig_keyword_type(rawsource: str = '', text:
str = '', *children: Element, **attributes: Any)
Node for a keyword which is a built-in type in a signature.
class sphinx.addnodes.desc_sig_literal_number(rawsource: str = '',
text: str = '', *children: Element, **attributes: Any)
Node for a numeric literal in a signature.
class sphinx.addnodes.desc_sig_literal_string(rawsource: str = '',
text: str = '', *children: Element, **attributes: Any)
Node for a string literal in a signature.
class sphinx.addnodes.desc_sig_literal_char(rawsource: str = '', text:
str = '', *children: Element, **attributes: Any)
Node for a character literal in a signature.
New admonition-like constructs
class sphinx.addnodes.versionmodified(rawsource='', text='', *children,
**attributes)
Node for version change entries.
Currently used for "versionadded", "versionchanged",
"deprecated" and "versionremoved" directives.
class sphinx.addnodes.seealso(rawsource='', *children, **attributes)
Custom "see also" admonition.
Other paragraph-level nodes
class sphinx.addnodes.compact_paragraph(rawsource='', text='',
*children, **attributes)
Node for a compact paragraph (which never makes a
node).
New inline nodes
class sphinx.addnodes.index(rawsource='', text='', *children,
**attributes)
Node for index entries.
This node is created by the index directive and has one
attribute, entries. Its value is a list of 5-tuples of
(entrytype, entryname, target, ignored, key).
entrytype is one of "single", "pair", "double", "triple".
key is categorization characters (usually a single character)
for general index page. For the details of this, please see
also: glossary and issue #2320.
class sphinx.addnodes.pending_xref(rawsource='', *children,
**attributes)
Node for cross-references that cannot be resolved without
complete information about all documents.
These nodes are resolved before writing output, in
BuildEnvironment.resolve_references.
class sphinx.addnodes.pending_xref_condition(rawsource='', text='',
*children, **attributes)
Node representing a potential way to create a cross-reference
and the condition in which this way should be used.
This node is only allowed to be placed under a pending_xref
node. A pending_xref node must contain either no
pending_xref_condition nodes or it must only contains
pending_xref_condition nodes.
The cross-reference resolver will replace a pending_xref which
contains pending_xref_condition nodes by the content of exactly
one of those pending_xref_condition nodes' content. It uses the
condition attribute to decide which pending_xref_condition
node's content to use. For example, let us consider how the
cross-reference resolver acts on:
StringIO
io.StringIO
If the cross-reference
resolver successfully
resolves the
cross-reference, then
it rewrites the
pending_xref as:
StringIO
Otherwise, if the
cross-reference
resolution failed, it
rewrites the
pending_xref as:
io.StringIO
The
pending_xref_condition
node should have
condition attribute.
Domains can be store
their individual
conditions into the
attribute to filter
contents on resolving
phase. As a reserved
condition name,
condition="*" is used
for the fallback of
resolution failure.
Additionally, as a
recommended condition
name,
condition="resolved"
represents a
resolution success in
the intersphinx
module.
Added in version 4.0.
class sphinx.addnodes.literal_emphasis(rawsource='', text='',
*children, **attributes)
Node that behaves like emphasis, but further text processors are
not applied (e.g. smartypants for HTML output).
class sphinx.addnodes.download_reference(rawsource='', text='',
*children, **attributes)
Node for download references, similar to pending_xref.
Special nodes
class sphinx.addnodes.only(rawsource='', *children, **attributes)
Node for "only" directives (conditional inclusion based on
tags).
class sphinx.addnodes.highlightlang(rawsource='', *children,
**attributes)
Inserted to set the highlight language and line number options
for subsequent code blocks.
You should not need to
generate the nodes below in
extensions.
class sphinx.addnodes.glossary(rawsource='', *children, **attributes)
Node to insert a glossary.
class sphinx.addnodes.toctree(rawsource='', *children, **attributes)
Node for inserting a "TOC tree".
class sphinx.addnodes.start_of_file(rawsource='', *children,
**attributes)
Node to mark start of a new file, used in the LaTeX builder
only.
class sphinx.addnodes.productionlist(rawsource='', *children,
**attributes)
Node for grammar production lists.
Contains production nodes.
class sphinx.addnodes.production(rawsource='', text='', *children,
**attributes)
Node for a single grammar production rule.
Logging API
sphinx.util.logging.getLogger(name)
Get logger wrapped by sphinx.util.logging.SphinxLoggerAdapter.
Sphinx logger always uses sphinx.* namespace to be independent
from settings of root logger. It ensures logging is consistent
even if a third-party extension or imported application resets
logger settings.
Example usage:
>>> from sphinx.util import logging
>>> logger = logging.getLogger(__name__)
>>> logger.info('Hello, this is an extension!')
Hello, this is an extension!
class sphinx.util.logging.SphinxLoggerAdapter(logging.LoggerAdapter)
LoggerAdapter allowing type and subtype keywords.
error(msg, *args, **kwargs)
critical(msg, *args, **kwargs)
warning(msg, *args, **kwargs)
Logs a message on this logger with the specified level.
Basically, the arguments are as with python's logging
module.
In addition, Sphinx logger supports following keyword
arguments:
type, *subtype*
Categories of warning logs. It is used to
suppress warnings by suppress_warnings setting.
location
Where the warning happened. It is used to include
the path and line number in each log. It allows
docname, tuple of docname and line number and
nodes:
logger = sphinx.util.logging.getLogger(__name__)
logger.warning('Warning happened!', location='index')
logger.warning('Warning happened!', location=('chapter1/index', 10))
logger.warning('Warning happened!', location=some_node)
color The color of logs. By default, error level logs
are colored as "darkred", critical level ones is
not colored, and warning level ones are colored as
"red".
log(level, msg, *args, **kwargs)
info(msg, *args, **kwargs)
verbose(msg, *args, **kwargs)
debug(msg, *args, **kwargs)
Logs a message to this logger with the specified level.
Basically, the arguments are as with python's logging
module.
In addition, Sphinx logger supports following keyword
arguments:
nonl If true, the logger does not fold lines at the end
of the log message. The default is False.
location
Where the message emitted. For more detail, see
SphinxLoggerAdapter.warning().
color The color of logs. By default, info and verbose
level logs are not colored, and debug level ones
are colored as "darkgray".
sphinx.util.logging.pending_logging()
Context manager to postpone logging all logs temporarily.
For example:
>>> with pending_logging():
>>> logger.warning('Warning message!') # not flushed yet
>>> some_long_process()
>>>
Warning message! # the warning is flushed here
sphinx.util.logging.pending_warnings()
Context manager to postpone logging warnings temporarily.
Similar to pending_logging().
sphinx.util.logging.prefixed_warnings()
Context manager to prepend prefix to all warning log records
temporarily.
For example:
>>> with prefixed_warnings("prefix:"):
>>> logger.warning('Warning message!') # => prefix: Warning message!
Added in version 2.0.
i18n API
sphinx.locale.init(locale_dirs: Iterable[str | None], language: str |
None, catalog: str = 'sphinx', namespace: str = 'general') ->
tuple[NullTranslations, bool]
Look for message catalogs in locale_dirs and ensure that there
is at least a NullTranslations catalog set in translators. If
called multiple times or if several .mo files are found, their
contents are merged together (thus making init reentrant).
sphinx.locale.init_console(locale_dir: str | None = None, catalog: str
= 'sphinx') -> tuple[NullTranslations, bool]
Initialize locale for console.
Added in version 1.8.
sphinx.locale.get_translation(catalog: str, namespace: str = 'general')
-> Callable[[str], str]
Get a translation function based on the catalog and namespace.
The extension can use this API to translate the messages on the
extension:
import os
from sphinx.locale import get_translation
MESSAGE_CATALOG_NAME = 'myextension' # name of *.pot, *.po and *.mo files
_ = get_translation(MESSAGE_CATALOG_NAME)
text = _('Hello Sphinx!')
def setup(app):
package_dir = os.path.abspath(os.path.dirname(__file__))
locale_dir = os.path.join(package_dir, 'locales')
app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
With this code, sphinx
searches a message
catalog from
${package_dir}/locales/${language}/LC_MESSAGES/myextension.mo.
The language is used
for the searching.
Added in version 1.8.
sphinx.locale._(message: str) -> str
Translation function for messages on documentation (menu,
labels, themes and so on). This function follows language
setting.
sphinx.locale.__(message: str) -> str
Translation function for console messages This function follows
locale setting (LC_ALL, LC_MESSAGES and so on).
Extension internationalization (i18n) and localization (l10n) using i18n
API
Added in version 1.8.
An extension may naturally come with message translations. This is
briefly summarized in sphinx.locale.get_translation() help.
In practice, you have to:
1. Choose a name for your message catalog, which must be unique.
Usually the name of your extension is used for the name of message
catalog.
2. Mark in your extension sources all messages as translatable, via
sphinx.locale.get_translation() function, usually renamed _(), e.g.:
src/__init__.py
from sphinx.locale import get_translation
MESSAGE_CATALOG_NAME = 'myextension'
_ = get_translation(MESSAGE_CATALOG_NAME)
translated_text = _('Hello Sphinx!')
3. Set up your extension to be aware of its dedicated translations:
src/__init__.py
def setup(app):
package_dir = path.abspath(path.dirname(__file__))
locale_dir = os.path.join(package_dir, 'locales')
app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
4. Generate message catalog template *.pot file, usually in locale/
source directory, for example via Babel:
$ pybabel extract --output=src/locale/myextension.pot src/
5. Create message catalogs (*.po) for each language which your
extension will provide localization, for example via Babel:
$ pybabel init --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale --locale=fr_FR
6. Translate message catalogs for each language manually
7. Compile message catalogs into *.mo files, for example via Babel:
$ pybabel compile --directory=src/locale --domain=myextension
8. Ensure that message catalog files are distributed when your package
will be installed, by adding equivalent line in your extension
MANIFEST.in:
MANIFEST.in
recursive-include src *.pot *.po *.mo
When the messages on your
extension has been changed,
you need to also update
message catalog template and
message catalogs, for example
via Babel:
$ pybabel extract --output=src/locale/myextension.pot src/
$ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale
Utilities
Sphinx provides utility classes and functions to develop extensions.
Base classes for components
These base classes are useful to allow your extensions to obtain Sphinx
components (e.g. Config, BuildEnvironment and so on) easily.
NOTE:
The subclasses of them might not work with bare docutils because
they are strongly coupled with Sphinx.
class sphinx.transforms.SphinxTransform(document, startnode=None)
A base class of Transforms.
Compared with docutils.transforms.Transform, this class improves
accessibility to Sphinx APIs.
property app: Sphinx
Reference to the Sphinx object.
property config: Config
Reference to the Config object.
property env: BuildEnvironment
Reference to the BuildEnvironment object.
class sphinx.transforms.post_transforms.SphinxPostTransform(document,
startnode=None)
A base class of post-transforms.
Post transforms are invoked to modify the document to
restructure it for outputting. They resolve references, convert
images, do special transformation for each output formats and so
on. This class helps to implement these post transforms.
apply(**kwargs: Any) -> None
Override to apply the transform to the document tree.
is_supported() -> bool
Check this transform working for current builder.
run(**kwargs: Any) -> None
Main method of post transforms.
Subclasses should override this method instead of
apply().
class sphinx.util.docutils.SphinxDirective(name, arguments, options,
content, lineno, content_offset, block_text, state, state_machine)
A base class for Sphinx directives.
This class provides helper methods for Sphinx directives.
NOTE:
The subclasses of this class might not work with docutils.
This class is strongly coupled with Sphinx.
get_location() -> str
Get current location info for logging.
get_source_info() -> tuple[str, int]
Get source and line number.
set_source_info(node: Node) -> None
Set source and line number to the node.
property config: Config
Reference to the Config object.
property env: BuildEnvironment
Reference to the BuildEnvironment object.
class sphinx.util.docutils.SphinxRole
A base class for Sphinx roles.
This class provides helper methods for Sphinx roles.
NOTE:
The subclasses of this class might not work with docutils.
This class is strongly coupled with Sphinx.
get_location() -> str
Get current location info for logging.
property config: Config
Reference to the Config object.
content: Sequence[str]
A list of strings, the directive content for
customisation (from the "role" directive).
property env: BuildEnvironment
Reference to the BuildEnvironment object.
inliner: Inliner
The docutils.parsers.rst.states.Inliner object.
lineno: int
The line number where the interpreted text begins.
name: str
The role name actually used in the document.
options: dict[str, Any]
A dictionary of directive options for customisation (from
the "role" directive).
rawtext: str
A string containing the entire interpreted text input.
text: str
The interpreted text content.
class sphinx.util.docutils.ReferenceRole
A base class for reference roles.
The reference roles can accept link title style as a
text for the role. The parsed result; link title and target
will be stored to self.title and self.target.
disabled: bool
A boolean indicates the reference is disabled.
has_explicit_title: bool
A boolean indicates the role has explicit title or not.
target: str
The link target for the interpreted text.
title: str
The link title for the interpreted text.
class sphinx.transforms.post_transforms.images.ImageConverter(*args:
Any, **kwargs: Any)
A base class for image converters.
An image converter is kind of Docutils transform module. It is
used to convert image files which are not supported by a builder
to the appropriate format for that builder.
For example, LaTeX builder supports PDF, PNG and JPEG as image
formats. However it does not support SVG images. For such
case, using image converters allows to embed these unsupported
images into the document. One of the image converters;
sphinx.ext.imgconverter can convert a SVG image to PNG format
using Imagemagick internally.
There are three steps to make your custom image converter:
1. Make a subclass of ImageConverter class
2. Override conversion_rules, is_available() and convert()
3. Register your image converter to Sphinx using
Sphinx.add_post_transform()
convert(_from: str, _to: str) -> bool
Convert an image file to the expected format.
_from is a path of the source image file, and _to is a
path of the destination file.
is_available() -> bool
Return the image converter is available or not.
available: bool | None = None
The converter is available or not. Will be filled at the
first call of the build. The result is shared in the
same process.
Todo
This should be refactored not to store the state without class
variable.
conversion_rules: list[tuple[str, str]] = []
A conversion rules the image converter supports. It is
represented as a list of pair of source image format
(mimetype) and destination one:
conversion_rules = [
('image/svg+xml', 'image/png'),
('image/gif', 'image/png'),
('application/pdf', 'image/png'),
]
default_priority = 200
Numerical priority of this transform, 0 through 999
(override).
Utility components
class sphinx.events.EventManager(app: Sphinx)
Event manager for Sphinx.
add(name: str) -> None
Register a custom Sphinx event.
connect(name: str, callback: Callable, priority: int) -> int
Connect a handler to specific event.
disconnect(listener_id: int) -> None
Disconnect a handler.
emit(name: str, *args: Any, allowed_exceptions:
tuple[type[Exception], ...] = ()) -> list
Emit a Sphinx event.
emit_firstresult(name: str, *args: Any, allowed_exceptions:
tuple[type[Exception], ...] = ()) -> Any
Emit a Sphinx event and returns first result.
This returns the result of the first handler that doesn't
return None.
Utility types
class sphinx.util.typing.ExtensionMetadata
The metadata returned by an extension's setup() function.
See Extension metadata.
env_version: int
An integer that identifies the version of env data added
by the extension.
parallel_read_safe: bool
Indicate whether parallel reading of source files is
supported by the extension.
parallel_write_safe: bool
Indicate whether parallel writing of output files is
supported by the extension (default: True).
version: str
The extension version (default: 'unknown version').
Deprecated APIs
On developing Sphinx, we are always careful to the compatibility of our
APIs. But, sometimes, the change of interface are needed for some
reasons. In such cases, we've marked them as deprecated. And they are
kept during the two major versions (for more details, please see
Deprecation policy).
The following is a list of deprecated interfaces.
deprecated APIs
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|Target | Deprecated | Removed | Alternatives |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.testing.util.strip_escseq | 7.3 | 9.0 | sphinx.util.console.strip_colors |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|Old-style Makefiles in sphinx-quickstart and the -M, -m, | 7.3 | 9.0 | Vendoring the old style Makefile templates |
|--no-use-make-mode, and --use-make-mode options | | | |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.preserve_defaults.get_function_def() | 7.2 | 9.0 | N/A (replacement is private) |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.html.StandaloneHTMLBuilder.css_files | 7.2 | 9.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.html.StandaloneHTMLBuilder.script_files | 7.2 | 9.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.html.Stylesheet | 7.2 | 9.0 | sphinx.application.Sphinx.add_css_file() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.html.JavaScript | 7.2 | 9.0 | sphinx.application.Sphinx.add_js_file() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.split_into | 7.2 | 9.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.split_index_msg | 7.2 | 9.0 | sphinx.util.index_entries.split_index_msg |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.testing.path | 7.2 | 9.0 | os.path or pathlib |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.md5 | 7.2 | 9.0 | hashlib.md5 |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.sha1 | 7.2 | 9.0 | hashlib.sha1 |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.osutil.cd | 6.2 | 8.0 | contextlib.chdir |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.save_traceback | 6.1 | 8.0 | sphinx.util.exceptions.save_traceback |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.format_exception_cut_frames | 6.1 | 8.0 | sphinx.util.exceptions.format_exception_cut_frames |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.epoch_to_rfc1123 | 6.1 | 8.0 | sphinx.util.http_date.epoch_to_rfc1123 |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.rfc1123_to_epoch | 6.1 | 8.0 | sphinx.util.http_date.rfc1123_to_epoch |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.status_iterator | 6.1 | 8.0 | sphinx.util.display.status_iterator |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.display_chunk | 6.1 | 8.0 | sphinx.util.display.display_chunk |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.SkipProgressMessage | 6.1 | 8.0 | sphinx.util.display.SkipProgressMessage |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.progress_message | 6.1 | 8.0 | sphinx.util.display.progress_message |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.typing.stringify | 6.1 | 8.0 | sphinx.util.typing.stringify_annotation |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|HTML 4 support | 5.2 | 7.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.path_stabilize | 5.1 | 7.0 | sphinx.util.osutil.path_stabilize |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.get_matching_files | 5.1 | 7.0 | sphinx.util.matching.get_matching_files |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.napoleon.iterators | 5.1 | 7.0 | pockets.iterators |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.stemmer | 5.1 | 7.0 | snowballstemmer |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.jsdump | 5.0 | 7.0 | The standard library json module. |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|The Setuptools integration (setup.py build_sphinx) | 5.0 | 7.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|The locale argument of sphinx.util.i18n:babel_format_date() | 5.0 | 7.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|The language argument of sphinx.util.i18n:format_date() | 5.0 | 7.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.html.html5_ready | 5.0 | 7.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.io.read_doc() | 5.0 | 7.0 | sphinx.builders.Builder.read_doc() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.docutils.__version_info__ | 5.0 | 7.0 | docutils.__version_info__ |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.docutils.is_html5_writer_available() | 5.0 | 7.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LaTeXWriter.docclasses | 5.0 | 7.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.napoleon.docstring.GoogleDocstring._qualify_name() | 4.5 | 6.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.AttributeDocumenter._datadescriptor | 4.3 | 6.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.html.HTMLTranslator._fieldlist_row_index | 4.3 | 6.0 | sphinx.writers.html.HTMLTranslator._fieldlist_row_indices |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.html.HTMLTranslator._table_row_index | 4.3 | 6.0 | sphinx.writers.html.HTMLTranslator._table_row_indices |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.html5.HTML5Translator._fieldlist_row_index | 4.3 | 6.0 | sphinx.writers.html5.HTML5Translator._fieldlist_row_indices |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.html5.HTML5Translator._table_row_index | 4.3 | 6.0 | sphinx.writers.html5.HTML5Translator._table_row_indices |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|The optional argument app for sphinx.environment.BuildEnvironment | 4.1 | 6.0 | The required argument |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.application.Sphinx.html_theme | 4.1 | 6.0 | sphinx.registry.SphinxComponentRegistry.html_themes |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autosummary._app | 4.1 | 6.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.docstrings.extract_metadata() | 4.1 | 6.0 | sphinx.util.docstrings.separate_metadata() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|favicon variable in HTML templates | 4.0 | 6.0 | favicon_url |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|logo variable in HTML templates | 4.0 | 6.0 | logo_url |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.directives.patches.ListTable | 4.0 | 6.0 | docutils.parsers.rst.directives.tables.ListSVTable |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.directives.patches.RSTTable | 4.0 | 6.0 | docutils.parsers.rst.directives.tables.RSTTable |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.directive.DocumenterBridge.filename_set | 4.0 | 6.0 | sphinx.ext.autodoc.directive.DocumenterBridge.record_dependencies |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.directive.DocumenterBridge.warn() | 4.0 | 6.0 | Logging API |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.registry.SphinxComponentRegistry.get_source_input() | 4.0 | 6.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.registry.SphinxComponentRegistry.source_inputs | 4.0 | 6.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.transforms.FigureAligner | 4.0 | 6.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.pycompat.convert_with_2to3() | 4.0 | 6.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.pycompat.execfile_() | 4.0 | 6.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.smartypants | 4.0 | 6.0 | docutils.utils.smartquotes |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.typing.DirectiveOption | 4.0 | 6.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|pending_xref node for viewcode extension | 3.5 | 5.0 | sphinx.ext.viewcode.viewcode_anchor |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.linkcheck.CheckExternalLinksBuilder.anchors_ignore | 3.5 | 5.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.linkcheck.CheckExternalLinksBuilder.auth | 3.5 | 5.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.linkcheck.CheckExternalLinksBuilder.broken | 3.5 | 5.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.linkcheck.CheckExternalLinksBuilder.good | 3.5 | 5.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.linkcheck.CheckExternalLinksBuilder.redirected | 3.5 | 5.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.linkcheck.CheckExternalLinksBuilder.rqueue | 3.5 | 5.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.linkcheck.CheckExternalLinksBuilder.to_ignore | 3.5 | 5.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.linkcheck.CheckExternalLinksBuilder.workers | 3.5 | 5.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.linkcheck.CheckExternalLinksBuilder.wqueue | 3.5 | 5.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.linkcheck.node_line_or_0() | 3.5 | 5.0 | sphinx.util.nodes.get_node_line() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.AttributeDocumenter.isinstanceattribute() | 3.5 | 5.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.importer.get_module_members() | 3.5 | 5.0 | sphinx.ext.autodoc.ModuleDocumenter.get_module_members() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autosummary.generate._simple_info() | 3.5 | 5.0 | Logging API |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autosummary.generate._simple_warn() | 3.5 | 5.0 | Logging API |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.html.HTMLTranslator.permalink_text | 3.5 | 5.0 | html_permalinks_icon |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.html5.HTML5Translator.permalink_text | 3.5 | 5.0 | html_permalinks_icon |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|The follow_wrapped argument of sphinx.util.inspect.signature() | 3.4 | 5.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|The no_docstring argument of | 3.4 | 5.0 | sphinx.ext.autodoc.Documenter.get_doc() |
|sphinx.ext.autodoc.Documenter.add_content() | | | |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.Documenter.get_object_members() | 3.4 | 6.0 | sphinx.ext.autodoc.ClassDocumenter.get_object_members() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.DataDeclarationDocumenter | 3.4 | 5.0 | sphinx.ext.autodoc.DataDocumenter |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.GenericAliasDocumenter | 3.4 | 5.0 | sphinx.ext.autodoc.DataDocumenter |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.InstanceAttributeDocumenter | 3.4 | 5.0 | sphinx.ext.autodoc.AttributeDocumenter |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.SlotsAttributeDocumenter | 3.4 | 5.0 | sphinx.ext.autodoc.AttributeDocumenter |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.TypeVarDocumenter | 3.4 | 5.0 | sphinx.ext.autodoc.DataDocumenter |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.directive.DocumenterBridge.reporter | 3.5 | 5.0 | sphinx.util.logging |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.importer._getannotations() | 3.4 | 4.0 | sphinx.util.inspect.getannotations() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.importer._getmro() | 3.4 | 4.0 | sphinx.util.inspect.getmro() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.pycode.ModuleAnalyzer.parse() | 3.4 | 5.0 | sphinx.pycode.ModuleAnalyzer.analyze() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.osutil.movefile() | 3.4 | 5.0 | os.replace() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.requests.is_ssl_error() | 3.4 | 5.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.latex.LaTeXBuilder.usepackages | 3.3 | 5.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.latex.LaTeXBuilder.usepackages_afger_hyperref | 3.3 | 5.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.SingledispatchFunctionDocumenter | 3.3 | 5.0 | sphinx.ext.autodoc.FunctionDocumenter |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.SingledispatchMethodDocumenter | 3.3 | 5.0 | sphinx.ext.autodoc.MethodDocumenter |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.members_set_option() | 3.2 | 5.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.merge_special_members_option() | 3.2 | 5.0 | sphinx.ext.autodoc.merge_members_option() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.texinfo.TexinfoWriter.desc | 3.2 | 5.0 | sphinx.writers.texinfo.TexinfoWriter.descs |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|The first argument for | 3.1 | 5.0 | N/A |
|sphinx.ext.autosummary.generate.AutosummaryRenderer has been | | | |
|changed to Sphinx object | | | |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autosummary.generate.AutosummaryRenderer takes an | 3.1 | 5.0 | N/A |
|object type as an argument | | | |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|The ignore argument of sphinx.ext.autodoc.Documenter.get_doc() | 3.1 | 5.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|The template_dir argument of | 3.1 | 5.0 | N/A |
|sphinx.ext.autosummary.generate.AutosummaryRenderer | | | |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|The module argument of | 3.0 | 5.0 | N/A |
|sphinx.ext.autosummary.generate.find_autosummary_in_docstring() | | | |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|The builder argument of | 3.1 | 5.0 | N/A |
|sphinx.ext.autosummary.generate.generate_autosummary_docs() | | | |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|The template_dir argument of | 3.1 | 5.0 | N/A |
|sphinx.ext.autosummary.generate.generate_autosummary_docs() | | | |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autosummary.generate.AutosummaryRenderer.exists() | 3.1 | 5.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|The ignore argument of sphinx.util.docstring.prepare_docstring() | 3.1 | 5.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.rpartition() | 3.1 | 5.0 | str.rpartition() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|desc_signature['first'] | | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.directives.DescDirective | 3.0 | 5.0 | sphinx.directives.ObjectDescription |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.domains.std.StandardDomain.add_object() | 3.0 | 5.0 | sphinx.domains.std.StandardDomain.note_object() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.domains.python.PyDecoratorMixin | 3.0 | 5.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.get_documenters() | 3.0 | 5.0 | sphinx.registry.documenters |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autosummary.process_autosummary_toc() | 3.0 | 5.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.parsers.Parser.app | 3.0 | 5.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.testing.path.Path.text() | 3.0 | 5.0 | sphinx.testing.path.Path.read_text() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.testing.path.Path.bytes() | 3.0 | 5.0 | sphinx.testing.path.Path.read_bytes() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.inspect.getargspec() | 3.0 | 5.0 | inspect.getargspec() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LaTeXWriter.format_docclass() | 3.0 | 5.0 | LaTeX Themes |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|decode argument of sphinx.pycode.ModuleAnalyzer() | 2.4 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.directives.other.Index | 2.4 | 4.0 | sphinx.domains.index.IndexDirective |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.environment.temp_data['gloss_entries'] | 2.4 | 4.0 | documents.nameids |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.environment.BuildEnvironment.indexentries | 2.4 | 4.0 | sphinx.domains.index.IndexDomain |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.environment.collectors.indexentries.IndexEntriesCollector | 2.4 | 4.0 | sphinx.domains.index.IndexDomain |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.io.FiletypeNotFoundError | 2.4 | 4.0 | sphinx.errors.FiletypeNotFoundError |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.apidoc.INITPY | 2.4 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.apidoc.shall_skip() | 2.4 | 4.0 | sphinx.ext.apidoc.is_skipped_package |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.io.get_filetype() | 2.4 | 4.0 | sphinx.util.get_filetype() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.pycode.ModuleAnalyzer.encoding | 2.4 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.roles.Index | 2.4 | 4.0 | sphinx.domains.index.IndexRole |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.detect_encoding() | 2.4 | 4.0 | tokenize.detect_encoding() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.get_module_source() | 2.4 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.inspect.Signature | 2.4 | 4.0 | sphinx.util.inspect.signature and sphinx.util.inspect.stringify_signature() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.inspect.safe_getmembers() | 2.4 | 4.0 | inspect.getmembers() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LaTeXTranslator.settings.author | 2.4 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LaTeXTranslator.settings.contentsname | 2.4 | 4.0 | document['contentsname'] |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LaTeXTranslator.settings.docclass | 2.4 | 4.0 | document['docclass'] |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LaTeXTranslator.settings.docname | 2.4 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LaTeXTranslator.settings.title | 2.4 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.ADDITIONAL_SETTINGS | 2.4 | 4.0 | sphinx.builders.latex.constants.ADDITIONAL_SETTINGS |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.DEFAULT_SETTINGS | 2.4 | 4.0 | sphinx.builders.latex.constants.DEFAULT_SETTINGS |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LUALATEX_DEFAULT_FONTPKG | 2.4 | 4.0 | sphinx.builders.latex.constants.LUALATEX_DEFAULT_FONTPKG |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.PDFLATEX_DEFAULT_FONTPKG | 2.4 | 4.0 | sphinx.builders.latex.constants.PDFLATEX_DEFAULT_FONTPKG |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.XELATEX_DEFAULT_FONTPKG | 2.4 | 4.0 | sphinx.builders.latex.constants.XELATEX_DEFAULT_FONTPKG |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.XELATEX_GREEK_DEFAULT_FONTPKG | 2.4 | 4.0 | sphinx.builders.latex.constants.XELATEX_GREEK_DEFAULT_FONTPKG |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.gettext.POHEADER | 2.3 | 4.0 | sphinx/templates/gettext/message.pot_t (template file) |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.io.SphinxStandaloneReader.app | 2.3 | 4.0 | sphinx.io.SphinxStandaloneReader.setup() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.io.SphinxStandaloneReader.env | 2.3 | 4.0 | sphinx.io.SphinxStandaloneReader.setup() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.texescape.tex_escape_map | 2.3 | 4.0 | sphinx.util.texescape.escape() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.texescape.tex_hl_escape_map_new | 2.3 | 4.0 | sphinx.util.texescape.hlescape() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LaTeXTranslator.no_contractions | 2.3 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.domains.math.MathDomain.add_equation() | 2.2 | 4.0 | sphinx.domains.math.MathDomain.note_equation() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.domains.math.MathDomain.get_next_equation_number() | 2.2 | 4.0 | sphinx.domains.math.MathDomain.note_equation() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|The info and warn arguments of | 2.2 | 4.0 | logging.info() and logging.warning() |
|sphinx.ext.autosummary.generate.generate_autosummary_docs() | | | |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autosummary.generate._simple_info() | 2.2 | 4.0 | logging.info() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autosummary.generate._simple_warn() | 2.2 | 4.0 | logging.warning() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.todo.merge_info() | 2.2 | 4.0 | sphinx.ext.todo.TodoDomain |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.todo.process_todo_nodes() | 2.2 | 4.0 | sphinx.ext.todo.TodoDomain |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.todo.process_todos() | 2.2 | 4.0 | sphinx.ext.todo.TodoDomain |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.todo.purge_todos() | 2.2 | 4.0 | sphinx.ext.todo.TodoDomain |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.latex.LaTeXBuilder.apply_transforms() | 2.1 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders._epub_base.EpubBuilder.esc() | 2.1 | 4.0 | html.escape() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.directives.Acks | 2.1 | 4.0 | sphinx.directives.other.Acks |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.directives.Author | 2.1 | 4.0 | sphinx.directives.other.Author |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.directives.Centered | 2.1 | 4.0 | sphinx.directives.other.Centered |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.directives.Class | 2.1 | 4.0 | sphinx.directives.other.Class |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.directives.CodeBlock | 2.1 | 4.0 | sphinx.directives.code.CodeBlock |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.directives.Figure | 2.1 | 4.0 | sphinx.directives.patches.Figure |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.directives.HList | 2.1 | 4.0 | sphinx.directives.other.HList |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.directives.Highlight | 2.1 | 4.0 | sphinx.directives.code.Highlight |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.directives.Include | 2.1 | 4.0 | sphinx.directives.other.Include |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.directives.Index | 2.1 | 4.0 | sphinx.directives.other.Index |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.directives.LiteralInclude | 2.1 | 4.0 | sphinx.directives.code.LiteralInclude |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.directives.Meta | 2.1 | 4.0 | sphinx.directives.patches.Meta |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.directives.Only | 2.1 | 4.0 | sphinx.directives.other.Only |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.directives.SeeAlso | 2.1 | 4.0 | sphinx.directives.other.SeeAlso |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.directives.TabularColumns | 2.1 | 4.0 | sphinx.directives.other.TabularColumns |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.directives.TocTree | 2.1 | 4.0 | sphinx.directives.other.TocTree |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.directives.VersionChange | 2.1 | 4.0 | sphinx.directives.other.VersionChange |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.domains.python.PyClassmember | 2.1 | 4.0 | sphinx.domains.python.PyAttribute, sphinx.domains.python.PyMethod, |
| | | | sphinx.domains.python.PyClassMethod, sphinx.domains.python.PyObject and |
| | | | sphinx.domains.python.PyStaticMethod |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.domains.python.PyModulelevel | 2.1 | 4.0 | sphinx.domains.python.PyFunction, sphinx.domains.python.PyObject and |
| | | | sphinx.domains.python.PyVariable |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.domains.std.StandardDomain._resolve_citation_xref() | 2.1 | 4.0 | sphinx.domains.citation.CitationDomain.resolve_xref() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.domains.std.StandardDomain.note_citations() | 2.1 | 4.0 | sphinx.domains.citation.CitationDomain.note_citation() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.domains.std.StandardDomain.note_citation_refs() | 2.1 | 4.0 | sphinx.domains.citation.CitationDomain.note_citation_reference() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.domains.std.StandardDomain.note_labels() | 2.1 | 4.0 | sphinx.domains.std.StandardDomain.process_doc() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.domains.js.JSObject.display_prefix | | 4.3 | sphinx.domains.js.JSObject.get_display_prefix() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.environment.NoUri | 2.1 | 3.0 | sphinx.errors.NoUri |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.apidoc.format_directive() | 2.1 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.apidoc.format_heading() | 2.1 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.apidoc.makename() | 2.1 | 4.0 | sphinx.ext.apidoc.module_join() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.importer.MockFinder | 2.1 | 4.0 | sphinx.ext.autodoc.mock.MockFinder |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.importer.MockLoader | 2.1 | 4.0 | sphinx.ext.autodoc.mock.MockLoader |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.importer.mock() | 2.1 | 4.0 | sphinx.ext.autodoc.mock.mock() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autosummary.autolink_role() | 2.1 | 4.0 | sphinx.ext.autosummary.AutoLink |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.imgmath.DOC_BODY | 2.1 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.imgmath.DOC_BODY_PREVIEW | 2.1 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.imgmath.DOC_HEAD | 2.1 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.transforms.CitationReferences | 2.1 | 4.0 | sphinx.domains.citation.CitationReferenceTransform |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.transforms.SmartQuotesSkipper | 2.1 | 4.0 | sphinx.domains.citation.CitationDefinitionTransform |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.docfields.DocFieldTransformer.preprocess_fieldtypes() | 2.1 | 4.0 | sphinx.directives.ObjectDescription.get_field_type_map() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.node.find_source_node() | 2.1 | 4.0 | sphinx.util.node.get_node_source() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.i18n.find_catalog() | 2.1 | 4.0 | sphinx.util.i18n.docname_to_domain() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.i18n.find_catalog_files() | 2.1 | 4.0 | sphinx.util.i18n.CatalogRepository |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.i18n.find_catalog_source_files() | 2.1 | 4.0 | sphinx.util.i18n.CatalogRepository |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|encoding argument of autodoc.Documenter.get_doc(), | 2.0 | 4.0 | N/A |
|autodoc.DocstringSignatureMixin.get_doc(), | | | |
|autodoc.DocstringSignatureMixin._find_signature(), and | | | |
|autodoc.ClassDocumenter.get_doc() | | | |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|arguments of EpubBuilder.build_mimetype(), | 2.0 | 4.0 | N/A |
|EpubBuilder.build_container(), EpubBuilder.build_content(), | | | |
|EpubBuilder.build_toc() and EpubBuilder.build_epub() | | | |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|arguments of Epub3Builder.build_navigation_doc() | 2.0 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|nodetype argument of | 2.0 | 4.0 | N/A |
|sphinx.search.WordCollector.is_meta_keywords() | | | |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|suffix argument of BuildEnvironment.doc2path() | 2.0 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|string style base argument of BuildEnvironment.doc2path() | 2.0 | 4.0 | os.path.join() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.addnodes.abbreviation | 2.0 | 4.0 | docutils.nodes.abbreviation |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.applehelp | 2.0 | 4.0 | sphinxcontrib.applehelp |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.devhelp | 2.0 | 4.0 | sphinxcontrib.devhelp |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.epub3.Epub3Builder.validate_config_value() | 2.0 | 4.0 | sphinx.builders.epub3.validate_config_values() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.html.JSONHTMLBuilder | 2.0 | 4.0 | sphinx.builders.serializinghtml.JSONHTMLBuilder |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.html.PickleHTMLBuilder | 2.0 | 4.0 | sphinx.builders.serializinghtml.PickleHTMLBuilder |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.html.SerializingHTMLBuilder | 2.0 | 4.0 | sphinx.builders.serializinghtml.SerializingHTMLBuilder |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.html.SingleFileHTMLBuilder | 2.0 | 4.0 | sphinx.builders.singlehtml.SingleFileHTMLBuilder |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.html.WebHTMLBuilder | 2.0 | 4.0 | sphinx.builders.serializinghtml.PickleHTMLBuilder |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.htmlhelp | 2.0 | 4.0 | sphinxcontrib.htmlhelp |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.htmlhelp.HTMLHelpBuilder.open_file() | 2.0 | 4.0 | open() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.builders.qthelp | 2.0 | 4.0 | sphinxcontrib.qthelp |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.cmd.quickstart.term_decode() | 2.0 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.cmd.quickstart.TERM_ENCODING | 2.0 | 4.0 | sys.stdin.encoding |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.config.check_unicode() | 2.0 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.config.string_classes | 2.0 | 4.0 | [str] |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.domains.cpp.DefinitionError.description | 2.0 | 4.0 | str(exc) |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.domains.cpp.NoOldIdError.description | 2.0 | 4.0 | str(exc) |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded | 2.0 | 4.0 | str(exc) |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autosummary.Autosummary.warn() | 2.0 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autosummary.Autosummary.genopt | 2.0 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autosummary.Autosummary.warnings | 2.0 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autosummary.Autosummary.result | 2.0 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.doctest.doctest_encode() | 2.0 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.jsmath | 2.0 | 4.0 | sphinxcontrib.jsmath |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.roles.abbr_role() | 2.0 | 4.0 | sphinx.roles.Abbreviation |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.roles.emph_literal_role() | 2.0 | 4.0 | sphinx.roles.EmphasizedLiteral |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.roles.menusel_role() | 2.0 | 4.0 | sphinx.roles.GUILabel or sphinx.roles.MenuSelection |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.roles.index_role() | 2.0 | 4.0 | sphinx.roles.Index |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.roles.indexmarkup_role() | 2.0 | 4.0 | sphinx.roles.PEP or sphinx.roles.RFC |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.testing.util.remove_unicode_literal() | 2.0 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.attrdict | 2.0 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.force_decode() | 2.0 | 5.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.get_matching_docs() | 2.0 | 4.0 | sphinx.util.get_matching_files() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.inspect.Parameter | 2.0 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.jsonimpl | 2.0 | 4.0 | sphinxcontrib.serializinghtml.jsonimpl |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.osutil.EEXIST | 2.0 | 4.0 | errno.EEXIST or FileExistsError |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.osutil.EINVAL | 2.0 | 4.0 | errno.EINVAL |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.osutil.ENOENT | 2.0 | 4.0 | errno.ENOENT or FileNotFoundError |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.osutil.EPIPE | 2.0 | 4.0 | errno.ENOENT or BrokenPipeError |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.osutil.walk() | 2.0 | 4.0 | os.walk() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.pycompat.NoneType | 2.0 | 4.0 | sphinx.util.typing.NoneType |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.pycompat.TextIOWrapper | 2.0 | 4.0 | io.TextIOWrapper |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.pycompat.UnicodeMixin | 2.0 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.pycompat.htmlescape() | 2.0 | 4.0 | html.escape() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.pycompat.indent() | 2.0 | 4.0 | textwrap.indent() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.pycompat.sys_encoding | 2.0 | 4.0 | sys.getdefaultencoding() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.pycompat.terminal_safe() | 2.0 | 4.0 | sphinx.util.console.terminal_safe() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.pycompat.u | 2.0 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.PeekableIterator | 2.0 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|Omitting the filename argument in an overriddent | 2.0 | 4.0 | IndexBuilder.feed(docname, filename, title, doctree) |
|IndexBuilder.feed() method. | | | |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.ExtBabel | 2.0 | 4.0 | sphinx.builders.latex.util.ExtBabel |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LaTeXTranslator.babel_defmacro() | 2.0 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.application.Sphinx._setting_up_extension | 2.0 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|The importer argument of sphinx.ext.autodoc.importer._MockModule | 2.0 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.importer._MockImporter | 2.0 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.io.SphinxBaseFileInput | 2.0 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.io.SphinxFileInput.supported | 2.0 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.io.SphinxRSTFileInput | 2.0 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.registry.SphinxComponentRegistry.add_source_input() | 2.0 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LaTeXTranslator._make_visit_admonition() | 2.0 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LaTeXTranslator.collect_footnotes() | 2.0 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition() | 2.0 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.text.TextTranslator._make_depart_admonition() | 2.0 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LaTeXTranslator.generate_numfig_format() | 2.0 | 4.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|highlightlang | 1.8 | 4.0 | highlight |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|add_stylesheet() | 1.8 | 6.0 | add_css_file() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|add_javascript() | 1.8 | 4.0 | add_js_file() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|autodoc_default_flags | 1.8 | 4.0 | autodoc_default_options |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|content arguments of sphinx.util.image.guess_mimetype() | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|gettext_compact arguments of | 1.8 | 3.0 | N/A |
|sphinx.util.i18n.find_catalog_source_files() | | | |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.io.SphinxI18nReader.set_lineno_for_reporter() | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.io.SphinxI18nReader.line | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.directives.other.VersionChanges | 1.8 | 3.0 | sphinx.domains.changeset.VersionChanges |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.highlighting.PygmentsBridge.unhighlight() | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|trim_doctest_flags arguments of sphinx.highlighting.PygmentsBridge | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.mathbase | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.mathbase.MathDomain | 1.8 | 3.0 | sphinx.domains.math.MathDomain |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.mathbase.MathDirective | 1.8 | 3.0 | sphinx.directives.patches.MathDirective |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.mathbase.math_role() | 1.8 | 3.0 | docutils.parsers.rst.roles.math_role() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.mathbase.setup_math() | 1.8 | 3.0 | add_html_math_renderer() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.mathbase.is_in_section_title() | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.mathbase.get_node_equation_number() | 1.8 | 3.0 | sphinx.util.math.get_node_equation_number() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.mathbase.wrap_displaymath() | 1.8 | 3.0 | sphinx.util.math.wrap_displaymath() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.mathbase.math (node) | 1.8 | 3.0 | docutils.nodes.math |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.mathbase.displaymath (node) | 1.8 | 3.0 | docutils.nodes.math_block |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.mathbase.eqref (node) | 1.8 | 3.0 | sphinx.builders.latex.nodes.math_reference |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|viewcode_import (config value) | 1.8 | 3.0 | viewcode_follow_imported_members |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.Table.caption_footnotetexts | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.Table.header_footnotetexts | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LaTeXTranslator.footnotestack | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LaTeXTranslator.in_container_literal_block | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LaTeXTranslator.next_section_ids | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LaTeXTranslator.restrict_footnote() | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote() | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids() | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids() | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LaTeXTranslator.bibitems | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LaTeXTranslator.hlsettingstack | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.ExtBabel.get_shorthandoff() | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.html.HTMLTranslator.highlightlang() | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.html.HTMLTranslator.highlightlang_base() | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.html.HTMLTranslator.highlightlangopts() | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.html.HTMLTranslator.highlightlinenothreshold() | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.html5.HTMLTranslator.highlightlang() | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.html5.HTMLTranslator.highlightlang_base() | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.html5.HTMLTranslator.highlightlangopts() | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold() | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.writers.latex.LaTeXTranslator.check_latex_elements() | 1.8 | 3.0 | Nothing |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.application.CONFIG_FILENAME | 1.8 | 3.0 | sphinx.config.CONFIG_FILENAME |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|Config.check_unicode() | 1.8 | 3.0 | sphinx.config.check_unicode() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|Config.check_types() | 1.8 | 3.0 | sphinx.config.check_confval_types() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|dirname, filename and tags arguments of Config.__init__() | 1.8 | 3.0 | Config.read() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|The value of html_search_options | 1.8 | 3.0 | see html_search_options |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.versioning.prepare() | 1.8 | 3.0 | sphinx.versioning.UIDTransform |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|Sphinx.override_domain() | 1.8 | 3.0 | add_domain() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|Sphinx.import_object() | 1.8 | 3.0 | sphinx.util.import_object() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|suffix argument of add_source_parser() | 1.8 | 3.0 | add_source_suffix() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|BuildEnvironment.load() | 1.8 | 3.0 | pickle.load() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|BuildEnvironment.loads() | 1.8 | 3.0 | pickle.loads() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|BuildEnvironment.frompickle() | 1.8 | 3.0 | pickle.load() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|BuildEnvironment.dump() | 1.8 | 3.0 | pickle.dump() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|BuildEnvironment.dumps() | 1.8 | 3.0 | pickle.dumps() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|BuildEnvironment.topickle() | 1.8 | 3.0 | pickle.dump() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|BuildEnvironment._nitpick_ignore | 1.8 | 3.0 | nitpick_ignore |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|BuildEnvironment.versionchanges | 1.8 | 3.0 | N/A |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|BuildEnvironment.update() | 1.8 | 3.0 | Builder.read() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|BuildEnvironment.read_doc() | 1.8 | 3.0 | Builder.read_doc() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|BuildEnvironment._read_serial() | 1.8 | 3.0 | Builder.read() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|BuildEnvironment._read_parallel() | 1.8 | 3.0 | Builder.read() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|BuildEnvironment.write_doctree() | 1.8 | 3.0 | Builder.write_doctree() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|BuildEnvironment.note_versionchange() | 1.8 | 3.0 | ChangesDomain.note_changeset() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|warn() (template helper function) | 1.8 | 3.0 | warning() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|source_parsers | 1.8 | 3.0 | add_source_parser() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.docutils.directive_helper() | 1.8 | 3.0 | Directive class of docutils |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.cmdline | 1.8 | 3.0 | sphinx.cmd.build |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.make_mode | 1.8 | 3.0 | sphinx.cmd.make_mode |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.locale.l_() | 1.8 | 3.0 | sphinx.locale._() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.locale.lazy_gettext() | 1.8 | 3.0 | sphinx.locale._() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.locale.mygettext() | 1.8 | 3.0 | sphinx.locale._() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.copy_static_entry() | 1.5 | 3.0 | sphinx.util.fileutil.copy_asset() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.build_main() | 1.7 | 2.0 | sphinx.cmd.build.build_main() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.intersphinx.debug() | 1.7 | 2.0 | sphinx.ext.intersphinx.inspect_main() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.format_annotation() | 1.7 | 2.0 | sphinx.util.inspect.Signature |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.formatargspec() | 1.7 | 2.0 | sphinx.util.inspect.Signature |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.AutodocReporter | 1.7 | 2.0 | sphinx.util.docutils.switch_source_input() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.add_documenter() | 1.7 | 2.0 | add_autodocumenter() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.ext.autodoc.AutoDirective._register | 1.7 | 2.0 | add_autodocumenter() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|AutoDirective._special_attrgetters | 1.7 | 2.0 | add_autodoc_attrgetter() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|Sphinx.warn(), Sphinx.info() | 1.6 | 2.0 | Logging API |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|BuildEnvironment.set_warnfunc() | 1.6 | 2.0 | Logging API |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|BuildEnvironment.note_toctree() | 1.6 | 2.0 | Toctree.note() (in sphinx.environment.adapters.toctree) |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|BuildEnvironment.get_toc_for() | 1.6 | 2.0 | Toctree.get_toc_for() (in sphinx.environment.adapters.toctree) |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|BuildEnvironment.get_toctree_for() | 1.6 | 2.0 | Toctree.get_toctree_for() (in sphinx.environment.adapters.toctree) |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|BuildEnvironment.create_index() | 1.6 | 2.0 | IndexEntries.create_index() (in sphinx.environment.adapters.indexentries) |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.websupport | 1.6 | 2.0 | sphinxcontrib-websupport |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|StandaloneHTMLBuilder.css_files | 1.6 | 2.0 | add_stylesheet() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|document.settings.gettext_compact | 1.8 | 1.8 | gettext_compact |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|Sphinx.status_iterator() | 1.6 | 1.7 | sphinx.util.status_iterator() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|Sphinx.old_status_iterator() | 1.6 | 1.7 | sphinx.util.old_status_iterator() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|Sphinx._directive_helper() | 1.6 | 1.7 | sphinx.util.docutils.directive_helper() |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.compat.Directive | 1.6 | 1.7 | docutils.parsers.rst.Directive |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
|sphinx.util.compat.docutils_version | 1.6 | 1.7 | sphinx.util.docutils.__version_info__ |
+-------------------------------------------------------------------+------------+---------+---------------------------------------------------------------------------------------------+
NOTE:
On deprecating on public APIs (internal functions and classes), we
also follow the policy as much as possible.
COMMUNITY GUIDE
Sphinx is community supported and welcomes contributions from anybody.
The sections below should help you get started joining the Sphinx
community as well as contributing.
See the Sphinx contributors' guide if you would like to contribute to
the project.
Get support
For questions or to report problems with Sphinx, join the sphinx-users
mailing list on Google Groups, come to the #sphinx-doc channel on
libera.chat, or open an issue at the tracker.
Examples of other projects using Sphinx can be found in the examples
page. A useful tutorial has been written by the matplotlib developers.
There is a translation team in Transifex of this documentation, thanks
to the Sphinx document translators.
Contribute to Sphinx
This guide contains information about the Sphinx open source project
itself. This is where you can find information about how Sphinx is
managed and learn how to contribute to the project.
Contributing to Sphinx
There are many ways you can contribute to Sphinx, be it filing bug
reports or feature requests, writing new documentation or submitting
patches for new or fixed behavior. This guide serves to illustrate how
you can get started with this.
Get help
The Sphinx community maintains a number of mailing lists and IRC
channels.
Stack Overflow with tag python-sphinx
Questions and answers about use and development.
sphinx-users
Mailing list for user support.
sphinx-dev
Mailing list for development related discussions.
#sphinx-doc on irc.libera.chat
IRC channel for development questions and user support.
Bug Reports and Feature Requests
If you have encountered a problem with Sphinx or have an idea for a new
feature, please submit it to the issue tracker on GitHub or discuss it
on the sphinx-dev mailing list.
For bug reports, please include the output produced during the build
process and also the log file Sphinx creates after it encounters an
unhandled exception. The location of this file should be shown towards
the end of the error message.
Including or providing a link to the source files involved may help us
fix the issue. If possible, try to create a minimal project that
produces the error and post that instead.
Contribute code
The Sphinx source code is managed using Git and is hosted on GitHub.
The recommended way for new contributors to submit code to Sphinx is to
fork this repository and submit a pull request after committing changes
to their fork. The pull request will then need to be approved by one
of the core developers before it is merged into the main repository.
Getting started
Before starting on a patch, we recommend checking for open issues or
open a fresh issue to start a discussion around a feature idea or a
bug. If you feel uncomfortable or uncertain about an issue or your
changes, feel free to email the sphinx-dev mailing list.
These are the basic steps needed to start developing on Sphinx.
1. Create an account on GitHub.
2. Fork the main Sphinx repository (sphinx-doc/sphinx) using the
GitHub interface.
3. Clone the forked repository to your machine.
git clone https://github.com/USERNAME/sphinx
cd sphinx
4. Checkout the appropriate branch.
Sphinx adopts Semantic Versioning 2.0.0 (refs: https://semver.org/
).
For changes that preserves backwards-compatibility of API and
features, they should be included in the next MINOR release, use
the A.x branch.
git checkout A.x
For
incompatible
or other
substantial
changes
that
should
wait
until
the next
MAJOR
release,
use the
master
branch.
For
urgent
release,
a new
PATCH
branch
must be
branched
from the
newest
release
tag (see
Sphinx's
release
process
for
detail).
5. Setup a virtual environment.
This is not necessary for unit testing, thanks to tox, but it is
necessary if you wish to run sphinx-build locally or run unit tests
without the help of tox:
virtualenv ~/.venv
. ~/.venv/bin/activate
pip install -e .
6. Create a new working branch. Choose any name you like.
git checkout -b feature-xyz
7. Hack, hack, hack.
Write your code along with tests that shows that the bug was fixed
or that the feature works as expected.
8. Add a bullet point to CHANGES.rst if the fix or feature is not
trivial (small doc updates, typo fixes), then commit:
git commit -m '#42: Add useful new feature that does this.'
GitHub
recognizes
certain
phrases
that can
be used
to
automatically
update
the
issue
tracker.
For
example:
git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
would
close
issue
#42.
9. Push changes in the branch to your forked repository on GitHub:
git push origin feature-xyz
10. Submit a pull request from your branch to the respective branch
(master or A.x).
11. Wait for a core developer to review your changes.
Coding style
Please follow these guidelines when writing code for Sphinx:
o Try to use the same code style as used in the rest of the project.
o For non-trivial changes, please update the CHANGES.rst file. If your
changes alter existing behavior, please document this.
o New features should be documented. Include examples and use cases
where appropriate. If possible, include a sample that is displayed
in the generated output.
o When adding a new configuration variable, be sure to document it and
update sphinx/cmd/quickstart.py if it's important enough.
o Add appropriate unit tests.
Style and
type checks
can be run
as follows:
ruff .
mypy sphinx/
Unit tests
Sphinx is tested using pytest for Python code and Karma for JavaScript.
To run Python unit tests, we recommend using tox, which provides a
number of targets and allows testing against multiple different Python
environments:
o To list all possible targets:
tox -av
o To run unit tests for a specific Python version, such as Python 3.10:
tox -e py310
o To run unit tests for a specific Python version and turn on
deprecation warnings so they're shown in the test output:
PYTHONWARNINGS=error tox -e py310
o Arguments to pytest can be passed via tox, e.g., in order to run a
particular test:
tox -e py310 tests/test_module.py::test_new_feature
You can also
test by
installing
dependencies
in your
local
environment:
pip install .[test]
To run
JavaScript
tests, use
npm:
npm install
npm run test
TIP:
karma requires a Firefox binary to use as a test browser.
For Unix-based systems, you can specify the path to the Firefox
binary using:
FIREFOX_BIN="/Applications/Firefox.app/Contents/MacOS/firefox" npm test
New unit
tests should
be included
in the tests
directory
where
necessary:
o For bug fixes, first add a test that fails without your changes and
passes after they are applied.
o Tests that need a sphinx-build run should be integrated in one of the
existing test modules if possible. New tests that to @with_app and
then build_all for a few assertions are not good since the test suite
should not take more than a minute to run.
Added in
version 1.8:
Sphinx also
runs
JavaScript
tests.
Added in
version 1.6:
sphinx.testing
is added as
a
experimental.
Changed in
version
1.5.2:
Sphinx was
switched
from nose to
pytest.
Todo
The below belongs in the developer guide
Utility
functions
and pytest
fixtures for
testing are
provided in
sphinx.testing.
If you are a
developer of
Sphinx
extensions,
you can
write unit
tests by
using
pytest. At
this time,
sphinx.testing
will help
your test
implementation.
How to use
pytest
fixtures
that are
provided by
sphinx.testing?
You can
require
'sphinx.testing.fixtures'
in your test
modules or
conftest.py
files like
this:
pytest_plugins = 'sphinx.testing.fixtures'
If you
want to
know
more
detailed
usage,
please
refer to
tests/conftest.py
and
other
test_*.py
files
under
the
tests
directory.
Contribute documentation
Contributing to documentation involves modifying the source files found
in the doc/ folder. To get started, you should first follow Getting
started, and then take the steps below to work with the documentation.
The following sections describe how to get started with contributing
documentation, as well as key aspects of a few different tools that we
use.
Todo
Add a more extensive documentation contribution guide.
Build the documentation
To build the documentation, run the following command:
sphinx-build -M html ./doc ./build/sphinx -W --keep-going
This
will
parse
the
Sphinx
documentation's
source
files
and
generate
HTML
for
you
to
preview
in
build/sphinx/html.
You
can
also
build
a
live
version
of
the
documentation
that
you
can
preview
in
the
browser.
It
will
detect
changes
and
reload
the
page
any
time
you
make
edits.
To do
so,
run
the
following
command:
sphinx-autobuild ./doc ./build/sphinx/
Translations
The parts of messages in Sphinx that go into builds are translated into
several locales. The translations are kept as gettext .po files
translated from the master template sphinx/locale/sphinx.pot.
Sphinx uses Babel to extract messages and maintain the catalog files.
The utils directory contains a helper script, babel_runner.py.
o Use python babel_runner.py extract to update the .pot template.
o Use python babel_runner.py update to update all existing language
catalogs in sphinx/locale/*/LC_MESSAGES with the current messages in
the template file.
o Use python babel_runner.py compile to compile the .po files to binary
.mo files and .js files.
When
an
updated
.po
file
is
submitted,
run
python
babel_runner.py
compile
to
commit
both
the
source
and
the
compiled
catalogs.
When
a new
locale
is
submitted,
add a
new
directory
with
the
ISO
639-1
language
identifier
and
put
sphinx.po
in
there.
Don't
forget
to
update
the
possible
values
for
language
in
doc/usage/configuration.rst.
The
Sphinx
core
messages
can
also
be
translated
on
Transifex.
There
tx
client
tool,
which
is
provided
by
the
transifex_client
Python
package,
can
be
used
to
pull
translations
in
.po
format
from
Transifex.
To do
this,
go to
sphinx/locale
and
then
run
tx
pull
-f -l
LANG
where
LANG
is an
existing
language
identifier.
It is
good
practice
to
run
python
babel_runner.py
update
afterwards
to
make
sure
the
.po
file
has
the
canonical
Babel
formatting.
Debugging tips
o Delete the build cache before building documents if you make changes
in the code by running the command make clean or using the
sphinx-build -E option.
o Use the sphinx-build -P option to run pdb on exceptions.
o Use node.pformat() and node.asdom().toxml() to generate a printable
representation of the document structure.
o Set the configuration variable keep_warnings to True so warnings will
be displayed in the generated output.
o Set the configuration variable nitpicky to True so that Sphinx will
complain about references without a known target.
o Set the debugging options in the Docutils configuration file.
o JavaScript stemming algorithms in sphinx/search/non-minified-js/*.js
are generated using snowball by cloning the repository, executing
make dist_libstemmer_js and then unpacking the tarball which is
generated in dist directory.
Minified files in sphinx/search/minified-js/*.js are generated from
non-minified ones using uglifyjs (installed via npm), with -m option
to enable mangling.
Sphinx's release process
Versioning
Sphinx adheres to PEP 440 versions, with a major.minor.micro scheme for
the release segment (e.g. 1.2.3). The major, minor, and micro version
parts should be altered as follows:
o The major version part should be incremented for incompatible
behavior change and public API updates.
o The minor version part should be incremented for most releases of
Sphinx, where backwards-compatibility of API and features are
preserves.
o The micro version part should only be incremented for urgent
bugfix-only releases.
When
the
major
version
part
is
incremented,
the
minor
and
micro
version
parts
must
be
set
to 0.
When
the
minor
version
part
is
incremented,
the
micro
version
part
must
be
set
to 0.
New
major
versions
should
come
with
a
beta-testing
period
before
the
final
release.
Deprecating a feature
There are a couple reasons that code in Sphinx might be deprecated:
o If a feature has been improved or modified in a
backwards-incompatible way, the old feature or behavior will be
deprecated.
o Sometimes Sphinx will include a backport of a Python library that's
not included in a version of Python that Sphinx currently supports.
When Sphinx no longer needs to support the older version of Python
that doesn't include the library, the library will be deprecated in
Sphinx.
As
the
Deprecation
policy
describes,
the
first
release
of
Sphinx
that
deprecates
a
feature
(A.B)
should
raise
a
RemovedInSphinxXXWarning
(where
XX is
the
Sphinx
version
where
the
feature
will
be
removed)
when
the
deprecated
feature
is
invoked.
Assuming
we
have
good
test
coverage,
these
warnings
are
converted
to
errors
when
running
the
test
suite
with
warnings
enabled:
pytest -Wall
Thus,
when
adding
a
RemovedInSphinxXXWarning
you
need
to
eliminate
or
silence
any
warnings
generated
when
running
the
tests.
Deprecation policy
MAJOR and MINOR releases may deprecate certain features from previous
releases. If a feature is deprecated in a release A.x, it will continue
to work in all A.x.x versions (for all versions of x). It will continue
to work in all B.x.x versions but raise deprecation warnings.
Deprecated features will be removed at the C.0.0. It means the
deprecated feature will work during 2 MAJOR releases at least.
So, for example, if we decided to start the deprecation of a function
in Sphinx 2.x:
o Sphinx 2.x will contain a backwards-compatible replica of the
function which will raise a RemovedInSphinx40Warning. This is a
subclass of PendingDeprecationWarning, i.e. it will not get displayed
by default.
o Sphinx 3.x will still contain the backwards-compatible replica, but
RemovedInSphinx40Warning will be a subclass of DeprecationWarning
then, and gets displayed by default.
o Sphinx 4.0 will remove the feature outright.
Deprecation warnings
Sphinx will enable its RemovedInNextVersionWarning warnings by default,
if PYTHONWARNINGS is not set. Therefore you can disable them using:
o PYTHONWARNINGS= make html (Linux/Mac)
o export PYTHONWARNINGS= and do make html (Linux/Mac)
o set PYTHONWARNINGS= and do make html (Windows)
But
you
can
also
explicitly
enable
the
pending
ones
using
e.g.
PYTHONWARNINGS=default
(see
the
Python
docs
on
configuring
warnings)
for
more
details.
Python version support policy
Sphinx supports at all minor versions of Python released in the past 42
months from the anticipated release date with a minimum of 3 minor
versions of Python. This policy is derived from NEP 29, a scientific
Python domain standard.
For example, a version of Sphinx released in May 2024 would support
Python 3.10, 3.11, and 3.12.
This is a summary table with the current policy:
+------------+--------+
|Date | Python |
+------------+--------+
|26 Dec 2021 | 3.8+ |
+------------+--------+
|14 Apr 2023 | 3.9+ |
+------------+--------+
|05 Apr 2024 | 3.10+ |
+------------+--------+
|04 Apr 2025 | 3.11+ |
+------------+--------+
|24 Apr 2026 | 3.12+ |
+------------+--------+
Release procedures
The release procedures are listed in utils/release-checklist.rst.
Organization of the Sphinx project
The guide explains how the Sphinx project is organized.
Core developers
The core developers of Sphinx have write access to the main repository.
They can commit changes, accept/reject pull requests, and manage items
on the issue tracker.
Guidelines
The following are some general guidelines for core developers:
o Questionable or extensive changes should be submitted as a pull
request instead of being committed directly to the main repository.
The pull request should be reviewed by another core developer before
it is merged.
o Trivial changes can be committed directly but be sure to keep the
repository in a good working state and that all tests pass before
pushing your changes.
o When committing code written by someone else, please attribute the
original author in the commit message and any relevant CHANGES.rst
entry.
Membership
Core membership is predicated on continued active contribution to the
project. In general, prospective cores should demonstrate:
o a good understanding of one of more components of Sphinx
o a history of helpful, constructive contributions
o a willingness to invest time improving Sphinx
Refer
to
Contributing
to
Sphinx
for
more
information
on
how
you
can
get
started.
Other contributors
You do not need to be a core developer or have write access to be
involved in the development of Sphinx. You can submit patches or
create pull requests from forked repositories and have a core developer
add the changes for you.
Similarly, contributions are not limited to code patches. We also
welcome help triaging bugs, input on design decisions, reviews of
existing patches and documentation improvements. More information can
be found in Contributing to Sphinx.
A list of people that have contributed to Sphinx can be found in Sphinx
authors.
Sphinx Code of Conduct
Like the technical community as a whole, the Sphinx team and community
is made up of volunteers from all over the world. Diversity is a
strength, but it can also lead to communication issues and unhappiness.
To that end, we have a few ground rules that we ask people to adhere
to.
o Be friendly and patient.
o Be welcoming. We strive to be a community that welcomes and supports
people of all backgrounds and identities. This includes, but is not
limited to members of any race, ethnicity, culture, national origin,
colour, immigration status, social and economic class, educational
level, sex, sexual orientation, gender identity and expression, age,
size, family status, political belief, religion, and mental and
physical ability.
o Be considerate. Your work will be used by other people, and you in
turn will depend on the work of others. Any decision you take will
affect users and colleagues, and you should take those consequences
into account when making decisions. Remember that we're a world-wide
community, so you might not be communicating in someone else's
primary language.
o Be respectful. Not all of us will agree all the time, but
disagreement is no excuse for poor behavior and poor manners. We
might all experience some frustration now and then, but we cannot
allow that frustration to turn into a personal attack. It's
important to remember that a community where people feel
uncomfortable or threatened is not a productive one. Members of the
Sphinx community should be respectful when dealing with other members
as well as with people outside the Sphinx community.
o Be careful in the words that you choose. We are a community of
professionals, and we conduct ourselves professionally. Be kind to
others. Do not insult or put down other participants. Harassment and
other exclusionary behavior aren't acceptable. This includes, but is
not limited to:
o Violent threats or language directed against another person.
o Discriminatory jokes and language.
o Posting sexually explicit or violent material.
o Posting (or threatening to post) other people's personally
identifying information ("doxing").
o Personal insults, especially those using racist or sexist terms.
o Unwelcome sexual attention.
o Advocating for, or encouraging, any of the above behavior.
o Repeated harassment of others. In general, if someone asks you to
stop, then stop.
o When we disagree, try to understand why. Disagreements, both social
and technical, happen all the time and Sphinx is no exception. It is
important that we resolve disagreements and differing views
constructively. Remember that we're different. Different people have
different perspectives on issues. Being unable to understand why
someone holds a viewpoint doesn't mean that they're wrong. Don't
forget that it is human to err and blaming each other doesn't get us
anywhere. Instead, focus on helping to resolve issues and learning
from mistakes.
This
isn't
an
exhaustive
list
of
things
that
you
can't
do.
Rather,
take
it in
the
spirit
in
which
it's
intended
- a
guide
to
make
it
easier
to
enrich
all
of us
and
the
technical
communities
in
which
we
participate.
This
code
of
conduct
applies
to
all
spaces
of
the
Sphinx
community.
Attribution
Original
text
courtesy
of
the
Speak
Up!
project:
http://web.archive.org/web/20141109123859/http://speakup.io/coc.html.
Sphinx FAQ
This is a list of Frequently Asked Questions about Sphinx. Feel free
to suggest new entries!
How do I...
... create PDF files without LaTeX?
rinohtype provides a PDF builder that can be used as a drop-in
replacement for the LaTeX builder.
... get section numbers?
They are automatic in LaTeX output; for HTML, give a :numbered:
option to the toctree directive where you want to start
numbering.
... customize the look of the built HTML files?
Use themes, see HTML Theming.
... add global substitutions or includes?
Add them in the rst_prolog or rst_epilog config value.
... display the whole TOC tree in the sidebar?
Use the toctree callable in a custom layout template, probably
in the sidebartoc block.
... write my own extension?
See the Extension tutorials.
... convert from my existing docs using MoinMoin markup?
The easiest way is to convert to xhtml, then convert xhtml to
reST. You'll still need to mark up classes and such, but the
headings and code examples come through cleanly.
For
many
more
extensions
and
other
contributed
stuff,
see
the
sphinx-contrib
repository.
Using Sphinx with...
Read the Docs
Read the Docs is a documentation hosting service based around
Sphinx. They will host sphinx documentation, along with
supporting a number of other features including version support,
PDF generation, and more. The Getting Started guide is a good
place to start.
Epydoc There's a third-party extension providing an api role which
refers to Epydoc's API docs for a given identifier.
Doxygen
Michael Jones is developing a reST/Sphinx bridge to doxygen
called breathe.
SCons Glenn Hutchings has written a SCons build script to build Sphinx
documentation; it is hosted here:
https://bitbucket-archive.softwareheritage.org/projects/zo/zondo/sphinx-scons.html
PyPI Jannis Leidel wrote a setuptools command that automatically
uploads Sphinx documentation to the PyPI package documentation
area at https://pythonhosted.org/.
GitHub Pages
Please add sphinx.ext.githubpages to your project. It allows
you to publish your document in GitHub Pages. It generates
helper files for GitHub Pages on building HTML document
automatically.
MediaWiki
See sphinx-wiki, a project by Kevin Dunn.
Google Analytics
You can use a custom layout.html template, like this:
{% extends "!layout.html" %}
{%- block extrahead %}
{{ super() }}
{% endblock %}
{% block footer %}
{{ super() }}
{% endblock %}
Google Search
To replace Sphinx's built-in search function with Google Search,
proceed as follows:
1. Go to https://cse.google.com/cse/all to create the Google
Search code snippet.
2. Copy the code snippet and paste it into
_templates/searchbox.html in your Sphinx project:
{{ _('Quick search') }}
3. Add searchbox.html to the html_sidebars configuration value.
Sphinx vs. Docutils
tl;dr: docutils converts reStructuredText to multiple output formats.
Sphinx builds upon docutils to allow construction of cross-referenced
and indexed bodies of documentation.
docutils is a text processing system for converting plain text
documentation into other, richer formats. As noted in the docutils
documentation, docutils uses readers to read a document, parsers for
parsing plain text formats into an internal tree representation made up
of different types of nodes, and writers to output this tree in various
document formats. docutils provides parsers for one plain text format
- reStructuredText - though other, out-of-tree parsers have been
implemented including Sphinx's Markdown parser. On the other hand, it
provides writers for many different formats including HTML, LaTeX, man
pages, Open Document Format and XML.
docutils exposes all of its functionality through a variety of
front-end tools, such as rst2html, rst2odt and rst2xml. Crucially
though, all of these tools, and docutils itself, are concerned with
individual documents. They don't support concepts such as
cross-referencing, indexing of documents, or the construction of a
document hierarchy (typically manifesting in a table of contents).
Sphinx builds upon docutils by harnessing docutils' readers and parsers
and providing its own Builders. As a result, Sphinx wraps some of the
writers provided by docutils. This allows Sphinx to provide many
features that would simply not be possible with docutils, such as those
outlined above.
Epub info
The following list gives some hints for the creation of epub files:
o Split the text into several files. The longer the individual HTML
files are, the longer it takes the ebook reader to render them. In
extreme cases, the rendering can take up to one minute.
o Try to minimize the markup. This also pays in rendering time.
o For some readers you can use embedded or external fonts using the CSS
@font-face directive. This is extremely useful for code listings
which are often cut at the right margin. The default Courier font
(or variant) is quite wide and you can only display up to 60
characters on a line. If you replace it with a narrower font, you
can get more characters on a line. You may even use FontForge and
create narrow variants of some free font. In my case I get up to 70
characters on a line.
You may have to experiment a little until you get reasonable results.
o Test the created epubs. You can use several alternatives. The ones I
am aware of are Epubcheck, Calibre, FBreader (although it does not
render the CSS), and Bookworm. For Bookworm, you can download the
source from https://code.google.com/archive/p/threepress and run your
own local server.
o Large floating divs are not displayed properly. If they cover more
than one page, the div is only shown on the first page. In that case
you can copy the epub.css from the sphinx/themes/epub/static/
directory to your local _static/ directory and remove the float
settings.
o Files that are inserted outside of the toctree directive must be
manually included. This sometimes applies to appendixes, e.g. the
glossary or the indices. You can add them with the epub_post_files
option.
o The handling of the epub cover page differs from the reStructuredText
procedure which automatically resolves image paths and puts the
images into the _images directory. For the epub cover page put the
image in the html_static_path directory and reference it with its
full path in the epub_cover config option.
o kindlegen command can convert from epub3 resulting file to .mobi file
for Kindle. You can get yourdoc.mobi under _build/epub after the
following command:
$ make epub
$ kindlegen _build/epub/yourdoc.epub
The
kindlegen
command
doesn't
accept
documents
that
have
section
titles
surrounding
toctree
directive:
Section Title
=============
.. toctree::
subdocument
Section After Toc Tree
======================
kindlegen
assumes
all
documents
order
in
line,
but
the
resulting
document
has
complicated
order
for
kindlegen:
``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
If
you
get
the
following
error,
fix
your
document
structure:
Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
Error(prcgen):E24001: The table of content could not be built.
Texinfo info
There are two main programs for reading Info files, info and GNU Emacs.
The info program has less features but is available in most Unix
environments and can be quickly accessed from the terminal. Emacs
provides better font and color display and supports extensive
customization (of course).
Displaying Links
One noticeable problem you may encounter with the generated Info files
is how references are displayed. If you read the source of an Info
file, a reference to this section would look like:
* note Displaying Links: target-id
In
the
stand-alone
reader,
info,
references
are
displayed
just
as
they
appear
in
the
source.
Emacs,
on
the
other-hand,
will
by
default
replace
*note:
with
see
and
hide
the
target-id.
For
example:
Displaying Links
One
can
disable
generation
of
the
inline
references
in a
document
with
texinfo_cross_references.
That
makes
an
info
file
more
readable
with
stand-alone
reader
(info).
The
exact
behavior
of
how
Emacs
displays
references
is
dependent
on
the
variable
Info-hide-note-references.
If
set
to
the
value
of
hide,
Emacs
will
hide
both
the
*note:
part
and
the
target-id.
This
is
generally
the
best
way
to
view
Sphinx-based
documents
since
they
often
make
frequent
use
of
links
and
do
not
take
this
limitation
into
account.
However,
changing
this
variable
affects
how
all
Info
documents
are
displayed
and
most
do
take
this
behavior
into
account.
If
you
want
Emacs
to
display
Info
files
produced
by
Sphinx
using
the
value
hide
for
Info-hide-note-references
and
the
default
value
for
all
other
Info
files,
try
adding
the
following
Emacs
Lisp
code
to
your
start-up
file,
~/.emacs.d/init.el.
(defadvice info-insert-file-contents (after
sphinx-info-insert-file-contents
activate)
"Hack to make `Info-hide-note-references' buffer-local and
automatically set to `hide' iff it can be determined that this file
was created from a Texinfo file generated by Docutils or Sphinx."
(set (make-local-variable 'Info-hide-note-references)
(default-value 'Info-hide-note-references))
(save-excursion
(save-restriction
(widen) (goto-char (point-min))
(when (re-search-forward
"^Generated by \\(Sphinx\\|Docutils\\)"
(save-excursion (search-forward "\x1f" nil t)) t)
(set (make-local-variable 'Info-hide-note-references)
'hide)))))
Notes
The following notes may be helpful if you want to create Texinfo files:
o Each section corresponds to a different node in the Info file.
o Colons (:) cannot be properly escaped in menu entries and xrefs.
They will be replaced with semicolons (;).
o Links to external Info files can be created using the somewhat
official URI scheme info. For example:
info:Texinfo#makeinfo_options
Sphinx authors
Maintainers
Listed alphabetically in forename, surname order
o Adam Turner <@AA-Turner>
o Benedikt Tran <@picnixz>
o Chris Sewell <@chrisjsewell>
o Francois Freitag <@francoisfreitag>
o Jakob Lykke Andersen <@jakobandersen>
o Jean-Francois Burnol <@jfbu>
o Stephen Finucane <@stephenfin>
o Takayuki Shimizukawa <@shimizukawa>
o Takeshi Komiya <@tk0miya>
Contributors
Listed alphabetically in forename, surname order
o Adrian Chaves (Gallaecio) -- coverage builder improvements
o Alastair Houghton -- Apple Help builder
o Alexander Todorov -- inheritance_diagram tests and improvements
o Andi Albrecht -- agogo theme
o Antonio Valentino -- qthelp builder, docstring inheritance
o Antti Kaihola -- doctest extension (skipif option)
o Barry Warsaw -- setup command improvements
o Ben Egan -- Napoleon improvements
o Benjamin Peterson -- unittests
o Blaise Laflamme -- pyramid theme
o Bruce Mitchener -- Minor epub improvement
o Buck Evan -- dummy builder
o Charles Duffy -- original graphviz extension
o Chris Lamb -- reproducibility fixes
o Christopher Perkins -- autosummary integration
o Dan MacKinlay -- metadata fixes
o Daniel Bultmann -- todo extension
o Daniel Neuhauser -- JavaScript domain, Python 3 support (GSOC)
o Daniel Pizetta -- inheritance diagram improvements
o Dave Kuhlman -- original LaTeX writer
o Doug Hellmann -- graphviz improvements
o Eric N. Vander Weele -- autodoc improvements
o Etienne Desautels -- apidoc module
o Ezio Melotti -- collapsible sidebar JavaScript
o Filip Vavera -- napoleon todo directive
o Glenn Matthews -- python domain signature improvements
o Gregory Szorc -- performance improvements
o Henrique Bastos -- SVG support for graphviz extension
o Hernan Grecco -- search improvements
o Hong Xu -- svg support in imgmath extension and various bug fixes
o Horst Gutmann -- internationalization support
o Hugo van Kemenade -- support FORCE_COLOR and NO_COLOR
o Ian Lee -- quickstart improvements
o Jacob Mason -- websupport library (GSOC project)
o Jeppe Pihl -- literalinclude improvements
o Joel Wurtz -- cellspanning support in LaTeX
o John Waltman -- Texinfo builder
o Josip Dzolonga -- coverage builder
o Julien Palard -- Colspan and rowspan in text builder
o Kevin Dunn -- MathJax extension
o KINEBUCHI Tomohiko -- typing Sphinx as well as docutils
o Kurt McKee -- documentation updates
o Lars Hupfeldt Nielsen - OpenSSL FIPS mode md5 bug fix
o Lukasz Langa -- partial support for autodoc
o Marco Buttu -- doctest extension (pyversion option)
o Martin Hans -- autodoc improvements
o Martin Larralde -- additional napoleon admonitions
o Martin Mahner -- nature theme
o Matthew Fernandez -- todo extension fix
o Matthew Woodcraft -- text output improvements
o Michael Droettboom -- inheritance_diagram extension
o Michael Wilson -- Intersphinx HTTP basic auth support
o Nathan Damon -- bugfix in validation of static paths in html builders
o Pauli Virtanen -- autodoc improvements, autosummary extension
o Rob Ruana -- napoleon extension
o Robert Lehmann -- gettext builder (GSOC project)
o Roland Meister -- epub builder
o Sebastian Wiesner -- image handling, distutils support
o Stefan Seefeld -- toctree improvements
o Stefan van der Walt -- autosummary extension
o
T. Powers -- HTML output improvements
o Taku Shimizu -- epub3 builder
o Thomas Lamb -- linkcheck builder
o Thomas Waldmann -- apidoc module fixes
o Tim Hoffmann -- theme improvements
o Vince Salvino -- JavaScript search improvements
o Will Maier -- directory HTML builder
o Zac Hatfield-Dodds -- doctest reporting improvements, intersphinx
performance
Former maintainers
Listed alphabetically in forename, surname order
Former maintainers are those who haven't committed in the last two
years. Those on the list below may become active maintainers again at
any time.
o Armin Ronacher <@mitsuhiko>
o Daniel Neuhauser <@DasIch>
o Georg Brandl
o Rob Ruana <@RobRuana>
o Robert Lehmann <@lehmannro>
o Timotheus Kampik <@TimKam>
o Yoshiki Shibukawa <@shibukawa>
Many
thanks
for
all
contributions!
REFERENCE GUIDE
Reference documentation is more complete and programmatic in nature, it
is a collection of information that can be quickly referenced. If you
would like usecase-driven documentation, see Get started or User
Guides.
Command-Line Tools
These are the applications provided as part of Sphinx.
Core Applications
sphinx-quickstart
Synopsis
sphinx-quickstart
Description
sphinx-quickstart is an interactive tool that asks some questions about
your project and then generates a complete documentation directory and
sample Makefile to be used with sphinx-build(1).
Options
-q, --quiet
Quiet mode that skips the interactive wizard for specifying
options. This option requires -p, -a and -v options.
-h, --help, --version
Display usage summary or Sphinx version.
Structure
Options
--sep If specified, separate source and build directories.
--no-sep
If specified, create build directory under source directory.
--dot=DOT
Inside the root directory, two more directories will be created;
"_templates" for custom HTML templates and "_static" for custom
stylesheets and other static files. You can enter another prefix
(such as ".") to replace the underscore.
Project
Basic
Options
-p PROJECT, --project=PROJECT
Project name will be set. (see project).
-a AUTHOR, --author=AUTHOR
Author names. (see copyright).
-v VERSION
Version of project. (see version).
-r RELEASE, --release=RELEASE
Release of project. (see release).
-l LANGUAGE, --language=LANGUAGE
Document language. (see language).
--suffix=SUFFIX
Source file suffix. (see source_suffix).
--master=MASTER
Master document name. (see root_doc).
Extension
Options
--ext-autodoc
Enable sphinx.ext.autodoc extension.
--ext-doctest
Enable sphinx.ext.doctest extension.
--ext-intersphinx
Enable sphinx.ext.intersphinx extension.
--ext-todo
Enable sphinx.ext.todo extension.
--ext-coverage
Enable sphinx.ext.coverage extension.
--ext-imgmath
Enable sphinx.ext.imgmath extension.
--ext-mathjax
Enable sphinx.ext.mathjax extension.
--ext-ifconfig
Enable sphinx.ext.ifconfig extension.
--ext-viewcode
Enable sphinx.ext.viewcode extension.
--ext-githubpages
Enable sphinx.ext.githubpages extension.
--extensions=EXTENSIONS
Enable arbitrary extensions.
Makefile
and
Batchfile
Creation
Options
--use-make-mode (-m), --no-use-make-mode (-M)
Makefile/make.bat uses (or doesn't use) make-mode. Default is
use, which generates a more concise Makefile/make.bat.
Changed in version 1.5: make-mode is default.
Changed in version 7.3: Support for disabling the make-mode will
be removed in Sphinx 8.
--makefile, --no-makefile
Create (or not create) makefile.
--batchfile, --no-batchfile
Create (or not create) batchfile
Project
templating
Added
in
version
1.5:
Project
templating
options
for
sphinx-quickstart
-t, --templatedir=TEMPLATEDIR
Template directory for template files. You can modify the
templates of sphinx project files generated by quickstart.
Following Jinja2 template files are allowed:
o root_doc.rst_t
o conf.py_t
o Makefile_t
o Makefile.new_t
o make.bat_t
o make.bat.new_t
In
detail,
please
refer
the
system
template
files
Sphinx
provides.
(sphinx/templates/quickstart)
-d NAME=VALUE
Define a template variable
See also
sphinx-build(1)
sphinx-build
Synopsis
sphinx-build [options] [filenames ...]
Description
sphinx-build generates documentation from the files in and
places it in the .
sphinx-build looks for /conf.py for the configuration
settings. sphinx-quickstart(1) may be used to generate template files,
including conf.py.
sphinx-build can create documentation in different formats. A format
is selected by specifying the builder name on the command line; it
defaults to HTML. Builders can also perform other tasks related to
documentation processing. For a list of available builders, refer to
Builders.
By default, everything that is outdated is built. Output only for
selected files can be built by specifying individual filenames.
Options
-M buildername
Select a builder, using the make-mode. See Builders for a list
of all of Sphinx's built-in builders. Extensions can add their
own builders.
IMPORTANT:
Sphinx only recognizes the -M option if it is used first,
along with the source and output directories, before any
other options are passed. For example:
sphinx-build -M html ./source ./build -W --keep-going
The
make-mode
provides
the
same
build
functionality
as
a
default
Makefile
or
Make.bat,
and
provides
the
following
additional
build
pipelines:
latexpdf
Build LaTeX files and run them through pdflatex, or as
per latex_engine setting. If language is set to 'ja',
will use automatically the platex/dvipdfmx latex to PDF
pipeline.
info Build Texinfo files and run them through makeinfo.
NOTE:
The default output directory locations when using make-mode
differ from the defaults when using -b.
o doctrees are saved to /doctrees
o output files are saved to /
Added
in
version
1.2.1.
-b buildername, --builder buildername
Selects a builder.
See Builders for a list of all of Sphinx's built-in builders.
Extensions can add their own builders.
Changed in version 7.3: Add --builder long option.
-a, --write-all
If given, always write all output files. The default is to only
write output files for new and changed source files. (This may
not apply to all builders.)
NOTE:
This option does not re-read source files. To read and
re-process every file, use --fresh-env instead.
Changed
in
version
7.3:
Add
--write-all
long
option.
-E, --fresh-env
Don't use a saved environment (the structure caching all
cross-references), but rebuild it completely. The default is to
only read and parse source files that are new or have changed
since the last run.
Changed in version 7.3: Add --fresh-env long option.
-t tag, --tag tag
Define the tag tag. This is relevant for only directives that
only include their content if this tag is set.
Added in version 0.6.
Changed in version 7.3: Add --tag long option.
-d path, --doctree-dir path
Since Sphinx has to read and parse all source files before it
can write an output file, the parsed source files are cached as
"doctree pickles". Normally, these files are put in a directory
called .doctrees under the build directory; with this option you
can select a different cache directory (the doctrees can be
shared between all builders).
Changed in version 7.3: Add --doctree-dir long option.
-j N, --jobs N
Distribute the build over N processes in parallel, to make
building on multiprocessor machines more effective. Note that
not all parts and not all builders of Sphinx can be
parallelized. If auto argument is given, Sphinx uses the number
of CPUs as N.
Added in version 1.2: This option should be considered
experimental.
Changed in version 1.7: Support auto argument.
Changed in version 6.2: Add --jobs long option.
-c path, --config-dir path
Don't look for the conf.py in the source directory, but use the
given configuration directory instead. Note that various other
files and paths given by configuration values are expected to be
relative to the configuration directory, so they will have to be
present at this location too.
Added in version 0.3.
Changed in version 7.3: Add --config-dir long option.
-C, --isolated
Don't look for a configuration file; only take options via the
--define option.
Added in version 0.5.
Changed in version 7.3: Add --isolated long option.
-D setting=value, --define setting=value
Override a configuration value set in the conf.py file. The
value must be a number, string, list or dictionary value.
For lists, you can separate elements with a comma like this: -D
html_theme_path=path1,path2.
For dictionary values, supply the setting name and key like
this: -D latex_elements.docclass=scrartcl.
For boolean values, use 0 or 1 as the value.
Changed in version 0.6: The value can now be a dictionary value.
Changed in version 1.3: The value can now also be a list value.
Changed in version 7.3: Add --define long option.
-A name=value, --html-define name=value
Make the name assigned to value in the HTML templates.
Added in version 0.5.
Changed in version 7.3: Add --html-define long option.
-n, --nitpicky
Run in nit-picky mode. Currently, this generates warnings for
all missing references. See the config value nitpick_ignore for
a way to exclude some references as "known missing".
Changed in version 7.3: Add --nitpicky long option.
-N, --no-color
Do not emit colored output.
Changed in version 1.6: Add --no-color long option.
--color
Emit colored output. Auto-detected by default.
Added in version 1.6.
-v, --verbose
Increase verbosity (log-level). This option can be given up to
three times to get more debug logging output. It implies -T.
Added in version 1.2.
Changed in version 7.3: Add --verbose long option.
-q, --quiet
Do not output anything on standard output, only write warnings
and errors to standard error.
Changed in version 7.3: Add --quiet long option.
-Q, --silent
Do not output anything on standard output, also suppress
warnings. Only errors are written to standard error.
Changed in version 7.3: Add --silent long option.
-w file, --warning-file file
Write warnings (and errors) to the given file, in addition to
standard error.
Changed in version 7.3: ANSI control sequences are stripped when
writing to file.
Changed in version 7.3: Add --warning-file long option.
-W, --fail-on-warning
Turn warnings into errors. This means that the build stops at
the first warning and sphinx-build exits with exit status 1.
Changed in version 7.3: Add --fail-on-warning long option.
--keep-going
With -W option, keep going processing when getting warnings to
the end of build, and sphinx-build exits with exit status 1.
Added in version 1.8.
-T, --show-traceback
Display the full traceback when an unhandled exception occurs.
Otherwise, only a summary is displayed and the traceback
information is saved to a file for further analysis.
Added in version 1.2.
Changed in version 7.3: Add --show-traceback long option.
-P, --pdb
(Useful for debugging only.) Run the Python debugger, pdb, if
an unhandled exception occurs while building.
Changed in version 7.3: Add --pdb long option.
-h, --help, --version
Display usage summary or Sphinx version.
Added in version 1.2.
You
can
also
give
one
or
more
filenames
on
the
command
line
after
the
source
and
build
directories.
Sphinx
will
then
try
to
build
only
these
output
files
(and
their
dependencies).
Environment Variables
The sphinx-build refers following environment variables:
MAKE A path to make command. A command name is also allowed.
sphinx-build uses it to invoke sub-build process on make-mode.
Makefile
Options
The
Makefile
and
make.bat
files
created
by
sphinx-quickstart
usually
run
sphinx-build
only
with
the
-b
and
-d
options.
However,
they
support
the
following
variables
to
customize
behavior:
PAPER This sets the 'papersize' key of latex_elements: i.e. PAPER=a4
sets it to 'a4paper' and PAPER=letter to 'letterpaper'.
NOTE:
Usage of this environment variable got broken at Sphinx 1.5
as a4 or letter ended up as option to LaTeX document in place
of the needed a4paper, resp. letterpaper. Fixed at 1.7.7.
SPHINXBUILD
The command to use instead of sphinx-build.
BUILDDIR
The build directory to use instead of the one chosen in
sphinx-quickstart.
SPHINXOPTS
Additional options for sphinx-build. These options can also be
set via the shortcut variable O (capital 'o').
NO_COLOR
When set (regardless of value), sphinx-build will not use color
in terminal output. NO_COLOR takes precedence over FORCE_COLOR.
See no-color.org for other libraries supporting this community
standard.
Added in version 4.5.0.
FORCE_COLOR
When set (regardless of value), sphinx-build will use color in
terminal output. NO_COLOR takes precedence over FORCE_COLOR.
Added in version 4.5.0.
Deprecation Warnings
If any deprecation warning like RemovedInSphinxXXXWarning are displayed
when building a user's document, some Sphinx extension is using
deprecated features. In that case, please report it to author of the
extension.
To disable the deprecation warnings, please set PYTHONWARNINGS=
environment variable to your environment. For example:
o PYTHONWARNINGS= make html (Linux/Mac)
o export PYTHONWARNINGS= and do make html (Linux/Mac)
o set PYTHONWARNINGS= and do make html (Windows)
o modify your Makefile/make.bat and set the environment variable
See also
sphinx-quickstart(1)
Additional Applications
sphinx-apidoc
Synopsis
sphinx-apidoc [OPTIONS] -o [EXCLUDE_PATTERN
...]
Description
sphinx-apidoc is a tool for automatic generation of Sphinx sources
that, using the autodoc extension, document a whole package in the
style of other automatic API documentation tools.
MODULE_PATH is the path to a Python package to document, and
OUTPUT_PATH is the directory where the generated sources are placed.
Any EXCLUDE_PATTERNs given are fnmatch-style file and/or directory
patterns that will be excluded from generation.
WARNING:
sphinx-apidoc generates source files that use sphinx.ext.autodoc to
document all found modules. If any modules have side effects on
import, these will be executed by autodoc when sphinx-build is run.
If you document scripts (as opposed to library modules), make sure
their main routine is protected by a if __name__ == '__main__'
condition.
Options
-o
Directory to place the output files. If it does not exist, it is
created.
-q Do not output anything on standard output, only write warnings
and errors to standard error.
-f, --force
Force overwriting of any existing generated files.
-l, --follow-links
Follow symbolic links. Defaults to False.
-n, --dry-run
Do not create any files.
-s
Suffix for the source files generated. Defaults to rst.
-d
Maximum depth for the generated table of contents file. Defaults
to 4.
--tocfile
Filename for a table of contents file. Defaults to modules.
-T, --no-toc
Do not create a table of contents file. Ignored when --full is
provided.
-F, --full
Generate a full Sphinx project (conf.py, Makefile etc.) using
the same mechanism as sphinx-quickstart.
-e, --separate
Put documentation for each module on its own page.
Added in version 1.2.
-E, --no-headings
Do not create headings for the modules/packages. This is useful,
for example, when docstrings already contain headings.
-P, --private
Include "_private" modules.
Added in version 1.2.
--implicit-namespaces
By default sphinx-apidoc processes sys.path searching for
modules only. Python 3.3 introduced PEP 420 implicit namespaces
that allow module path structures such as foo/bar/module.py or
foo/bar/baz/__init__.py (notice that bar and foo are namespaces,
not modules).
Interpret paths recursively according to PEP-0420.
-M, --module-first
Put module documentation before submodule documentation.
These
options
are
used
when
--full
is
specified:
-a Append module_path to sys.path.
-H
Sets the project name to put in generated files (see project).
-A
Sets the author name(s) to put in generated files (see
copyright).
-V
Sets the project version to put in generated files (see
version).
-R
Sets the project release to put in generated files (see
release).
Project
templating
Added
in
version
2.2:
Project
templating
options
for
sphinx-apidoc
-t, --templatedir=TEMPLATEDIR
Template directory for template files. You can modify the
templates of sphinx project files generated by apidoc.
Following Jinja2 template files are allowed:
o module.rst_t
o package.rst_t
o toc.rst_t
o root_doc.rst_t
o conf.py_t
o Makefile_t
o Makefile.new_t
o make.bat_t
o make.bat.new_t
In
detail,
please
refer
the
system
template
files
Sphinx
provides.
(sphinx/templates/apidoc
and
sphinx/templates/quickstart)
Environment
SPHINX_APIDOC_OPTIONS
A comma-separated list of option to append to generated
automodule directives. Defaults to
members,undoc-members,show-inheritance.
See also
sphinx-build(1), sphinx-autogen(1)
sphinx-autogen
Synopsis
sphinx-autogen [options] ...
Description
sphinx-autogen is a tool for automatic generation of Sphinx sources
that, using the autodoc extension, document items included in
autosummary listing(s).
sourcefile is the path to one or more reStructuredText documents
containing autosummary entries with the :toctree:: option set.
sourcefile can be an fnmatch-style pattern.
Options
-o
Directory to place the output file. If it does not exist, it is
created. Defaults to the value passed to the :toctree: option.
-s , --suffix
Default suffix to use for generated files. Defaults to rst.
-t , --templates
Custom template directory. Defaults to None.
-i, --imported-members
Document imported members.
-a, --respect-module-all
Document exactly the members in a module's __all__ attribute.
Example
Given the following directory structure:
docs
>>> index.rst
>>> ...
foobar
>>> foo
| >>> __init__.py
>>> bar
>>> __init__.py
>>> baz
>>> __init__.py
and
assuming
docs/index.rst
contained
the
following:
Modules
=======
.. autosummary::
:toctree: modules
foobar.foo
foobar.bar
foobar.bar.baz
If
you
run
the
following:
$ PYTHONPATH=. sphinx-autogen docs/index.rst
then
the
following
stub
files
will
be
created
in
docs:
docs
>>> index.rst
>>> modules
>>> foobar.bar.rst
>>> foobar.bar.baz.rst
>>> foobar.foo.rst
and
each
of
those
files
will
contain
a
autodoc
directive
and
some
other
information.
See also
sphinx-build(1), sphinx-apidoc(1)
Glossary
builder
A class (inheriting from Builder) that takes parsed documents
and performs an action on them. Normally, builders translate
the documents to an output format, but it is also possible to
use builders that e.g. check for broken links in the
documentation, or build coverage information.
See Builders for an overview over Sphinx's built-in builders.
configuration directory
The directory containing conf.py. By default, this is the same
as the source directory, but can be set differently with the -c
command-line option.
directive
A reStructuredText markup element that allows marking a block of
content with special meaning. Directives are supplied not only
by docutils, but Sphinx and custom extensions can add their own.
The basic directive syntax looks like this:
.. directivename:: argument ...
:option: value
Content of the directive.
See
Directives
for
more
information.
document name
Since reST source files can have different extensions (some
people like .txt, some like .rst -- the extension can be
configured with source_suffix) and different OSes have different
path separators, Sphinx abstracts them: document names are
always relative to the source directory, the extension is
stripped, and path separators are converted to slashes. All
values, parameters and such referring to "documents" expect such
document names.
Examples for document names are index, library/zipfile, or
reference/datamodel/types. Note that there is no leading or
trailing slash.
domain A domain is a collection of markup (reStructuredText 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.
Having domains means that there are no naming problems when one
set of documentation wants to refer to e.g. C++ and Python
classes. It also means that extensions that support the
documentation of whole new languages are much easier to write.
For more information, refer to Domains.
environment
A structure where information about all documents under the root
is saved, and used for cross-referencing. The environment is
pickled after the parsing stage, so that successive runs only
need to read and parse new and changed documents.
extension
A custom role, directive or other aspect of Sphinx that allows
users to modify any aspect of the build process within Sphinx.
For more information, refer to Extensions.
master document
The document that contains the root toctree directive.
root document
Same as master document.
object The basic building block of Sphinx documentation. Every "object
directive" (e.g. py:function or object) creates such a block;
and most objects can be cross-referenced to.
RemoveInSphinxXXXWarning
The feature which is warned will be removed in Sphinx-XXX
version. It usually caused from Sphinx extensions which is
using deprecated. See also Deprecation Warnings.
role A reStructuredText markup element that allows marking a piece of
text. Like directives, roles are extensible. The basic syntax
looks like this: :rolename:`content`. See Inline markup for
details.
source directory
The directory which, including its subdirectories, contains all
source files for one Sphinx project.
reStructuredText
An easy-to-read, what-you-see-is-what-you-get plaintext markup
syntax and parser system.
Changelog
Release 7.3.7 (released Apr 19, 2024)
Bugs fixed
o #12299: Defer loading themes defined via entry points until their
explicit use by the user or a child theme. Patch by Adam Turner.
o #12305: Return the default value for theme.get_config() with an
unsupported theme configuration section. Patch by Adam Turner.
Release 7.3.6 (released Apr 17, 2024)
Bugs fixed
o #12295: Re-export all AST types in the C and C++ domains. Patch by
Adam Turner.
o #12295: Re-export various objects from
sphinx.domains.python._annotations in sphinx.domains.python. Patch
by Jacob Chesslo and Adam Turner.
Release 7.3.5 (released Apr 17, 2024)
Bugs fixed
o #12295: Re-export various objects from sphinx.domains.python._object
in sphinx.domains.python. Patch by Jacob Chesslo and Adam Turner.
Release 7.3.4 (released Apr 17, 2024)
Bugs fixed
o Handle cases when Any is not an instance of type. Patch by Adam
Turner.
Release 7.3.3 (released Apr 17, 2024)
Bugs fixed
o #12290: Fix a false-positive warning when setting a configuration
value with Any as the valid type to a type other than the value's
default. Patch by Adam Turner.
Release 7.3.2 (released Apr 17, 2024)
Bugs fixed
o Preload all themes defined via entry points. Patch by Adam Turner.
o Fix a bad interaction between the 'Furo' theme and the new-style for
configuration values. Patch by Adam Turner.
Release 7.3.1 (released Apr 17, 2024)
Dependencies
o Require tomli on Python 3.10 and earlier. Patch by Adam Turner.
Release 7.3.0 (released Apr 16, 2024)
Dependencies
o #11858: Increase the minimum supported version of Alabaster to
0.7.14. Patch by Adam Turner.
o #11411: Support Docutils 0.21. Patch by Adam Turner.
o #12012: Use types-docutils instead of docutils-stubs.
Deprecated
o #11693: Support for old-style Makefile and make.bat output in
sphinx-quickstart, and the associated options -M, -m,
--no-use-make-mode, and --use-make-mode.
o #11285: Direct access to sphinx.testing.util.SphinxTestApp._status or
sphinx.testing.util.SphinxTestApp._warning is deprecated. Use the
public properties sphinx.testing.util.SphinxTestApp.status and
sphinx.testing.util.SphinxTestApp.warning instead. Patch by Benedikt
Tran.
o tests: sphinx.testing.util.strip_escseq() is deprecated in favour of
sphinx.util.console.strip_colors(). Patch by Benedikt Tran.
Features added
o #12265: Support theme configuration via theme.toml.
o #11701: HTML Search: Adopt the new element. Patch by
Benedikt Tran.
o #11776: Add long option names to sphinx-build. Patch by Hugo van
Kemenade, Adam Turner, Benedikt Tran, and Ezio Melotti.
o Organise the sphinx-build options into groups. Patch by Adam Turner.
o #11855: Defer computation of configuration values. Patch by Adam
Turner.
o Add :no-search: as an alias of the :nosearch: metadata field. Patch
by Adam Turner.
o #11803: autodoc: Use an overriden __repr__() function in an enum, if
defined. Patch by Shengyu Zhang.
o #11825: Allow custom targets in the manpage role. Patch by Nicolas
Peugnet.
o #11892: Improved performance when resolving cross references in the
C++ domain. Patch by Rouslan Korneychuk.
o #11905: Add a versionremoved directive. Patch by Hugo van Kemenade,
Adam Turner, and C.A.M. Gerlach.
o #11981: Improve rendering of signatures using slice syntax, e.g., def
foo(arg: np.float64[:,:]) -> None: ....
o The manpage builder now adds OSC 8 anchors to hyperlinks, using the
groff device control command.
o #11015: Change the text of the versionadded directive from New in
[...] to Added in [...]. Patch by Benedikt Tran.
o #12131: Added show_warning_types configuration option. Patch by
Chris Sewell.
o #12193: Improve external warnings for unknown roles. In particular,
suggest related role names if an object type is mistakenly used.
Patch by Chris Sewell.
o Add public type alias sphinx.util.typing.ExtensionMetadata. This can
be used by extension developers to annotate the return type of their
setup function. Patch by Chris Sewell.
Bugs fixed
o #11668: Raise a useful error when theme.conf is missing. Patch by
Vinay Sajip.
o #11622: Ensure that the order of keys in searchindex.js is
deterministic. Patch by Pietro Albini.
o #11617: ANSI control sequences are stripped from the output when
writing to a warnings file with -w. Patch by Benedikt Tran.
o #11666: Skip all hidden directories in CatalogRepository.pofiles.
Patch by Aryaz Eghbali.
o #9686: html builder: Fix MathJax lazy loading when equations appear
in titles. Patch by Benedikt Tran.
o #11483: singlehtml builder: Fix MathJax lazy loading when the index
does not contain any math equations. Patch by Benedikt Tran.
o #11697: HTML Search: add 'noindex' meta robots tag. Patch by James
Addison.
o #11678: Fix a possible ZeroDivisionError in sphinx.ext.coverage.
Patch by Stephen Finucane.
o #11756: LaTeX: build error with recent TeXLive due to missing
substitutefont package (triggered if using fontenc with T2A option
and document language is not a Cyrillic one). Patch by Jean-Francois
B.
o #11675: Fix rendering of progression bars in environments that do not
support ANSI control sequences. Patch by Benedikt Tran.
o #11861: Whitelist more types with an incorrect __module__ attribute.
Patch by Adam Turner.
o #11715: Apply tls_verify and tls_cacerts config to ImageDownloader.
Patch by Nick Touran.
o Allow hyphens in group names for productionlist cross-references.
Patch by Adam Turner.
o #11433: Added the linkcheck_allow_unauthorized configuration option.
Set this option to False to report HTTP 401 (unauthorized) server
responses as broken. Patch by James Addison.
o #11868: linkcheck: added a distinct timeout reporting status code.
This can be enabled by setting linkcheck_report_timeouts_as_broken to
False. Patch by James Addison.
o #11869: Refresh the documentation for the linkcheck_timeout setting.
Patch by James Addison.
o #11874: Configure a default 30-second value for linkcheck_timeout.
Patch by James Addison.
o #11886: Print the Jinja2 template path chain in TemplateNotFound
exceptions. Patch by Colin Marquardt.
o #11598: Do not use query components in URLs for assets in EPUB
rendering. Patch by David Runge.
o #11904: Support unary subtraction when parsing annotations. Patch by
James Addison.
o #11925: Blacklist the sphinxprettysearchresults extension; the
functionality it provides was merged into Sphinx v2.0.0. Patch by
James Addison.
o #11917: Fix rendering of annotated inherited members for Python 3.9.
Patch by Janet Carson.
o #11935: C Domain: Fix namespace-pop context. Patch by Frank Dana.
o #11923: Avoid zombie processes when parallel builds fail. Patch by
Felix von Drigalski.
o #11353: Support enumeration classes inheriting from mixin or data
types. Patch by Benedikt Tran.
o #11962: Fix target resolution when using :paramtype: fields. Patch
by Benedikt Tran.
o #11944: Use anchor in search preview. Patch by Will Lachance.
o #12008: Fix case-sensitive lookup of std:label names in intersphinx
inventory. Patch by Michael Goerz.
o #11958: HTML Search: Fix partial matches overwriting full matches.
Patch by William Lachance.
o #11959: Fix multiple term matching when word appears in both title
and document. Patch by Will Lachance.
o #11474: Fix doctrees caching causing files not be rebuilt in some
cases, e.g., when numfig is True. Patch by Benedikt Tran.
o #11278: autodoc: Fix rendering of functools.singledispatchmethod
combined with @classmethod. Patch by Benedikt Tran.
o #11894: Do not add checksums to css files if building using the
htmlhelp builder. Patch by reduerK akiM.
o #12052: Remove
{{ super() }}
{%- endblock %}
Patch
by
Adam
Turner.
o #10471, #10565: Removed deprecated APIs scheduled for removal in
Sphinx 6.0. See Deprecated APIs for details. Patch by Adam Turner.
o #10901: C Domain: Remove support for parsing pre-v3 style type
directives and roles. Also remove associated configuration variables
c_allow_pre_v3 and c_warn_on_allowed_pre_v3. Patch by Adam Turner.
Features added
o #10924: LaTeX: adopt better looking defaults for tables and
code-blocks. See latex_table_style and the pre_border-radius and
pre_background-TeXcolor Additional CSS-like 'sphinxsetup' keys for
the former defaults and how to re-enact them if desired.
Bugs fixed
o #10984: LaTeX: Document latex_additional_files behavior for files
with .tex extension.
Release 5.3.0 (released Oct 16, 2022)
o #10759: LaTeX: add latex_table_style and support the 'booktabs',
'borderless', and 'colorrows' styles. (thanks to Stefan Wiehler for
initial pull requests #6666, #6671)
o #10840: One can cross-reference including an option value like
:option:`--module=foobar`, :option:`--module[=foobar]`, or
:option:`--module foobar`. Patch by Martin Liska.
o #10881: autosectionlabel: Record the generated section label to the
debug log.
o #10268: Correctly URI-escape image filenames.
o #10887: domains: Allow sections in all the content of all object
description directives (e.g. py:function). Patch by Adam Turner
Release 5.2.3 (released Sep 30, 2022)
o #10878: Fix base64 image embedding in sphinx.ext.imgmath
o #10886: Add :nocontentsentry: flag and global domain table of
contents entry control option. Patch by Adam Turner
Release 5.2.2 (released Sep 27, 2022)
o #10872: Restore link targets for autodoc modules to the top of
content. Patch by Dominic Davis-Foster.
Release 5.2.1 (released Sep 25, 2022)
Bugs fixed
o #10861: Always normalise the pycon3 lexer to pycon.
o Fix using sphinx.ext.autosummary with modules containing titles in
the module-level docstring.
Release 5.2.0.post0 (released Sep 24, 2022)
o Recreated source tarballs for Debian maintainers.
Release 5.2.0 (released Sep 24, 2022)
Dependencies
o #10356: Sphinx now uses declarative metadata with pyproject.toml to
create packages, using PyPA's flit project as a build backend. Patch
by Adam Turner.
Deprecated
o #10843: Support for HTML 4 output. Patch by Adam Turner.
Features added
o #10738: napoleon: Add support for docstring types using 'of', like
type of type. Example: tuple of int.
o #10286: C++, support requires clauses not just between the template
parameter lists and the declaration.
o #10755: linkcheck: Check the source URL of raw directives that use
the url option.
o #10781: Allow ref role to be used with definitions and fields.
o #10717: HTML Search: Increase priority for full title and subtitle
matches in search results
o #10718: HTML Search: Save search result score to the HTML element for
debugging
o #10673: Make toctree accept 'genindex', 'modindex' and 'search'
docnames
o #6316, #10804: Add domain objects to the table of contents. Patch by
Adam Turner
o #6692: HTML Search: Include explicit index directive index entries in
the search index and search results. Patch by Adam Turner
o #10816: imgmath: Allow embedding images in HTML as base64
o #10854: HTML Search: Use browser localstorage for highlight control,
stop storing highlight parameters in URL query strings. Patch by Adam
Turner.
Bugs fixed
o #10723: LaTeX: 5.1.0 has made the 'sphinxsetup'
verbatimwithframe=false become without effect.
o #10257: C++, ensure consistent non-specialization template argument
representation.
o #10729: C++, fix parsing of certain non-type template parameter
packs.
o #10715: Revert #10520: "Fix" use of sidebar classes in agogo.css_t
Release 5.1.1 (released Jul 26, 2022)
Bugs fixed
o #10701: Fix ValueError in the new deque based sphinx.ext.napolean
iterator implementation.
o #10702: Restore compatability with third-party builders.
Release 5.1.0 (released Jul 24, 2022)
Dependencies
o #10656: Support Docutils 0.19. Patch by Adam Turner.
Deprecated
o #10467: Deprecated sphinx.util.stemmer in favour of snowballstemmer.
Patch by Adam Turner.
o #9856: Deprecated sphinx.ext.napoleon.iterators.
Features added
o #10444: html theme: Allow specifying multiple CSS files through the
stylesheet setting in theme.conf or by setting html_style to an
iterable of strings.
o #10366: std domain: Add support for emphasising placeholders in
option directives through a new option_emphasise_placeholders
configuration option.
o #10439: std domain: Use the repr of some variables when displaying
warnings, making whitespace issues easier to identify.
o #10571: quickstart: Reduce content in the generated conf.py file.
Patch by Pradyun Gedam.
o #10648: LaTeX: CSS-named-alike additional 'sphinxsetup' keys allow to
configure four separate border-widths, four paddings, four corner
radii, a shadow (possibly inset), colours for border, background,
shadow for each of the code-block, topic, attention, caution, danger,
error and warning directives.
o #10655: LaTeX: Explain non-standard encoding in LatinRules.xdy
o #10599: HTML Theme: Wrap consecutive footnotes in an