sphinx.rst

.. highlightlang:: rest

The Sphinx build system

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.