Configuration¶

The configuration directory must contain a file named conf.py. This file (containing Python code) is called the “build configuration file” and contains (almost) all configuration needed to customize Sphinx input and output behavior.

An optional file docutils.conf can be added to the configuration directory to adjust Docutils configuration if not otherwise overridden or set by Sphinx.

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 the Builder class in the sphinx.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 to del 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 Including content based on tags). Use tags.has('tag') to query, tags.add('tag') and tags.remove('tag') to change. Only tags set via the -t command-line option or via tags.add('tag') can be queried using tags.has('tag'). Note that the current builder tag is not available in conf.py, as it is created after the builder is initialized.

General configuration¶

extensions

A list of strings that are module names of 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.

source_suffix

The file extensions of source files. Sphinx considers the files with this suffix as sources. The value can be a dictionary mapping file extensions to file types. For example:

source_suffix = {
'.rst': 'restructuredtext',
'.txt': 'restructuredtext',
'.md': 'markdown',
}


By default, Sphinx only supports 'restructuredtext' file type. You can add a new file type using source parser extensions. Please read a document of the extension to know which file type the extension supports.

The value may also be a list of file extensions: then Sphinx will consider that they all map to the 'restructuredtext' file type.

Default is {'.rst': 'restructuredtext'}.

Note

file extensions have to start with a dot (e.g. .rst).

Changed in version 1.3: Can now be a list of extensions.

Changed in version 1.8: Support file type mapping

source_encoding

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.

source_parsers

If given, a dictionary of parser classes for different source suffices. The keys are the suffix, the values can be either a class or a string giving a fully-qualified name of a parser class. The parser class can be either docutils.parsers.Parser or sphinx.parsers.Parser. Files with a suffix that is not in the dictionary will be parsed with the default reStructuredText parser.

For example:

source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}


Note

New in version 1.3.

Deprecated since version 1.8: Now Sphinx provides an API Sphinx.add_source_parser() to register a source parser. Please use it instead.

master_doc

The document name of the “master” document, that is, the document that contains the root toctree directive. Default is 'contents'.

exclude_patterns

A list of glob-style patterns that should be excluded when looking for source files. [1] They are matched against the source file names relative to the source directory, using slashes as directory separators on all platforms.

Example patterns:

• 'library/xml.rst' – ignores the library/xml.rst file (replaces entry in unused_docs)
• 'library/xml' – ignores the library/xml directory
• 'library/xml*' – ignores all files and directories starting with library/xml
• '**/.svn' – ignores all .svn directories

exclude_patterns is also consulted when looking for static files in html_static_path and html_extra_path.

New in version 1.0.

templates_path

A list of paths that contain extra templates (or templates that overwrite builtin/theme-specific templates). Relative paths are taken as relative to the configuration directory.

Changed in version 1.3: As these files are not meant to be built, they are automatically added to exclude_patterns.

template_bridge

A string with the fully-qualified name of a callable (or simply a class) that returns an instance of TemplateBridge. This instance is then used to render HTML documents, and possibly the output of other builders (currently the changes builder). (Note that the template bridge must be made theme-aware if HTML themes are to be used.)

rst_epilog

A string of reStructuredText that will be included at the end of every source file that is read. This is a possible place to add substitutions that should be available in every file (another being rst_prolog). An example:

rst_epilog = """
.. |psf| replace:: Python Software Foundation
"""


New in version 0.6.

rst_prolog

A string of reStructuredText that will be included at the beginning of every source file that is read. This is a possible place to add substitutions that should be available in every file (another being rst_epilog). An example:

rst_prolog = """
.. |psf| replace:: Python Software Foundation
"""


New in version 1.0.

primary_domain

The name of the default domain. Can also be None to disable a default domain. The default is 'py'. Those objects in other domains (whether the domain name is given explicitly, or selected by a default-domain directive) will have the domain name explicitly prepended when named (e.g., when the default domain is C, Python functions will be named “Python function”, not just “function”).

New in version 1.0.

default_role

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 'py:obj' to make filter a cross-reference to the Python 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.

keep_warnings

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.

suppress_warnings

A list of warning types to suppress arbitrary warning messages.

Sphinx supports following warning types:

• ref.term
• ref.ref
• ref.numref
• ref.keyword
• ref.option
• ref.citation
• ref.footnote
• ref.doc
• ref.python
• misc.highlighting_failure
• toc.secnum
• epub.unknown_project_files

You can choose from these types.

Now, this option should be considered experimental.

New in version 1.4.

Changed in version 1.5: Added misc.highlighting_failure

Changed in version 1.5.1: Added epub.unknown_project_files

Changed in version 1.6: Added ref.footnote

needs_sphinx

If set to a major.minor version string like '1.1', Sphinx will compare it with its version and refuse to build if it is too old. Default is no requirement.

New in version 1.0.

Changed in version 1.4: also accepts micro version string

needs_extensions

This value can be a dictionary specifying version requirements for extensions in extensions, e.g. needs_extensions = {'sphinxcontrib.something': '1.5'}. The version strings should be in the form major.minor. Requirements do not have to be specified for all extensions, only for those you want to check.

This requires that the extension specifies its version to Sphinx (see Developing extensions for Sphinx for how to do that).

New in version 1.3.

manpages_url

A URL to cross-reference manpage directives. If this is defined to https://manpages.debian.org/{path}, the :manpage:man(1) role will link to <https://manpages.debian.org/man(1)>. The patterns available are:

• page - the manual page (man)
• section - the manual section (1)
• path - the original manual page and section specified (man(1))

This also supports manpages specified as man.1.

Note

This currently affects only HTML writers but could be expanded in the future.

New in version 1.7.

nitpicky

If true, Sphinx will warn about all references where the target cannot be found. Default is False. You can activate this mode temporarily using the -n command-line switch.

New in version 1.0.

nitpick_ignore

A list of (type, target) tuples (by default empty) that should be ignored when generating warnings in “nitpicky mode”. Note that type should include the domain name if present. Example entries would be ('py:func', 'int') or ('envvar', 'LD_LIBRARY_PATH').

New in version 1.1.

numfig

If true, figures, tables and code-blocks are automatically numbered if they have a caption. The numref role is enabled. Obeyed so far only by HTML and LaTeX builders. Default is False.

Note

The LaTeX builder always assigns numbers whether this option is enabled or not.

New in version 1.3.

numfig_format

A dictionary mapping 'figure', 'table', 'code-block' and 'section' to strings that are used for format of figure numbers. As a special character, %s will be replaced to figure number.

Default is to use 'Fig. %s' for 'figure', 'Table %s' for 'table', 'Listing %s' for 'code-block' and 'Section' for 'section'.

New in version 1.3.

numfig_secnum_depth
• if set to 0, figures, tables and code-blocks are continuously numbered starting at 1.
• if 1 (default) numbers will be x.1, x.2, … with x the section number (top level sectioning; no x. if no section). This naturally applies only if section numbering has been activated via the :numbered: option of the toctree directive.
• 2 means that numbers will be x.y.1, x.y.2, … if located in a sub-section (but still x.1, x.2, … if located directly under a section and 1, 2, … if not in any top level section.)
• etc…

New in version 1.3.

Changed in version 1.7: The LaTeX builder obeys this setting (if numfig is set to True).

smartquotes

If true, the Docutils Smart Quotes transform, originally based on SmartyPants (limited to English) and currently applying to many languages, will be used to convert quotes and dashes to typographically correct entities. Default: True.

New in version 1.6.6: It replaces deprecated html_use_smartypants. It applies by default to all builders except man and text (see smartquotes_excludes.)

