The build configuration file
The documentation root, that is the Doc subdirectory of the source
distribution, contains a file named conf.py. This file is called the “build
configuration file”, and it contains several variables that are read and used
during a build run.
These variables are:
- version : string
- A string that is used as a replacement for the |version| reST
substitution. It should be the Python version the documentation refers to.
This consists only of the major and minor version parts, e.g. 2.5, even
for version 2.5.1.
- release : string
- A string that is used as a replacement for the |release| reST
substitution. It should be the full version string including
alpha/beta/release candidate tags, e.g. 2.5.2b3.
Both release and version can be 'auto', which means that they are
determined at runtime from the Include/patchlevel.h file, if a complete
Python source distribution can be found, or else from the interpreter running
Sphinx.
- today_fmt : string
- A strftime format that is used to format a replacement for the
|today| reST substitution.
- today : string
- A string that can contain a date that should be written to the documentation
output literally. If this is nonzero, it is used instead of
strftime(today_fmt).
- unused_files : list of strings
- A list of reST filenames that are to be disregarded during building. This
could be docs for temporarily disabled modules or documentation that’s not
yet ready for public consumption.
- add_function_parentheses : bool
- If true, () will be appended to the content of :func:, :meth: and
:cfunc: cross-references.
- add_module_names : bool
- If true, the current module name will be prepended to all description unit
titles (such as .. function::).
Builder-specific variables
- html_download_base_url : string
- The base URL for download links on the download page.
- html_last_updated_fmt : string
- If this is not an empty string, it will be given to time.strftime() and
written to each generated output file after “last updated on:”.
- html_use_smartypants : bool
- If true, use SmartyPants to convert quotes and dashes to the typographically
correct entities.
- latex_paper_size : “letter” or “a4”
- The paper size option for the LaTeX document class.
- latex_font_size : “10pt”, “11pt” or “12pt”
- The font size option for the LaTeX document class.
