Configuration — Sphinx documentation

The configuration directory must contain a file named conf.py. This file (containing Python code) is called the “build configuration file” and contains (almost) all configuration needed to customise Sphinx input and output behaviour.
An optional file docutils.conf can be added to the configuration directory to adjust Docutils configuration if not otherwise overridden or set by Sphinx.
Important points to note:
If not otherwise documented, values must be strings, and their default is the empty string.
The term “fully-qualified name” (FQN) refers to a string that names an importable Python object inside a module; for example, the fully-qualified name "sphinx.builders.Builder" means the Builder class in the sphinx.builders module.
Document names use / as the path separator and do not contain the file name extension.
Where glob-style patterns are permitted, you can use the standard shell constructs (*, ?, [...], and [!...]) with the feature that none of these will match slashes (/). A double star ** can be used to match any sequence of characters including slashes.
The configuration file is executed as Python code at build time (using importlib.import_module(), with the current directory set to the configuration directory), and therefore can execute arbitrarily complex code.
Sphinx then reads simple names from the file’s namespace as its configuration. In general, configuration values should be simple strings, numbers, or lists or dictionaries of simple values.
The contents of the config namespace are pickled (so that Sphinx can find out when configuration changes), so it may not contain unpickleable values – delete them from the namespace with del if appropriate. Modules are removed automatically, so deleting imported modules is not needed.
There is a special object named tags available in the config file, which exposes the project tags. Tags are defined either via the --tag command-line option or tags.add('tag'). Note that the builder’s name and format tags are not available in conf.py.
It can be used to query and change the defined tags as follows:
To query whether a tag is set, use 'tag' in tags.
To add a tag, use tags.add('tag').
To remove a tag, use tags.remove('tag').
The documented project’s name. Example:
The project’s author(s). Example:
A copyright statement. Permitted styles are as follows, where ‘YYYY’ represents a four-digit year.
copyright = 'YYYY, Author Name'
copyright = 'YYYY Author Name'
copyright = 'YYYY-YYYY, Author Name'
copyright = 'YYYY-YYYY Author Name'
If the string '%Y' appears in a copyright line, it will be replaced with the current four-digit year. For example:
copyright = '%Y, Author Name'
copyright = 'YYYY-%Y, Author Name'
Added in version 3.5: The project_copyright alias.
Changed in version 7.1: The value may now be a sequence of copyright statements in the above form, which will be displayed each to their own line.
Changed in version 8.1: Copyright statements support the '%Y' placeholder.
The major project version, used as the replacement for the |version| default substitution.
This may be something like version = '4.2'. The full project version is defined in release.
If your project does not draw a meaningful distinction between between a ‘full’ and ‘major’ version, set both version and release to the same value.
The full project version, used as the replacement for the |release| default substitution, and e.g. in the HTML templates.
This may be something like release = '4.2.1b0'. The major (short) project version is defined in version.
If your project does not draw a meaningful distinction between between a ‘full’ and ‘major’ version, set both version and release to the same value.
Set a minimum supported version of Sphinx required to build the project. The format should be a 'major.minor' version string like '1.1' Sphinx will compare it with its version and refuse to build the project if the running version of Sphinx is too old. By default, there is no minimum version.
Added in version 1.0.
Changed in version 1.4: Allow a 'major.minor.micro' version string.
A list of strings that are module names of Sphinx extensions. These can be extensions bundled with Sphinx (named sphinx.ext.*) or custom first-party or third-party extensions.
To use a third-party extension, you must ensure that it is installed and include it in the extensions list, like so:
There are two options for first-party extensions. The configuration file itself can be an extension; for that, you only need to provide a setup() function in it. Otherwise, you must ensure that your custom extension is importable, and located in a directory that is in the Python path.