A docutils.conf file located in the configuration directory (or a global ~/.docutils file) is obeyed unconditionally if it deactivates smart quotes via the corresponding Docutils option. But if it activates them, then smartquotes does prevail.

smartquotes_action

This string, for use with Docutils 0.14 or later, customizes the Smart Quotes transform. See the file smartquotes.py at the Docutils repository for details. The default 'qDe' educates normal quote characters ", ', em- and en-Dashes ---, --, and ellipses ....

New in version 1.6.6.

smartquotes_excludes

This is a dict whose default is:

{'languages': ['ja'], 'builders': ['man', 'text']}


Each entry gives a sufficient condition to ignore the smartquotes setting and deactivate the Smart Quotes transform. Accepted keys are as above 'builders' or 'languages'. The values are lists.

Note

Currently, in case of invocation of make with multiple targets, the first target name is the only one which is tested against the 'builders' entry and it decides for all. Also, a make text following make html needs to be issued in the form make text O="-E" to force re-parsing of source files, as the cached ones are already transformed. On the other hand the issue does not arise with direct usage of sphinx-build as it caches (in its default usage) the parsed source files in per builder locations.

New in version 1.6.6.

tls_verify

If true, Sphinx verifies server certifications. Default is True.

New in version 1.5.

tls_cacerts

A path to a certification file of CA or a path to directory which contains the certificates. This also allows a dictionary mapping hostname to the path to certificate file. The certificates are used to verify server certifications.

New in version 1.5.

Project information¶

project

The documented project’s name.

author

The author name(s) of the document. The default value is 'unknown'.

A copyright statement in the style '2008, Author Name'.

version

The major project version, used as the replacement for |version|. For example, for the Python documentation, this may be something like 2.6.

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 version and release, just set them both to the same value.

today
today_fmt

These values determine how to format the current date, used as the replacement for |today|.

The default is now today and a today_fmt of '%B %d, %Y' (or, if translation is enabled with language, an equivalent format for the selected locale).

highlight_language

The default language to highlight source code in. The default is 'python3'. The value should be a valid Pygments lexer name, see Showing code examples for more details.

New in version 0.5.

Changed in version 1.4: The default is now 'default'. It is similar to 'python3'; it is mostly a superset of 'python' but it fallbacks to 'none' without warning if failed. 'python3' and other languages will emit warning if failed. If you prefer Python 2 only highlighting, you can set it back to 'python'.

highlight_options

A dictionary of options that modify how the lexer specified by highlight_language generates highlighted source code. These are lexer-specific; for the options understood by each, see the Pygments documentation.

New in version 1.3.

pygments_style

The style name to use for Pygments highlighting of source code. If not set, either the theme’s default style or 'sphinx' is selected for HTML output.

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.

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.

add_module_names

A boolean that decides whether module names are prepended to all object names (for object types where a “module” of some kind is defined), e.g. for py:function directives. Default is True.

show_authors

A boolean that decides whether codeauthor and sectionauthor directives produce any output in the built files.

modindex_common_prefix

A list of prefixes that are ignored for sorting the Python 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.

trim_footnote_reference_space

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.

trim_doctest_flags

