The build configuration file
The configuration directory must contain a file named conf.py
. 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 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.builders.Builder"
means theBuilder
class in thesphinx.builders
module. - Remember that document names use
/
as the path separator and don’t contain the file name extension. - Since
conf.py
is read as a Python file, the usual rules apply for encodings and Unicode support: 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 todel
your imports after use. - There is a special object named
tags
available in the config file. It can be used to query and change the tags (see 包含基于标签的内容). Usetags.has('tag')
to query,tags.add('tag')
andtags.remove('tag')
to change.
General configuration
Project information
Options for internationalization
These options influence Sphinx’ Native Language Support. See the documentation on Internationalization for details.
Options for HTML output
These options influence HTML as well as HTML Help output, and other builders that use Sphinx’ HTMLWriter class.
Options for epub output
These options influence the epub output. As this builder derives from the HTML builder, the HTML options also apply where appropriate. The actual values for some of the options is not really important, they just have to be entered into the Dublin Core metadata.
Options for LaTeX output
These options influence LaTeX output.
Options for text output
These options influence text output.
Options for manual page output
These options influence manual page output.
Options for Texinfo output
These options influence Texinfo output.
Options for the linkcheck builder
Footnotes
[1] | A note on available globbing syntax: you can use the standard shell constructs * , ? , [...] and [!...] with the feature that these all don’t match slashes. A double star ** can be used to match any sequence of characters including slashes. |