sphinx / doc / config.rst

Full commit

The build configuration file

The :term:`documentation root` must contain a file named :file:``. This file (containing Python code) is called the "build configuration file" and contains all configuration needed to customize Sphinx input and output behavior.

The configuration file if executed as Python code at build time (using :func:`execfile`, and with the current directory set to the documentation root), and therefore can execute arbitrarily complex code. Sphinx then reads simple names from the file's namespace as its configuration.

Two conventions are important to keep in mind here: Relative paths are always used relative to the documentation root, and document names must always be given without file name extension.

The contents of the 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.

The configuration values can be separated in several groups. If not otherwise documented, values must be strings, and their default is the empty string.

General configuration

Options for HTML output

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

Options for LaTeX output

These options influence LaTeX output.