If true, doctest flags (comments looking like # doctest: FLAG, ...) at the ends of lines and <BLANKLINE> markers are removed for all code blocks showing interactive Python sessions (i.e. doctests). Default is True. See the extension doctest for more possibilities of including doctests.

New in version 1.0.

Changed in version 1.1: Now also removes <BLANKLINE>.

Options for internationalization¶

These options influence Sphinx’s Native Language Support. See the documentation on Internationalization for details.

language

The code for the language the docs are written in. Any text automatically generated by Sphinx will be in that language. Also, Sphinx will try to substitute individual paragraphs from your documents with the translation sets obtained from locale_dirs. Sphinx will search language-specific figures named by figure_language_filename and substitute them for original figures. 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.

Changed in version 1.4: Support figure substitution

Currently supported languages by Sphinx are:

• bn – Bengali
• ca – Catalan
• cs – Czech
• da – Danish
• de – German
• en – English
• es – Spanish
• et – Estonian
• eu – Basque
• fa – Iranian
• fi – Finnish
• fr – French
• he – Hebrew
• hr – Croatian
• hu – Hungarian
• id – Indonesian
• it – Italian
• ja – Japanese
• ko – Korean
• lt – Lithuanian
• lv – Latvian
• mk – Macedonian
• nb_NO – Norwegian Bokmal
• ne – Nepali
• nl – Dutch
• pl – Polish
• pt_BR – Brazilian Portuguese
• pt_PT – European Portuguese
• ru – Russian
• si – Sinhala
• sk – Slovak
• sl – Slovenian
• sv – Swedish
• tr – Turkish
• uk_UA – Ukrainian
• vi – Vietnamese
• zh_CN – Simplified Chinese
• zh_TW – Traditional Chinese
locale_dirs

New in version 0.5.

Directories in which to search for additional message catalogs (see language), relative to the source directory. The directories on this path are searched by the standard gettext module.

Internal messages are fetched from a text domain of sphinx; so if you add the directory ./locale to this setting, the message catalogs (compiled from .po format using msgfmt) must be in ./locale/language/LC_MESSAGES/sphinx.mo. The text domain of individual documents depends on gettext_compact.

The default is ['locales'].

Changed in version 1.5: Use locales directory as a default value

gettext_compact

New in version 1.1.

If true, a document’s text domain is its docname if it is a top-level project file and its very base directory otherwise.

By default, the document markup/code.rst ends up in the markup text domain. With this option set to False, it is markup/code.

gettext_uuid

If true, Sphinx generates uuid information for version tracking in message catalogs. It is used for:

• Add uid line for each msgids in .pot files.
• Calculate similarity between new msgids and previously saved old msgids. This calculation takes a long time.

If you want to accelerate the calculation, you can use python-levenshtein 3rd-party package written in C by using pip install python-levenshtein.

The default is False.

New in version 1.3.

gettext_location

If true, Sphinx generates location information for messages in message catalogs.

The default is True.

New in version 1.3.

gettext_auto_build

If true, Sphinx builds mo file for each translation catalog files.

The default is True.

New in version 1.3.

gettext_additional_targets

To specify names to enable gettext extracting and translation applying for i18n additionally. You can specify below names:

Index: index terms literal blocks: :: and code-block. doctest block raw content image/figure uri and alt

For example: gettext_additional_targets = ['literal-block', 'image'].

The default is [].

New in version 1.3.

figure_language_filename

The filename format for language-specific figures. The default value is {root}.{language}{ext}. It will be expanded to dirname/filename.en.png from .. image:: dirname/filename.png. The available format tokens are:

• {root} - the filename, including any path component, without the file extension, e.g. dirname/filename
• {path} - the directory path component of the filename, with a trailing slash if non-empty, e.g. dirname/
• {basename} - the filename without the directory path or file extension components, e.g. filename
• {ext} - the file extension, e.g. .png
• {language} - the translation language, e.g. en

For example, setting this to {path}{language}/{basename}{ext} will expand to dirname/en/filename.png instead.

New in version 1.4.

Changed in version 1.5: Added {path} and {basename} tokens.

Options for Math¶

These options influence Math notations.

math_number_all

Set this option to True if you want all displayed math to be numbered. The default is False.

math_eqref_format

A string used for formatting the labels of references to equations. The {number} place-holder stands for the equation number.

Example: 'Eq.{number}' gets rendered as, for example, Eq.10.

math_numfig

If True, displayed math equations are numbered across pages when numfig is enabled. The numfig_secnum_depth setting is respected. The eq, not numref, role must be used to reference equation numbers. Default is True.

New in version 1.7.

Options for HTML output¶

These options influence HTML as well as HTML Help output, and other builders that use Sphinx’s HTMLWriter class.

html_theme

The “theme” that the HTML output should use. See the section about theming. The default is 'alabaster'.

New in version 0.6.

html_theme_options

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.

html_theme_path

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.

html_style

The style sheet to use for HTML pages. A file of that name must exist either in Sphinx’s static/ path, or in one of the custom paths given in html_static_path. Default is the stylesheet given by the selected theme. If you only want to add or override a few things compared to the theme’s stylesheet, use CSS @import to import the theme’s stylesheet.

html_title

The “title” for HTML documentation generated with Sphinx’s own templates. This is appended to the <title> tag of individual pages, and used in the navigation bar as the “topmost” element. It defaults to '<project> v<revision> documentation'.

html_short_title

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.

html_baseurl

The URL which points to the root of the HTML documentation. It is used to indicate the location of document like canonical_url.

html_context

A dictionary of values to pass into the template engine’s context for all pages. Single values can also be put in this dictionary using the -A command-line option of sphinx-build.

New in version 0.5.

If given, this must be the name of an image file (path relative to the configuration directory) 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, but only if the file does not already exist there.

html_favicon

If given, this must be the name of an image file (path relative to the configuration directory) that is the favicon of the docs. Modern browsers use this as the 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: The image file will be copied to the _static directory of the output HTML, but only if the file does not already exist there.

html_css_files

A list of CSS files. The entry must be a filename string or a tuple containing the filename string and the attributes dictionary. The filename must be relative to the html_static_path, or a full URI with scheme like http://example.org/style.css. The attributes is used for attributes of <link> tag. It defaults to an empty list.

Example:

html_css_files = ['custom.css'
'https://example.com/css/custom.css',
('print.css', {'media': 'print'})]


New in version 1.8.

html_js_files

A list of JavaScript filename. The entry must be a filename string or a tuple containing the filename string and the attributes dictionary. The filename must be relative to the html_static_path, or a full URI with scheme like http://example.org/script.js. The attributes is used for attributes of <script> tag. It defaults to an empty list.

Example:

html_js_files = ['script.js',
'https://example.com/scripts/custom.js',
('custom.js', {'async': 'async'})]


New in version 1.8.

html_static_path

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’s _static directory after the theme’s static files, so a file named default.css will overwrite the theme’s default.css.

As these files are not meant to be built, they are automatically excluded from source files.

Note

For security reasons, dotfiles under html_static_path will not be copied. If you would like to copy them intentionally, please add each filepath to this setting:

html_static_path = ['_static', '_static/.htaccess']


Another way to do that, you can also use html_extra_path. It allows to copy dotfiles under the directories.

Changed in version 0.4: The paths in html_static_path can now contain subdirectories.

Changed in version 1.0: The entries in html_static_path can now be single files.

Changed in version 1.8: The files under html_static_path are excluded from source files.

html_extra_path

A list of paths that contain extra files not directly related to the documentation, such as robots.txt or .htaccess. Relative paths are taken as relative to the configuration directory. They are copied to the output directory. They will overwrite any existing file of the same name.

As these files are not meant to be built, they are automatically excluded from source files.

New in version 1.2.

Changed in version 1.4: The dotfiles in the extra directory will be copied to the output directory. And it refers exclude_patterns on copying extra files and directories, and ignores if path matches to patterns.

html_last_updated_fmt

If this is not None, a ‘Last updated on:’ timestamp is inserted at every page bottom, using the given strftime() format. The empty string is equivalent to '%b %d, %Y' (or a locale-dependent equivalent).

html_use_smartypants

If true, quotes and dashes are converted to typographically correct entities. Default: True.

Deprecated since version 1.6: To disable smart quotes, use rather smartquotes.

Sphinx will add “permalinks” for each heading and description environment as paragraph signs that become visible when the mouse hovers over them.

This value determines the text for the permalink; it defaults to "¶". Set it to None or the empty string to disable permalinks.

New in version 0.6: Previously, this was always activated.

Changed in version 1.1: This can now be a string to select the actual text of the link. Previously, only boolean values were accepted.

html_sidebars

Custom sidebar templates, must be a dictionary that maps document names to template names.

The keys can contain glob-style patterns [1], in which case all matching documents will get the specified sidebars. (A warning is emitted when a more than one glob-style pattern matches for any document.)

The values can be either lists or single strings.

• If a value is a list, it specifies the complete list of sidebar templates to include. If all or some of the default sidebars are to be included, they must be put into this list as well.

The default sidebars (for documents that don’t match any pattern) are defined by theme itself. Builtin themes are using these templates by default: ['localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'].

• If a value is a single string, it specifies a custom sidebar to be added between the 'sourcelink.html' and 'searchbox.html' entries. This is for compatibility with Sphinx versions before 1.0.

Deprecated since version 1.7: a single string value for html_sidebars will be removed in 2.0

Builtin sidebar templates that can be rendered are:

• relations.html – two links to the previous and next documents
• sourcelink.html – a link to the source of the current document, if enabled in html_show_sourcelink
• searchbox.html – the “quick search” box

Example:

html_sidebars = {
'using/windows': ['windowssidebar.html', 'searchbox.html'],
}


This will render the custom template windowssidebar.html and the quick search box within the sidebar of the given document, and render the default sidebars for all other pages (except that the local TOC is replaced by the global TOC).

New in version 1.0: The ability to use globbing keys and to specify multiple sidebars.

Note that this value only has no effect if the chosen theme does not possess a sidebar, like the builtin scrolls and haiku themes.

html_additional_pages

Additional templates that should be rendered to HTML pages, must be a dictionary that maps document names to template names.

Example:

html_additional_pages = {
}


This will render the template customdownload.html as the page download.html.

html_domain_indices

If true, generate domain-specific indices in addition to the general index. For e.g. the Python domain, this is the global module index. Default is True.

This value can be a bool or a list of index names that should be generated. To find out the index name for a specific index, look at the HTML file name. For example, the Python module index has the name 'py-modindex'.

New in version 1.0.

html_use_index

If true, add an index to the HTML documents. Default is True.

New in version 0.4.

html_split_index

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.

html_copy_source

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.

Suffix to be appended to source links (see html_show_sourcelink), unless they have this suffix already. Default is '.txt'.

New in version 1.5.

html_use_opensearch

If nonempty, an OpenSearch description file will be output, and all pages will contain a <link> tag referring to it. Since OpenSearch doesn’t support relative URLs for its search page location, the value of this option must be the base URL from which these documents are served (without trailing slash), e.g. "https://docs.python.org". The default is ''.

html_file_suffix

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, “(C) Copyright …” is shown in the HTML footer. Default is True.

New in version 1.0.

html_show_sphinx

If true, “Created using Sphinx” is shown in the HTML footer. Default is True.

New in version 0.4.

html_output_encoding

Encoding of HTML output files. Default is 'utf-8'. Note that this encoding name must both be a valid Python encoding name and a valid HTML charset value.

New in version 1.0.

html_compact_lists

If true, a list all whose items consist of a single paragraph and/or a sub-list all whose items etc… (recursive definition) will not use the <p> element for any of its items. This is standard docutils behavior. Default: True.

New in version 1.0.

html_secnumber_suffix

Suffix for section numbers. Default: ". ". Set to " " to suppress the final dot on section numbers.

New in version 1.0.

html_search_language

Language to be used for generating the HTML full-text search index. This defaults to the global language selected with language. If there is no support for this language, "en" is used which selects the English language.

Support is present for these languages:

• da – Danish
• nl – Dutch
• en – English
• fi – Finnish
• fr – French
• de – German
• hu – Hungarian
• it – Italian
• ja – Japanese
• no – Norwegian
• pt – Portuguese
• ro – Romanian
• ru – Russian
• es – Spanish
• sv – Swedish
• tr – Turkish
• zh – Chinese

Accelerating build speed

Each language (except Japanese) provides its own stemming algorithm. Sphinx uses a Python implementation by default. You can use a C implementation to accelerate building the index file.

New in version 1.1: With support for en and ja.

html_search_options

A dictionary with options for the search language support, empty by default. The meaning of these options depends on the language selected.

The English support has no options.

The Japanese support has these options:

Type:

type is dotted module path string to specify Splitter implementation which should be derived from sphinx.search.ja.BaseSplitter. If not specified or None is specified, 'sphinx.search.ja.DefaultSplitter' will be used.

You can choose from these modules:

‘sphinx.search.ja.DefaultSplitter’:
TinySegmenter algorithm. This is default splitter.
‘sphinx.search.ja.MeCabSplitter’:
MeCab binding. To use this splitter, ‘mecab’ python binding or dynamic link library (‘libmecab.so’ for linux, ‘libmecab.dll’ for windows) is required.
‘sphinx.search.ja.JanomeSplitter’:
Janome binding. To use this splitter, Janome is required.

Deprecated since version 1.6: 'mecab', 'janome' and 'default' is deprecated. To keep compatibility, 'mecab', 'janome' and 'default' are also acceptable.

Other option values depend on splitter value which you choose.

Options for 'mecab':
dic_enc: dic_enc option is the encoding for the MeCab algorithm. dict option is the dictionary to use for the MeCab algorithm. lib option is the library name for finding the MeCab library via ctypes if the Python binding is not installed.

For example:

html_search_options = {
'type': 'mecab',
'dic_enc': 'utf-8',
'dict': '/path/to/mecab.dic',
'lib': '/path/to/libmecab.so',
}

Options for 'janome':
user_dic: user_dic option is the user dictionary file path for Janome. user_dic_enc option is the encoding for the user dictionary file specified by user_dic option. Default is ‘utf8’.

New in version 1.1.

Changed in version 1.4: html_search_options for Japanese is re-organized and any custom splitter can be used by type settings.

The Chinese support has these options:

• dict – the jieba dictionary path if want to use custom dictionary.
html_search_scorer

The name of a JavaScript file (relative to the configuration directory) that implements a search results scorer. If empty, the default will be used.

New in version 1.2.

If true, images itself links to the original image if it doesn’t have ‘target’ option or scale related options: ‘scale’, ‘width’, ‘height’. The default is True.

New in version 1.3.

html_math_renderer

The name of math_renderer extension for HTML output. The default is 'mathjax'.

New in version 1.8.

html_experimental_html5_writer

Output is processed with HTML5 writer. This feature needs docutils 0.13 or newer. Default is False.

New in version 1.6.

Options for Single HTML output¶

singlehtml_sidebars

Custom sidebar templates, must be a dictionary that maps document names to template names. And it only allows a key named ‘index’. All other keys are ignored. For more information, refer to html_sidebars. By default, it is same as html_sidebars.

Options for HTML help output¶

htmlhelp_basename

Output file base name for HTML help builder. Default is 'pydoc'.

Options for Apple Help output¶

New in version 1.3.

These options influence the Apple Help output. This builder derives from the HTML builder, so the HTML options also apply where appropriate.

Note

Apple Help output will only work on Mac OS X 10.6 and higher, as it requires the hiutil and codesign command line tools, neither of which are Open Source.

You can disable the use of these tools using applehelp_disable_external_tools, but the result will not be a valid help book until the indexer is run over the .lproj folders within the bundle.

applehelp_bundle_name

The basename for the Apple Help Book. Defaults to the project name.

applehelp_bundle_id

The bundle ID for the help book bundle.

Warning

You must set this value in order to generate Apple Help.

applehelp_dev_region

The development region. Defaults to 'en-us', which is Apple’s recommended setting.

applehelp_bundle_version

The bundle version (as a string). Defaults to '1'.

applehelp_icon

The help bundle icon file, or None for no icon. According to Apple’s documentation, this should be a 16-by-16 pixel version of the application’s icon with a transparent background, saved as a PNG file.

applehelp_kb_product

The product tag for use with applehelp_kb_url. Defaults to '<project>-<release>'.

applehelp_kb_url

The URL for your knowledgebase server, e.g. https://example.com/kbsearch.py?p='product'&q='query'&l='lang'. Help Viewer will replace the values 'product', 'query' and 'lang' at runtime with the contents of applehelp_kb_product, the text entered by the user in the search box and the user’s system language respectively.

Defaults to None for no remote search.

applehelp_remote_url

The URL for remote content. You can place a copy of your Help Book’s Resources folder at this location and Help Viewer will attempt to use it to fetch updated content.

e.g. if you set it to https://example.com/help/Foo/ and Help Viewer wants a copy of index.html for an English speaking customer, it will look at https://example.com/help/Foo/en.lproj/index.html.

Defaults to None for no remote content.

applehelp_index_anchors

If True, tell the help indexer to index anchors in the generated HTML. This can be useful for jumping to a particular topic using the AHLookupAnchor function or the openHelpAnchor:inBook: method in your code. It also allows you to use help:anchor URLs; see the Apple documentation for more information on this topic.

applehelp_min_term_length

Controls the minimum term length for the help indexer. Defaults to None, which means the default will be used.

applehelp_stopwords

Either a language specification (to use the built-in stopwords), or the path to a stopwords plist, or None if you do not want to use stopwords. The default stopwords plist can be found at /usr/share/hiutil/Stopwords.plist and contains, at time of writing, stopwords for the following languages:

Language Code
English en
German de
Spanish es
French fr
Swedish sv
Hungarian hu
Italian it

Defaults to language, or if that is not set, to en.

applehelp_locale

Specifies the locale to generate help for. This is used to determine the name of the .lproj folder inside the Help Book’s Resources, and is passed to the help indexer.

Defaults to language, or if that is not set, to en.

applehelp_title

Specifies the help book title. Defaults to '<project> Help'.

applehelp_codesign_identity

Specifies the identity to use for code signing, or None if code signing is not to be performed.

Defaults to the value of the environment variable CODE_SIGN_IDENTITY, which is set by Xcode for script build phases, or None if that variable is not set.

applehelp_codesign_flags

A list of additional arguments to pass to codesign when signing the help book.

Defaults to a list based on the value of the environment variable OTHER_CODE_SIGN_FLAGS, which is set by Xcode for script build phases, or the empty list if that variable is not set.

applehelp_indexer_path

The path to the hiutil program. Defaults to '/usr/bin/hiutil'.

applehelp_codesign_path

The path to the codesign program. Defaults to '/usr/bin/codesign'.

applehelp_disable_external_tools

If True, the builder will not run the indexer or the code signing tool, no matter what other settings are specified.

This is mainly useful for testing, or where you want to run the Sphinx build on a non-Mac OS X platform and then complete the final steps on OS X for some reason.

Defaults to False.

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.

epub_basename

The basename for the epub file. It defaults to the project name.

epub_theme

The HTML theme for the epub output. Since the default themes are not optimized for small screen space, using the same theme for HTML and epub output is usually not wise. This defaults to 'epub', a theme designed to save visual space.

epub_theme_options

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 1.2.

epub_title

The title of the document. It defaults to the html_title option but can be set independently for epub creation.

epub_description

The description of the document. The default value is 'unknown'.

New in version 1.4.

Changed in version 1.5: Renamed from epub3_description

epub_author

The author of the document. This is put in the Dublin Core metadata. It defaults to the author option.

epub_contributor

The name of a person, organization, etc. that played a secondary role in the creation of the content of an EPUB Publication. The default value is 'unknown'.

New in version 1.4.

Changed in version 1.5: Renamed from epub3_contributor

epub_language

The language of the document. This is put in the Dublin Core metadata. The default is the language option or 'en' if unset.

epub_publisher

The publisher of the document. This is put in the Dublin Core metadata. You may use any sensible string, e.g. the project homepage. The defaults to the author option.

The copyright of the document. It defaults to the copyright option but can be set independently for epub creation.

epub_identifier

An identifier for the document. This is put in the Dublin Core metadata. For published documents this is the ISBN number, but you can also use an alternative scheme, e.g. the project homepage. The default value is 'unknown'.

epub_scheme

The publication scheme for the epub_identifier. This is put in the Dublin Core metadata. For published books the scheme is 'ISBN'. If you use the project homepage, 'URL' seems reasonable. The default value is 'unknown'.

epub_uid

A unique identifier for the document. This is put in the Dublin Core metadata. You may use a XML’s Name format string. You can’t use hyphen, period, numbers as a first character. The default value is 'unknown'.

epub_cover

The cover page information. This is a tuple containing the filenames of the cover image and the html template. The rendered html cover page is inserted as the first item in the spine in content.opf. If the template filename is empty, no html cover page is created. No cover at all is created if the tuple is empty. Examples:

epub_cover = ('_static/cover.png', 'epub-cover.html')
epub_cover = ('_static/cover.png', '')
epub_cover = ()


The default value is ().

New in version 1.1.

epub_css_files

A list of CSS files. The entry must be a filename string or a tuple containing the filename string and the attributes dictionary. For more information, see html_css_files.

New in version 1.8.

epub_guide

Meta data for the guide element of content.opf. This is a sequence of tuples containing the type, the uri and the title of the optional guide information. See the OPF documentation at http://idpf.org/epub for details. If possible, default entries for the cover and toc types are automatically inserted. However, the types can be explicitly overwritten if the default entries are not appropriate. Example:

epub_guide = (('cover', 'cover.html', u'Cover Page'),)


The default value is ().

epub_pre_files

Additional files that should be inserted before the text generated by Sphinx. It is a list of tuples containing the file name and the title. If the title is empty, no entry is added to toc.ncx. Example:

epub_pre_files = [
('index.html', 'Welcome'),
]


The default value is [].

epub_post_files

Additional files that should be inserted after the text generated by Sphinx. It is a list of tuples containing the file name and the title. This option can be used to add an appendix. If the title is empty, no entry is added to toc.ncx. The default value is [].

epub_exclude_files

A list of files that are generated/copied in the build directory but should not be included in the epub file. The default value is [].

epub_tocdepth

The depth of the table of contents in the file toc.ncx. It should be an integer greater than zero. The default value is 3. Note: A deeply nested table of contents may be difficult to navigate.

epub_tocdup

This flag determines if a toc entry is inserted again at the beginning of its nested toc listing. This allows easier navigation to the top of a chapter, but can be confusing because it mixes entries of different depth in one list. The default value is True.

epub_tocscope

This setting control the scope of the epub table of contents. The setting can have the following values:

• 'default' – include all toc entries that are not hidden (default)
• 'includehidden' – include all toc entries

New in version 1.2.

epub_fix_images

This flag determines if sphinx should try to fix image formats that are not supported by some epub readers. At the moment palette images with a small color table are upgraded. You need the Python Image Library (Pillow the successor of the PIL) installed to use this option. The default value is False because the automatic conversion may lose information.

New in version 1.2.

epub_max_image_width

This option specifies the maximum width of images. If it is set to a value greater than zero, images with a width larger than the given value are scaled accordingly. If it is zero, no scaling is performed. The default value is 0. You need the Python Image Library (Pillow) installed to use this option.

New in version 1.2.

epub_show_urls

Control whether to display URL addresses. This is very useful for readers that have no other means to display the linked URL. The settings can have the following values:

• 'inline' – display URLs inline in parentheses (default)
• 'footnote' – display URLs in footnotes
• 'no' – do not display URLs

The display of inline URLs can be customized by adding CSS rules for the class link-target.

New in version 1.2.

epub_use_index

If true, add an index to the epub document. It defaults to the html_use_index option but can be set independently for epub creation.

New in version 1.2.

epub_writing_mode

It specifies writing direction. It can accept 'horizontal' (default) and 'vertical'

epub_writing_mode 'horizontal' 'vertical'
writing-mode [2] horizontal-tb vertical-rl
page progression left to right right to left
iBook’s Scroll Theme support scroll-axis is vertical. scroll-axis is horizontal.

Options for LaTeX output¶

These options influence LaTeX output. Refer to LaTeX customization for more information.

latex_engine

The LaTeX engine to build the docs. The setting can have the following values:

• 'pdflatex' – PDFLaTeX (default)
• 'xelatex' – XeLaTeX
• 'lualatex' – LuaLaTeX
• 'platex' – pLaTeX (default if language is 'ja')

PDFLaTeX’s support for Unicode characters covers those from the document language (the LaTeX babel and inputenc packages map them to glyph slots in the document font, at various encodings allowing each only 256 characters; Sphinx uses by default (except for Cyrillic languages) the times package), but stray characters from other scripts or special symbols may require adding extra LaTeX packages or macros to the LaTeX preamble.

If your project uses such extra Unicode characters, switching the engine to XeLaTeX or LuaLaTeX and setting up the document to use an OpenType font with wide-enough glyph coverage is often easier than sticking with PDFLaTeX and trying to get it to work with the Unicode characters.

The latex_elements 'fontpkg' key allows to set up the document fonts, see this example. Currently, for XeLaTeX and LuaLaTeX, Sphinx leaves this key empty and LaTeX then defaults to the Latin Modern font family (from the TeX distribution fonts). This font family provides good coverage of Latin scripts (European languages, Vietnamese) but Cyrillic requires some other OpenType font; for example Computer Modern Unicode (see babel-russian documentation on how to load it in the LaTeX document). In future, it is planned Sphinx will provide another default choice of OpenType font than Latin Modern, perhaps Libertinus, which is included in recent TeX distributions and supports Latin and Cyrillic and also has an accompanying math font.

With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document to use polyglossia. For some languages the babel support appears preferable; Sphinx uses currently babel for French and perhaps will also for some more languages in future. One can use the latex_elements 'babel' key to override Sphinx’s default.

latex_documents

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:

startdocname
String that specifies the document name of the LaTeX file’s master document. All documents referenced by the startdoc document in TOC trees will be included in the LaTeX file. (If you want to use the default master document for your LaTeX build, provide your master_doc here.)
targetname
File name of the LaTeX file in the output directory.
title
LaTeX document title. Can be empty to use the title of the startdoc document. This is inserted as LaTeX markup, so special characters like a backslash or ampersand must be represented by the proper LaTeX commands if they are to be inserted literally.
author
Author for the LaTeX document. The same LaTeX markup caveat as for title applies. Use \\and to separate multiple authors, as in: 'John \\and Sarah' (backslashes must be Python-escaped to reach LaTeX).
documentclass
Normally, one of 'manual' or 'howto' (provided by Sphinx and based on 'report', resp. 'article'; Japanese documents use 'jsbook', resp. 'jreport'.) “howto” (non-Japanese) documents will not get appendices. Also they have a simpler title page. Other document classes can be given. Independently of the document class, the “sphinx” package is always loaded in order to define Sphinx’s custom LaTeX commands.
toctree_only
Must be True or False. If true, the startdoc document itself is not included in the output, only the documents referenced by it via TOC trees. With this option, you can put extra stuff in the master document that shows up in the HTML, but not the LaTeX output.

New in version 1.2: In the past including your own document class required you to prepend the document class name with the string “sphinx”. This is not necessary anymore.

New in version 0.3: The 6th item toctree_only. Tuples with 5 items are still accepted.

If given, this must be the name of an image file (relative to the configuration directory) that is the logo of the docs. It is placed at the top of the title page. Default: None.

latex_toplevel_sectioning

This value determines the topmost sectioning unit. It should be chosen from 'part', 'chapter' or 'section'. The default is None; the topmost sectioning unit is switched by documentclass: section is used if documentclass will be howto, otherwise chapter will be used.

Note that if LaTeX uses \part command, then the numbering of sectioning units one level deep gets off-sync with HTML numbering, because LaTeX numbers continuously \chapter (or \section for howto.)

New in version 1.4.

latex_appendices

A list of document names to append as an appendix to all manuals.

latex_domain_indices

If true, generate domain-specific indices in addition to the general index. For e.g. the Python domain, this is the global module index. Default is True.

This value can be a bool or a list of index names that should be generated, like for html_domain_indices.

New in version 1.0.

latex_show_pagerefs

If true, add page references after internal references. This is very useful for printed copies of the manual. Default is False.

New in version 1.0.

latex_show_urls

Control whether to display URL addresses. This is very useful for printed copies of the manual. The setting can have the following values:

• 'no' – do not display URLs (default)
• 'footnote' – display URLs in footnotes
• 'inline' – display URLs inline in parentheses

New in version 1.0.

Changed in version 1.1: This value is now a string; previously it was a boolean value, and a true value selected the 'inline' display. For backwards compatibility, True is still accepted.

latex_use_latex_multicolumn

The default is False: it means that Sphinx’s own macros are used for merged cells from grid tables. They allow general contents (literal blocks, lists, blockquotes, …) but may have problems if the tabularcolumns directive was used to inject LaTeX mark-up of the type >{..}, <{..}, @{..} as column specification.

Setting to True means to use LaTeX’s standard \multicolumn; this is incompatible with literal blocks in the horizontally merged cell, and also with multiple paragraphs in such cell if the table is rendered using tabulary.

New in version 1.6.

latex_use_xindy

If True, the PDF build from the LaTeX files created by Sphinx will use xindy (doc) rather than makeindex for preparing the index of general terms (from index usage). This means that words with UTF-8 characters will get ordered correctly for the language.

• This option is ignored if latex_engine is 'platex' (Japanese documents; mendex replaces makeindex then).
• The default is True for 'xelatex' or 'lualatex' as makeindex, if any indexed term starts with a non-ascii character, creates .ind files containing invalid bytes for UTF-8 encoding. With 'lualatex' this then breaks the PDF build.
• The default is False for 'pdflatex' but True is recommended for non-English documents as soon as some indexed terms use non-ascii characters from the language script.

Sphinx adds to xindy base distribution some dedicated support for using 'pdflatex' engine with Cyrillic scripts. And whether with 'pdflatex' or Unicode engines, Cyrillic documents handle correctly the indexing of Latin names, even with diacritics.

New in version 1.8.

latex_elements

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:

'papersize'

Paper size option of the document class ('a4paper' or 'letterpaper'), default 'letterpaper'.

'pointsize'

Point size option of the document class ('10pt', '11pt' or '12pt'), default '10pt'.

'pxunit'

the value of the px when used in image attributes width and height. The default value is '0.75bp' which achieves 96px=1in (in TeX 1in = 72bp = 72.27pt.) To obtain for example 100px=1in use '0.01in' or '0.7227pt' (the latter leads to TeX computing a more precise value, due to the smaller unit used in the specification); for 72px=1in, simply use '1bp'; for 90px=1in, use '0.8bp' or '0.803pt'.

New in version 1.5.

'sphinxsetup'

A comma separated list of key=value package options for the Sphinx LaTeX style, default empty. See LaTeX customization.

New in version 1.5.

'passoptionstopackages'

A string which will be positioned early in the preamble, designed to contain \\PassOptionsToPackage{options}{foo} commands. Default empty.

New in version 1.4.

'babel'

“babel” package inclusion, default '\\usepackage{babel}' (the suitable document language string is passed as class option, and english is used if no language.) For Japanese documents, the default is the empty string.

Changed in version 1.5: For latex_engine set to 'xelatex', the default is '\\usepackage{polyglossia}\n\\setmainlanguage{<language>}'.

Changed in version 1.6: 'lualatex' uses same default setting as 'xelatex'

Changed in version 1.7.6: For French, xelatex and lualatex default to using babel, not polyglossia.

'fontpkg'

Font package inclusion, default '\\usepackage{times}' (which uses Times for text, Helvetica for sans serif and Courier for code-blocks).

Changed in version 1.2: Defaults to '' when the language uses the Cyrillic script.

Changed in version 1.5: Defaults to '' when latex_engine is 'xelatex'.

Changed in version 1.6: Defaults to '' also with 'lualatex'.

'fncychap'

Inclusion of the “fncychap” package (which makes fancy chapter titles), default '\\usepackage[Bjarne]{fncychap}' for English documentation (this option is slightly customized by Sphinx), '\\usepackage[Sonny]{fncychap}' for internationalized docs (because the “Bjarne” style uses numbers spelled out in English). Other “fncychap” styles you can try are “Lenny”, “Glenn”, “Conny”, “Rejne” and “Bjornstrup”. You can also set this to '' to disable fncychap.

'preamble'

Additional preamble content, default empty. See LaTeX customization.

'atendofbody'

Additional document content (right before the indices), default empty.

New in version 1.5.

'figure_align'

Latex figure float alignment, default ‘htbp’ (here, top, bottom, page). Whenever an image doesn’t fit into the current page, it will be ‘floated’ into the next page but may be preceded by any other text. If you don’t like this behavior, use ‘H’ which will disable floating and position figures strictly in the order they appear in the source.

New in version 1.3.

'footer'

Additional footer content (before the indices), default empty.

Deprecated since version 1.5: Use 'atendofbody' key instead.

• Keys that don’t need to be overridden unless in special cases are:

'extraclassoptions'

The default is the empty string. Example: 'extraclassoptions': 'openany' will allow chapters (for documents of the 'manual' type) to start on any page.

New in version 1.2.

Changed in version 1.6: Added this documentation.

'maxlistdepth'

LaTeX allows by default at most 6 levels for nesting list and quote-like environments, with at most 4 enumerated lists, and 4 bullet lists. Setting this key for example to '10' (as a string) will allow up to 10 nested levels (of all sorts). Leaving it to the empty string means to obey the LaTeX default.

Warning

• Using this key may prove incompatible with some LaTeX packages or special document classes which do their own list customization.
• The key setting is silently ignored if \usepackage{enumitem} is executed inside the document preamble. Use then rather the dedicated commands of this LaTeX package.

New in version 1.5.

'inputenc'

“inputenc” package inclusion, defaults to '\\usepackage[utf8]{inputenc}' when using pdflatex. Otherwise empty.

Changed in version 1.4.3: Previously '\\usepackage[utf8]{inputenc}' was used for all compilers.

'cmappkg'

“cmap” package inclusion, default '\\usepackage{cmap}'.

New in version 1.2.

'fontenc'

“fontenc” package inclusion, default '\\usepackage[T1]{fontenc}'.

Changed in version 1.5: Defaults to '\\usepackage{fontspec}' when latex_engine is 'xelatex'.

Changed in version 1.6: 'lualatex' also uses fontspec per default.

'geometry'

“geometry” package inclusion, the default definition is:

'\\usepackage{geometry}'

with an additional [dvipdfm] for Japanese documents. The Sphinx LaTeX style file executes:

\PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry}

