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:
A list of strings that are module names of Sphinx extensions. These can be extensions coming with Sphinx (named sphinx.ext.*) or custom ones.
Note that you can extend 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 configuration directory, use 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 subdirectory sphinxext.
The configuration file itself can be an extension; for that, you only need to provide a setup() function in it.
The encoding of all reST source files. The recommended encoding, and the default value, is 'utf-8-sig'.
New in version 0.5: Previously, Sphinx accepted only UTF-8 encoded sources.
A list of directory paths, relative to the source directory, that are to be recursively excluded from the search for source files, that is, their subdirectories won’t be searched too. The default is [].
New in version 0.4.
A list of directory names that are to be excluded from any recursive operation Sphinx performs (e.g. searching for source files or copying static files). This is useful, for example, to exclude version-control-specific directories like 'CVS'. The default is [].
New in version 0.5.
A list of directory names, relative to the source directory, that are to be excluded from the search for source files.
Deprecated since version 0.5: This does not take subdirs of the excluded directories into account. Use exclude_trees or exclude_dirnames, which match the expectations.
New in version 0.5.
Directories in which to search for additional Sphinx message catalogs (see language), relative to the source directory. The directories on this path are searched by the standard gettext module for a domain of sphinx; so if you add the directory ./locale to this settting, the message catalogs must be in ./locale/language/LC_MESSAGES/sphinx.mo.
The default is [].
A string of reStructuredText that will be included at the end of every source file that is read. This is the right place to add substitutions that should be available in every file. An example:
rst_epilog = """
.. |psf| replace:: Python Software Foundation
"""
New in version 0.6.
The name of a reST role (builtin or Sphinx extension) to use as the default role, that is, for text marked up `like this`. This can be set to 'obj' to make `filter` a cross-reference to the function “filter”. The default is None, which doesn’t reassign the default role.
The default role can always be set within individual documents using the standard reST default-role directive.
New in version 0.4.
If true, keep warnings as “system message” paragraphs in the built documents. Regardless of this setting, warnings are always written to the standard error stream when sphinx-build is run.
The default is False, the pre-0.5 behavior was to always keep them.
New in version 0.5.
A list of prefixes that are ignored for sorting the module index (e.g., if this is set to ['foo.'], then foo.bar is shown under B, not F). This can be handy if you document a project that consists of a single package. Works only for the HTML builder currently. Default is [].
New in version 0.6.
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 version and release, just set them both to the same value.
The code for the language the docs are written in. Any text automatically generated by Sphinx will be in that language. Also, in the LaTeX builder, a suitable language will be selected as an option for the Babel package. Default is None, which means that no translation will be done.
New in version 0.5.
Currently supported languages are:
These values determine how to format the current date, used as the replacement for |today|.
The default is no today and a today_fmt of '%B %d, %Y' (or, if translation is enabled with language, am equivalent %format for the selected locale).
The default language to highlight source code in. The default is 'python'. The value should be a valid Pygments lexer name, see Showing code examples for more details.
New in version 0.5.
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.
Changed in version 0.3: If the value is a fully-qualified name of a custom Pygments style class, this is then used as custom style.
Trim spaces before footnote references that are necessary for the reST parser to recognize the footnote, but do not look too nice in the output.
New in version 0.6.
These options influence HTML as well as HTML Help output, and other builders that use Sphinx’ HTMLWriter class.
The “theme” that the HTML output should use. See the section about theming. The default is 'default'.
New in version 0.6.
A dictionary of options that influence the look and feel of the selected theme. These are theme-specific. For the options understood by the builtin themes, see this section.
New in version 0.6.
A list of paths that contain custom themes, either as subdirectories or as zip files. Relative paths are taken as relative to the configuration directory.
New in version 0.6.
A shorter “title” for the HTML docs. This is used in for links in the header and in the HTML Help docs. If not given, it defaults to the value of html_title.
New in version 0.4.
If given, this must be the name of an image file that is the logo of the docs. It is placed at the top of the sidebar; its width should therefore not exceed 200 pixels. Default: None.
New in version 0.4.1: The image file will be copied to the _static directory of the output HTML, so an already existing file with that name will be overwritten.
If given, this must be the name of an image file (within the static path, see below) that is the favicon of the docs. Modern browsers use this as icon for tabs, windows and bookmarks. It should be a Windows-style icon file (.ico), which is 16x16 or 32x32 pixels large. Default: None.
New in version 0.4.
A list of paths that contain custom static files (such as style sheets or script files). Relative paths are taken as relative to the configuration directory. They are copied to the output directory after the theme’s static files, so a file named default.css will overwrite the theme’s default.css.
Changed in version 0.4: The paths in html_static_path can now contain subdirectories.
If true, Sphinx will add “permalinks” for each heading and description environment as paragraph signs that become visible when the mouse hovers over them. Default: True.
New in version 0.6: Previously, this was always activated.
Custom sidebar templates, must be a dictionary that maps document names to template names. Example:
html_sidebars = {
'using/windows': 'windowssidebar.html'
}
This will render the template windowssidebar.html within the sidebar of the given document.
Additional templates that should be rendered to HTML pages, must be a dictionary that maps document names to template names.
Example:
html_additional_pages = {
'download': 'customdownload.html',
}
This will render the template customdownload.html as the page download.html.
Note
Earlier versions of Sphinx had a value called html_index which was a clumsy way of controlling the content of the “index” document. If you used this feature, migrate it by adding an 'index' key to this setting, with your custom template as the value, and in your custom template, use
{% extend "defindex.html" %}
{% block tables %}
... old template content ...
{% endblock %}
If true, add an index to the HTML documents. Default is True.
New in version 0.4.
If true, the index is generated twice: once as a single page with all the entries, and once as one page per starting letter. Default is False.
New in version 0.4.
If true, the reST sources are included in the HTML build as _sources/name. The default is True.
Warning
If this config value is set to False, the JavaScript search function will only display the titles of matching documents, and no excerpt from the matching contents.
If true (and html_copy_source is true as well), links to the reST sources will be added to the sidebar. The default is True.
New in version 0.6.
If nonempty, this is the file name suffix for generated HTML files. The default is ".html".
New in version 0.4.
Suffix for generated links to HTML files. The default is whatever html_file_suffix is set to; it can be set differently (e.g. to support different web server setups).
New in version 0.6.
If true, “Created using Sphinx” is shown in the HTML footer. Default is True.
New in version 0.4.
These options influence LaTeX output.
This value determines how to group the document tree into LaTeX source files. It must be a list of tuples (startdocname, targetname, title, author, documentclass, toctree_only), where the items are:
New in version 0.3: The 6th item toctree_only. Tuples with 5 items are still accepted.
If true, the topmost sectioning unit is parts, else it is chapters. Default: False.
New in version 0.3.
New in version 0.5.
A dictionary that contains LaTeX snippets that override those Sphinx usually puts into the generated .tex files.
Keep in mind that backslashes must be doubled in Python string literals to avoid interpretation as escape sequences.
Keys that you may want to override include:
Paper size option of the document class ('a4paper' or 'letterpaper'), default 'letterpaper'.
Point size option of the document class ('10pt', '11pt' or '12pt'), default '10pt'.
“babel” package inclusion, default '\\usepackage{babel}'.
Font package inclusion, default '\\usepackage{times}' (which uses Times and Helvetica). You can set this to '' to use the Computer Modern fonts.
Inclusion of the “fncychap” package (which makes fancy chapter titles), default '\\usepackage[Bjarne]{fncychap}' for English documentation, '\\usepackage[Sonny]{fncychap}' for internationalized docs (because the “Bjarne” style uses numbers spelled out in English). Other “fncychap” styles you can try include “Lenny”, “Glenn”, “Conny” and “Rejne”. You can also set this to '' to disable fncychap.
Additional preamble content, default empty.
Additional footer content (before the indices), default empty.
Keys that don’t need be overridden unless in special cases are:
“inputenc” package inclusion, default '\\usepackage[utf8]{inputenc}'.
“fontenc” package inclusion, default '\\usepackage[T1]{fontenc}'.
“maketitle” call, default '\\maketitle'. Override if you want to generate a differently-styled title page.
“tableofcontents” call, default '\\tableofcontents'. Override if you want to generate a different table of contents or put content between the title page and the TOC.
“printindex” call, the last thing in the file, default '\\printindex'. Override if you want to generate the index differently or append some content after the index.
Keys that are set by other options and therefore should not be overridden are:
'docclass' 'classoptions' 'title' 'date' 'release' 'author' 'logo' 'releasename' 'makeindex' 'makemodindex' 'shorthandoff' 'printmodindex'
A list of file names, relative to the configuration directory, to copy to the build directory when building LaTeX output. This is useful to copy files that Sphinx doesn’t copy automatically, e.g. if they are referenced in custom LaTeX added in latex_elements. Image files that are referenced in source files (e.g. via .. image::) are copied automatically.
You have to make sure yourself that the filenames don’t collide with those of any automatically copied files.
New in version 0.6.
Additional LaTeX markup for the preamble.
Deprecated since version 0.5: Use the 'preamble' key in the latex_elements value.
The output paper size ('letter' or 'a4'). Default is 'letter'.
Deprecated since version 0.5: Use the 'papersize' key in the latex_elements value.
The font size (‘10pt’, ‘11pt’ or ‘12pt’). Default is '10pt'.
Deprecated since version 0.5: Use the 'pointsize' key in the latex_elements value.