.. highlightlang:: python The build configuration file ============================ .. module:: conf :synopsis: Build configuration file. The :term:`documentation root` must contain a file named :file:`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 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 --------------------- .. confval:: extensions A list of strings that are module names of Sphinx extensions. These can be extensions coming with Sphinx (named ``sphinx.addons.*``) or custom ones. Note that you can extend :data:`sys.path` within the conf file if your extensions live in another directory -- but make sure you use absolute paths. If your extension path is relative to the documentation root, use :func:`os.path.abspath` like so:: import sys, os sys.path.append(os.path.abspath('sphinxext')) extensions = ['extname'] That way, you can load an extension called ``extname`` from the documentation root's subdirectory ``sphinxext``. The configuration file itself can be an extension; for that, you only need to provide a :func:`setup` function in it. .. confval:: templates_path A list of paths that contain extra templates (or templates that overwrite builtin templates). .. confval:: source_suffix The file name extension of source files. Only files with this suffix will be read as sources. Default is ``.rst``. .. confval:: master_doc The document name of the "master" document, that is, the document that contains the root :dir:`toctree` directive. Default is ``'contents'``. .. confval:: project The documented project's name. .. confval:: copyright A copyright statement in the style ``'2008, Author Name'``. .. confval:: version The major project version, used as the replacement for ``|version|``. For example, for the Python documentation, this may be something like ``2.6``. .. confval:: release The full project version, used as the replacement for ``|release|`` and e.g. in the HTML templates. For example, for the Python documentation, this may be something like ``2.6.0rc1``. If you don't need the separation provided between :confval:`version` and :confval:`release`, just set them both to the same value. .. confval:: today today_fmt These values determine how to format the current date, used as the replacement for ``|today|``. * If you set :confval:`today` to a non-empty value, it is used. * Otherwise, the current time is formatted using :func:`time.strftime` and the format given in :confval:`today_fmt`. The default is no :confval:`today` and a :confval:`today_fmt` of ``'%B %d, %Y'``. .. confval:: unused_docs A list of document names that are present, but not currently included in the toctree. Use this setting to suppress the warning that is normally emitted in that case. .. confval:: add_function_parentheses A boolean that decides whether parentheses are appended to function and method role text (e.g. the content of ``:func:`input```) to signify that the name is callable. Default is ``True``. .. confval:: add_module_names A boolean that decides whether module names are prepended to all :term:`description unit` titles, e.g. for :dir:`function` directives. Default is ``True``. .. confval:: show_authors A boolean that decides whether :dir:`moduleauthor` and :dir:`sectionauthor` directives produce any output in the built files. .. confval:: pygments_style The style name to use for Pygments highlighting of source code. Default is ``'sphinx'``, which is a builtin style designed to match Sphinx' default style. .. confval:: template_bridge A string with the fully-qualified (that is, including the module name) name of a callable (or simply a class) that returns an instance of :class:`~sphinx.application.TemplateBridge`. This instance is then used to render HTML documents, and possibly the output of other builders (currently the changes builder). .. _html-options: Options for HTML output ----------------------- These options influence HTML as well as HTML Help output, and other builders that use Sphinx' HTMLWriter class. .. confval:: html_title The "title" for HTML documentation generated with Sphinx' own templates. This is appended to the ``