which can be customized via corresponding ‘sphinxsetup’ options.

New in version 1.5.

Changed in version 1.5.2: dvipdfm option if latex_engine is 'platex'.

New in version 1.5.3: The ‘sphinxsetup’ keys for the margins.

Changed in version 1.5.3: The location in the LaTeX file has been moved to after \usepackage{sphinx} and \sphinxsetup{..}, hence also after insertion of 'fontpkg' key. This is in order to handle the paper layout options in a special way for Japanese documents: the text width will be set to an integer multiple of the zenkaku width, and the text height to an integer multiple of the baseline. See the hmargin documentation for more.

'hyperref'

“hyperref” package inclusion; also loads package “hypcap” and issues \urlstyle{same}. This is done after sphinx.sty file is loaded and before executing the contents of 'preamble' key.

Attention

New in version 1.5: Previously this was done from inside sphinx.sty.

'maketitle'

“maketitle” call, default '\\sphinxmaketitle'. Override if you want to generate a differently styled title page.

Hint

If the key value is set to r'\newcommand\sphinxbackoftitlepage{<Extra material>}\sphinxmaketitle', then <Extra material> will be typeset on back of title page ('manual' docclass only).

Changed in version 1.8.3: Original \maketitle from document class is not overwritten, hence is re-usable as part of some custom setting for this key.

