sphinx / doc / config.rst

The build configuration file

The :term:`configuration directory` 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 is executed as Python code at build time (using :func:`execfile`, and with the current directory set to its containing directory), and therefore can execute arbitrarily complex code. Sphinx then reads simple names from the file's namespace as its configuration.

Important points to note:

  • If not otherwise documented, values must be strings, and their default is the empty string.
  • The term "fully-qualified name" refers to a string that names an importable Python object inside a module; for example, the FQN "sphinx.builder.Builder" means the Builder class in the sphinx.builder module.
  • Remember that document names use / as the path separator and don't contain the file name extension.
  • Since :file:`` is read as a Python file, the usual rules apply for encodings and Unicode support: declare the encoding using an encoding cookie (a comment like # -*- coding: utf-8 -*-) and use Unicode string literals when you include non-ASCII characters in configuration 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 you don't need to del your imports after use.

General configuration

Project information

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.

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.