New in version 1.8.3: \sphinxbackoftitlepage optional macro. It can also be defined inside 'preamble' key rather than this one.

'releasename'

value that prefixes 'release' element on title page, default 'Release'. As for title and author used in the tuples of latex_documents, it is inserted as LaTeX markup.

'tableofcontents'

“tableofcontents” call, default '\\sphinxtableofcontents' (it is a wrapper of unmodified \tableofcontents, which may itself be customized by user loaded packages.) Override if you want to generate a different table of contents or put content between the title page and the TOC.

Changed in version 1.5: Previously the meaning of \tableofcontents itself was modified by Sphinx. This created an incompatibility with dedicated packages modifying it also such as “tocloft” or “etoc”.

'transition'

Commands used to display transitions, default '\n\n\\bigskip\\hrule\\bigskip\n\n'. Override if you want to display transitions differently.

New in version 1.2.

Changed in version 1.6: Remove unneeded {} after \\hrule.

'printindex'

“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. For example '\\footnotesize\\raggedright\\printindex' is advisable when the index is full of long entries.

'fvset'

Customization of fancyvrb LaTeX package. Currently, Sphinx uses this key to set the fontsize in code-blocks according to the latex_engine.

• 'pdflatex' uses 'fvset': '\\fvset{fontsize=\\small}', to mitigate the size difference between the default monospaced font (Courier) and the default text font (Times). You may need to modify this if you use custom fonts.
• 'xelatex' and 'lualatex' use '\\fvset{fontsize=auto}', as there is no size difference between the regular and the monospaced fonts used by default by Sphinx with these engines.

New in version 1.8.

• Keys that are set by other options and therefore should not be overridden are:

'docclass' 'classoptions' 'title' 'date' 'release' 'author' 'logo' 'makeindex'

latex_docclass

A dictionary mapping 'howto' and 'manual' to names of real document classes that will be used as the base for the two Sphinx classes. Default is to use 'article' for 'howto' and 'report' for 'manual'.

New in version 1.0.

Changed in version 1.5: In Japanese docs (language is 'ja'), by default 'jreport' is used for 'howto' and 'jsbook' for 'manual'.

latex_additional_files

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.

Changed in version 1.2: This overrides the files which is provided from Sphinx such as sphinx.sty.

Options for text output¶

These options influence text output.

text_newlines

Determines which end-of-line character(s) are used in text output.

• 'unix': use Unix-style line endings (\n)
• 'windows': use Windows-style line endings (\r\n)
• 'native': use the line ending style of the platform the documentation is built on

Default: 'unix'.

New in version 1.1.

text_sectionchars

A string of 7 characters that should be used for underlining sections. The first character is used for first-level headings, the second for second-level headings and so on.

The default is '*=-~"+'.

New in version 1.1.

text_add_secnumbers

A boolean that decides whether section numbers are included in text output. Default is True.

New in version 1.7.

text_secnumber_suffix

Suffix for section numbers in text output. Default: ". ". Set to " " to suppress the final dot on section numbers.

New in version 1.7.

Options for manual page output¶

These options influence manual page output.

man_pages

This value determines how to group the document tree into manual pages. It must be a list of tuples (startdocname, name, description, authors, section), where the items are:

startdocname
String that specifies the document name of the manual page’s master document. All documents referenced by the startdoc document in TOC trees will be included in the manual file. (If you want to use the default master document for your manual pages build, use your master_doc here.)
name
Name of the manual page. This should be a short string without spaces or special characters. It is used to determine the file name as well as the name of the manual page (in the NAME section).
description
Description of the manual page. This is used in the NAME section.
authors
A list of strings with authors, or a single string. Can be an empty string or list if you do not want to automatically generate an AUTHORS section in the manual page.
section
The manual page section. Used for the output file name as well as in the manual page header.

New in version 1.0.

man_show_urls

If true, add URL addresses after links. Default is False.

New in version 1.1.

Options for Texinfo output¶

These options influence Texinfo output.

texinfo_documents

This value determines how to group the document tree into Texinfo source files. It must be a list of tuples (startdocname, targetname, title, author, dir_entry, description, category, toctree_only), where the items are:

startdocname
String that specifies the document name of the the Texinfo file’s master document. All documents referenced by the startdoc document in TOC trees will be included in the Texinfo file. (If you want to use the default master document for your Texinfo build, provide your master_doc here.)
targetname
File name (no extension) of the Texinfo file in the output directory.
title
Texinfo document title. Can be empty to use the title of the startdoc document. Inserted as Texinfo markup, so special characters like @ and {} will need to be escaped to be inserted literally.
author
Author for the Texinfo document. Inserted as Texinfo markup. Use @* to separate multiple authors, as in: 'John@*Sarah'.
dir_entry
The name that will appear in the top-level DIR menu file.
description
Descriptive text to appear in the top-level DIR menu file.
category
Specifies the section which this entry will appear in the top-level DIR menu file.
toctree_only
Must be True or False. If true, the startdoc document itself is not included in the output, only the documents referenced by it via TOC trees. With this option, you can put extra stuff in the master document that shows up in the HTML, but not the Texinfo output.

New in version 1.1.

texinfo_appendices

A list of document names to append as an appendix to all manuals.

New in version 1.1.

texinfo_domain_indices

If true, generate domain-specific indices in addition to the general index. For e.g. the Python domain, this is the global module index. Default is True.

This value can be a bool or a list of index names that should be generated, like for html_domain_indices.

New in version 1.1.

texinfo_show_urls

Control how to display URL addresses.

• 'footnote' – display URLs in footnotes (default)
• 'no' – do not display URLs
• 'inline' – display URLs inline in parentheses

New in version 1.1.

texinfo_no_detailmenu

If true, do not generate a @detailmenu in the “Top” node’s menu containing entries for each sub-node in the document. Default is False.

New in version 1.2.

texinfo_elements

A dictionary that contains Texinfo snippets that override those Sphinx usually puts into the generated .texi files.

• Keys that you may want to override include:

'paragraphindent'

Number of spaces to indent the first line of each paragraph, default 2. Specify 0 for no indentation.

'exampleindent'

Number of spaces to indent the lines for examples or literal blocks, default 4. Specify 0 for no indentation.

'preamble'

Texinfo markup inserted near the beginning of the file.

'copying'

Texinfo markup inserted within the @copying block and displayed after the title. The default value consists of a simple title page identifying the project.

• Keys that are set by other options and therefore should not be overridden are:

'author' 'body' 'date' 'direntry' 'filename' 'project' 'release' 'title'

New in version 1.1.

Options for QtHelp output¶

These options influence qthelp output. As this builder derives from the HTML builder, the HTML options also apply where appropriate.

qthelp_basename

The basename for the qthelp file. It defaults to the project name.

qthelp_namespace

The namespace for the qthelp file. It defaults to org.sphinx.<project_name>.<project_version>.

qthelp_theme

The HTML theme for the qthelp output. This defaults to 'nonav'.

qthelp_theme_options

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.

linkcheck_ignore

A list of regular expressions that match URIs that should not be checked when doing a linkcheck build. Example:

linkcheck_ignore = [r'http://localhost:\d+/']


New in version 1.1.

linkcheck_retries

The number of times the linkcheck builder will attempt to check a URL before declaring it broken. Defaults to 1 attempt.

New in version 1.4.

linkcheck_timeout

A timeout value, in seconds, for the linkcheck builder. The default is to use Python’s global socket timeout.

New in version 1.1.

linkcheck_workers

New in version 1.1.

linkcheck_anchors

If true, check the validity of #anchors in links. Since this requires downloading the whole document, it’s considerably slower when enabled. Default is True.

New in version 1.2.

linkcheck_anchors_ignore

A list of regular expressions that match anchors Sphinx should skip when checking the validity of anchors in links. This allows skipping anchors that a website’s JavaScript adds to control dynamic pages or when triggering an internal REST request. Default is ["^!"].

Note

If you want to ignore anchors of a specific page or of pages that match a specific pattern (but still check occurrences of the same page(s) that don’t have anchors), use linkcheck_ignore instead, for example as follows:

linkcheck_ignore = [
'http://www.sphinx-doc.org/en/1.7/intro.html#'
]


New in version 1.5.

Options for the XML builder¶

xml_pretty

If true, pretty-print the XML. Default is True.

New in version 1.2.

Footnotes

 [1] (1, 2) 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.

Options for the C++ domain¶

cpp_index_common_prefix

A list of prefixes that will be ignored when sorting C++ objects in the global index. For example ['awesome_lib::'].

New in version 1.5.

cpp_id_attributes

A list of strings that the parser additionally should accept as attributes. This can for example be used when attributes have been #define d for portability.

New in version 1.5.

cpp_paren_attributes

A list of strings that the parser additionally should accept as attributes with one argument. That is, if my_align_as is in the list, then my_align_as(X) is parsed as an attribute for all strings X that have balanced braces ((), [], and {}). This can for example be used when attributes have been #define d for portability.

New in version 1.5.

Example of configuration file¶

# -*- coding: utf-8 -*-
#
# test documentation build configuration file, created by
# sphinx-quickstart on Sun Jun 26 00:00:43 2016.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

# -- General configuration ------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'

# The encoding of source files.
#
# source_encoding = 'utf-8-sig'

# The master toctree document.
master_doc = 'index'

# General information about the project.
project = u'test'
author = u'test'

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = u'test'
# The full version, including alpha/beta/rc tags.
release = u'test'

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None

# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#
# today = ''
#
# Else, today_fmt is used as the format for a strftime call.
#
# today_fmt = '%B %d, %Y'

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# These patterns also affect html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# The reST default role (used for this markup: text) to use for all
# documents.
#
# default_role = None

# If true, '()' will be appended to :func: etc. cross-reference text.
#

# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#

# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#
# show_authors = False

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []

# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False

# If true, todo and todoList produce output, else they produce nothing.
todo_include_todos = False

# -- Options for HTML output ----------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'

# Theme options are theme-specific and customize the look and feel of a theme
# further.  For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}

# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = []

# The name for this set of Sphinx documents.
# "<project> v<release> documentation" by default.
#
# html_title = u'test vtest'

# A shorter title for the navigation bar.  Default is the same as html_title.
#
# html_short_title = None

# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#
# html_logo = None

# The name of an image file (relative to this directory) to use as a favicon of
# the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#
# html_favicon = None

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#
# html_extra_path = []

# If not None, a 'Last updated on:' timestamp is inserted at every page
# bottom, using the given strftime format.
# The empty string is equivalent to '%b %d, %Y'.
#
# html_last_updated_fmt = None

# Custom sidebar templates, maps document names to template names.
#
# html_sidebars = {}

# Additional templates that should be rendered to pages, maps page names to
# template names.
#

# If false, no module index is generated.
#
# html_domain_indices = True

# If false, no index is generated.
#
# html_use_index = True

# If true, the index is split into individual pages for each letter.
#
# html_split_index = False

# If true, links to the reST sources are added to the pages.
#

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#
# html_show_sphinx = True

# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#

# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it.  The value of this option must be the
# base URL from which the finished HTML is served.
#
# html_use_opensearch = ''

# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None

# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
#
# html_search_language = 'en'

# A dictionary with options for the search language support, empty by default.
# 'ja' uses this config value.
# 'zh' user can custom change jieba dictionary path.
#
# html_search_options = {'type': 'default'}

# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#
# html_search_scorer = 'scorer.js'

# Output file base name for HTML help builder.
htmlhelp_basename = 'testdoc'

# -- Options for LaTeX output ---------------------------------------------

latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',

# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',

# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',

# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
#  author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'test.tex', u'test Documentation',
u'test', 'manual'),
]

# The name of an image file (relative to this directory) to place at the top of
# the title page.
#
# latex_logo = None

# If true, show page references after internal links.
#
# latex_show_pagerefs = False

#
# latex_show_urls = False

# Documents to append as an appendix to all manuals.
#
# latex_appendices = []

# If false, no module index is generated.
#
# latex_domain_indices = True

# -- Options for manual page output ---------------------------------------

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'test', u'test Documentation',
[author], 1)
]

#
# man_show_urls = False

# -- Options for Texinfo output -------------------------------------------

# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
#  dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'test', u'test Documentation',
author, 'test', 'One line description of project.',
'Miscellaneous'),
]

# Documents to append as an appendix to all manuals.
#
# texinfo_appendices = []

# If false, no module index is generated.
#
# texinfo_domain_indices = True

# How to display URL addresses: 'footnote', 'no', or 'inline'.
#
# texinfo_show_urls = 'footnote'

# If true, do not generate a @detailmenu in the "Top" node's menu.
#

# -- A random example -----------------------------------------------------

import sys, os
sys.path.insert(0, os.path.abspath('.'))
exclude_patterns = ['zzz']

numfig = True
#language = 'ja'

extensions.append('sphinx.ext.todo')
extensions.append('sphinx.ext.autodoc')
#extensions.append('sphinx.ext.autosummary')
extensions.append('sphinx.ext.intersphinx')
extensions.append('sphinx.ext.mathjax')
extensions.append('sphinx.ext.viewcode')
extensions.append('sphinx.ext.graphviz')

autosummary_generate = True
html_theme = 'default'
#source_suffix = ['.rst', '.txt']
`