mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
2547 lines
83 KiB
ReStructuredText
2547 lines
83 KiB
ReStructuredText
.. highlight:: python
|
||
|
||
.. _build-config:
|
||
|
||
=============
|
||
Configuration
|
||
=============
|
||
|
||
.. module:: conf
|
||
:synopsis: Build configuration file.
|
||
|
||
The :term:`configuration directory` must contain a file named :file:`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.
|
||
|
||
.. _`docutils`: http://docutils.sourceforge.net/
|
||
.. _`docutils.conf`: http://docutils.sourceforge.net/docs/user/config.html
|
||
|
||
The configuration file is executed as Python code at build time (using
|
||
:func:`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 :file:`conf.py` is read as a Python file, the usual rules apply for
|
||
encodings and Unicode support.
|
||
|
||
* 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.
|
||
|
||
.. _conf-tags:
|
||
|
||
* There is a special object named ``tags`` available in the config file.
|
||
It can be used to query and change the tags (see :ref:`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.
|
||
|
||
|
||
Project information
|
||
-------------------
|
||
|
||
.. confval:: project
|
||
|
||
The documented project's name.
|
||
|
||
.. confval:: author
|
||
|
||
The author name(s) of the document. The default value is ``'unknown'``.
|
||
|
||
.. confval:: copyright
|
||
|
||
A copyright statement in the style ``'2008, Author Name'``.
|
||
|
||
.. confval:: version
|
||
|
||
The major project version, used as the replacement for ``|version|``. For
|
||
example, for the Python documentation, this may be something like ``2.6``.
|
||
|
||
.. confval:: release
|
||
|
||
The full project version, used as the replacement for ``|release|`` and
|
||
e.g. in the HTML templates. For example, for the Python documentation, this
|
||
may be something like ``2.6.0rc1``.
|
||
|
||
If you don't need the separation provided between :confval:`version` and
|
||
:confval:`release`, just set them both to the same value.
|
||
|
||
|
||
General configuration
|
||
---------------------
|
||
|
||
.. confval:: extensions
|
||
|
||
A list of strings that are module names of :doc:`extensions
|
||
<extensions/index>`. These can be extensions coming with Sphinx (named
|
||
``sphinx.ext.*``) or custom ones.
|
||
|
||
Note that you can extend :data:`sys.path` within the conf file if your
|
||
extensions live in another directory -- but make sure you use absolute paths.
|
||
If your extension path is relative to the :term:`configuration directory`,
|
||
use :func:`os.path.abspath` like so::
|
||
|
||
import sys, os
|
||
|
||
sys.path.append(os.path.abspath('sphinxext'))
|
||
|
||
extensions = ['extname']
|
||
|
||
That way, you can load an extension called ``extname`` from the subdirectory
|
||
``sphinxext``.
|
||
|
||
The configuration file itself can be an extension; for that, you only need
|
||
to provide a :func:`setup` function in it.
|
||
|
||
.. confval:: 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``).
|
||
|
||
.. versionchanged:: 1.3
|
||
Can now be a list of extensions.
|
||
|
||
.. versionchanged:: 1.8
|
||
Support file type mapping
|
||
|
||
.. confval:: source_encoding
|
||
|
||
The encoding of all reST source files. The recommended encoding, and the
|
||
default value, is ``'utf-8-sig'``.
|
||
|
||
.. versionadded:: 0.5
|
||
Previously, Sphinx accepted only UTF-8 encoded sources.
|
||
|
||
.. confval:: 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 :class:`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::
|
||
|
||
Refer to :doc:`/usage/markdown` for more information on using Markdown
|
||
with Sphinx.
|
||
|
||
.. versionadded:: 1.3
|
||
|
||
.. deprecated:: 1.8
|
||
Now Sphinx provides an API :meth:`.Sphinx.add_source_parser` to register
|
||
a source parser. Please use it instead.
|
||
|
||
.. confval:: master_doc
|
||
|
||
The document name of the "master" document, that is, the document that
|
||
contains the root :rst:dir:`toctree` directive. Default is ``'index'``.
|
||
|
||
.. versionchanged:: 2.0
|
||
The default is changed to ``'index'`` from ``'contents'``.
|
||
|
||
.. confval:: 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 :confval:`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
|
||
|
||
:confval:`exclude_patterns` is also consulted when looking for static files
|
||
in :confval:`html_static_path` and :confval:`html_extra_path`.
|
||
|
||
.. versionadded:: 1.0
|
||
|
||
.. confval:: 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.
|
||
|
||
.. versionchanged:: 1.3
|
||
As these files are not meant to be built, they are automatically added to
|
||
:confval:`exclude_patterns`.
|
||
|
||
.. confval:: template_bridge
|
||
|
||
A string with the fully-qualified name of a callable (or simply a class)
|
||
that returns an instance of :class:`~sphinx.application.TemplateBridge`.
|
||
This instance is then used to render HTML documents, and possibly the output
|
||
of other builders (currently the changes builder). (Note that the template
|
||
bridge must be made theme-aware if HTML themes are to be used.)
|
||
|
||
.. confval:: rst_epilog
|
||
|
||
.. index:: pair: global; substitutions
|
||
|
||
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 :confval:`rst_prolog`). An
|
||
example::
|
||
|
||
rst_epilog = """
|
||
.. |psf| replace:: Python Software Foundation
|
||
"""
|
||
|
||
.. versionadded:: 0.6
|
||
|
||
.. confval:: rst_prolog
|
||
|
||
.. index:: pair: global; substitutions
|
||
|
||
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 :confval:`rst_epilog`). An
|
||
example::
|
||
|
||
rst_prolog = """
|
||
.. |psf| replace:: Python Software Foundation
|
||
"""
|
||
|
||
.. versionadded:: 1.0
|
||
|
||
.. confval:: primary_domain
|
||
|
||
.. index:: default; domain
|
||
primary; domain
|
||
|
||
The name of the default :doc:`domain </usage/restructuredtext/domains>`.
|
||
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 :rst:dir:`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").
|
||
|
||
.. versionadded:: 1.0
|
||
|
||
.. confval:: default_role
|
||
|
||
.. index:: 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 :rst:dir:`default-role` directive.
|
||
|
||
.. versionadded:: 0.4
|
||
|
||
.. confval:: 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.
|
||
|
||
.. versionadded:: 0.5
|
||
|
||
.. confval:: suppress_warnings
|
||
|
||
A list of warning types to suppress arbitrary warning messages.
|
||
|
||
Sphinx supports following warning types:
|
||
|
||
* ``app.add_node``
|
||
* ``app.add_directive``
|
||
* ``app.add_role``
|
||
* ``app.add_generic_role``
|
||
* ``app.add_source_parser``
|
||
* ``download.not_readable``
|
||
* ``image.not_readable``
|
||
* ``ref.term``
|
||
* ``ref.ref``
|
||
* ``ref.numref``
|
||
* ``ref.keyword``
|
||
* ``ref.option``
|
||
* ``ref.citation``
|
||
* ``ref.footnote``
|
||
* ``ref.doc``
|
||
* ``ref.python``
|
||
* ``misc.highlighting_failure``
|
||
* ``toc.circular``
|
||
* ``toc.secnum``
|
||
* ``epub.unknown_project_files``
|
||
* ``autosectionlabel.*``
|
||
|
||
You can choose from these types.
|
||
|
||
Now, this option should be considered *experimental*.
|
||
|
||
.. versionadded:: 1.4
|
||
|
||
.. versionchanged:: 1.5
|
||
|
||
Added ``misc.highlighting_failure``
|
||
|
||
.. versionchanged:: 1.5.1
|
||
|
||
Added ``epub.unknown_project_files``
|
||
|
||
.. versionchanged:: 1.6
|
||
|
||
Added ``ref.footnote``
|
||
|
||
.. versionchanged:: 2.1
|
||
|
||
Added ``autosectionlabel.*``
|
||
|
||
.. confval:: 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.
|
||
|
||
.. versionadded:: 1.0
|
||
|
||
.. versionchanged:: 1.4
|
||
also accepts micro version string
|
||
|
||
.. confval:: needs_extensions
|
||
|
||
This value can be a dictionary specifying version requirements for
|
||
extensions in :confval:`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
|
||
:ref:`dev-extensions` for how to do that).
|
||
|
||
.. versionadded:: 1.3
|
||
|
||
.. confval:: manpages_url
|
||
|
||
A URL to cross-reference :rst:role:`manpage` directives. If this is
|
||
defined to ``https://manpages.debian.org/{path}``, the
|
||
:literal:`: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.
|
||
|
||
.. versionadded:: 1.7
|
||
|
||
.. confval:: 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 :option:`-n <sphinx-build -n>` command-line switch.
|
||
|
||
.. versionadded:: 1.0
|
||
|
||
.. confval:: 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')``.
|
||
|
||
.. versionadded:: 1.1
|
||
|
||
.. confval:: numfig
|
||
|
||
If true, figures, tables and code-blocks are automatically numbered if they
|
||
have a caption. The :rst:role:`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.
|
||
|
||
.. versionadded:: 1.3
|
||
|
||
.. confval:: 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'``.
|
||
|
||
.. versionadded:: 1.3
|
||
|
||
.. confval:: 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 :rst:dir:`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...
|
||
|
||
.. versionadded:: 1.3
|
||
|
||
.. versionchanged:: 1.7
|
||
The LaTeX builder obeys this setting (if :confval:`numfig` is set to
|
||
``True``).
|
||
|
||
.. confval:: 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``.
|
||
|
||
__ http://docutils.sourceforge.net/docs/user/smartquotes.html
|
||
__ https://daringfireball.net/projects/smartypants/
|
||
|
||
.. versionadded:: 1.6.6
|
||
It replaces deprecated :confval:`html_use_smartypants`.
|
||
It applies by default to all builders except ``man`` and ``text``
|
||
(see :confval:`smartquotes_excludes`.)
|
||
|
||
A `docutils.conf`__ file located in the configuration directory (or a
|
||
global :file:`~/.docutils` file) is obeyed unconditionally if it
|
||
*deactivates* smart quotes via the corresponding `Docutils option`__. But
|
||
if it *activates* them, then :confval:`smartquotes` does prevail.
|
||
|
||
__ http://docutils.sourceforge.net/docs/user/config.html
|
||
__ http://docutils.sourceforge.net/docs/user/config.html#smart-quotes
|
||
|
||
.. confval:: smartquotes_action
|
||
|
||
This string customizes the Smart Quotes transform. See the file
|
||
:file:`smartquotes.py` at the `Docutils repository`__ for details. The
|
||
default ``'qDe'`` educates normal **q**\ uote characters ``"``, ``'``,
|
||
em- and en-**D**\ ashes ``---``, ``--``, and **e**\ llipses ``...``.
|
||
|
||
.. versionadded:: 1.6.6
|
||
|
||
__ https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
|
||
|
||
.. confval:: smartquotes_excludes
|
||
|
||
This is a ``dict`` whose default is::
|
||
|
||
{'languages': ['ja'], 'builders': ['man', 'text']}
|
||
|
||
Each entry gives a sufficient condition to ignore the
|
||
:confval:`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 :program:`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 :program:`sphinx-build` as it caches
|
||
(in its default usage) the parsed source files in per builder locations.
|
||
|
||
.. hint:: An alternative way to effectively deactivate (or customize) the
|
||
smart quotes for a given builder, for example ``latex``, is to use
|
||
``make`` this way:
|
||
|
||
.. code-block:: console
|
||
|
||
make latex O="-D smartquotes_action="
|
||
|
||
This can follow some ``make html`` with no problem, in contrast to the
|
||
situation from the prior note. It requires Docutils 0.14 or later.
|
||
|
||
.. versionadded:: 1.6.6
|
||
|
||
.. confval:: user_agent
|
||
|
||
A User-Agent of Sphinx. It is used for a header on HTTP access (ex.
|
||
linkcheck, intersphinx and so on). Default is ``"Sphinx/X.Y.Z
|
||
requests/X.Y.Z python/X.Y.Z"``.
|
||
|
||
.. versionadded:: 2.3
|
||
|
||
.. confval:: tls_verify
|
||
|
||
If true, Sphinx verifies server certifications. Default is ``True``.
|
||
|
||
.. versionadded:: 1.5
|
||
|
||
.. confval:: 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.
|
||
|
||
.. versionadded:: 1.5
|
||
|
||
.. tip:: Sphinx uses requests_ as a HTTP library internally.
|
||
Therefore, Sphinx refers a certification file on the
|
||
directory pointed ``REQUESTS_CA_BUNDLE`` environment
|
||
variable if ``tls_cacerts`` not set.
|
||
|
||
.. _requests: https://requests.readthedocs.io/en/master/
|
||
|
||
.. confval:: today
|
||
today_fmt
|
||
|
||
These values determine how to format the current date, used as the
|
||
replacement for ``|today|``.
|
||
|
||
* If you set :confval:`today` to a non-empty value, it is used.
|
||
* Otherwise, the current time is formatted using :func:`time.strftime` and
|
||
the format given in :confval:`today_fmt`.
|
||
|
||
The default is now :confval:`today` and a :confval:`today_fmt` of ``'%B %d,
|
||
%Y'`` (or, if translation is enabled with :confval:`language`, an equivalent
|
||
format for the selected locale).
|
||
|
||
.. confval:: highlight_language
|
||
|
||
The default language to highlight source code in. The default is
|
||
``'python3'``. The value should be a valid Pygments lexer name, see
|
||
:ref:`code-examples` for more details.
|
||
|
||
.. versionadded:: 0.5
|
||
|
||
.. versionchanged:: 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'``.
|
||
|
||
.. confval:: highlight_options
|
||
|
||
A dictionary of options that modify how the lexer specified by
|
||
:confval:`highlight_language` generates highlighted source code. These are
|
||
lexer-specific; for the options understood by each, see the
|
||
`Pygments documentation <https://pygments.org/docs/lexers.html>`_.
|
||
|
||
.. versionadded:: 1.3
|
||
|
||
.. confval:: 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.
|
||
|
||
.. versionchanged:: 0.3
|
||
If the value is a fully-qualified name of a custom Pygments style class,
|
||
this is then used as custom style.
|
||
|
||
.. confval:: add_function_parentheses
|
||
|
||
A boolean that decides whether parentheses are appended to function and
|
||
method role text (e.g. the content of ``:func:`input```) to signify that the
|
||
name is callable. Default is ``True``.
|
||
|
||
.. confval:: add_module_names
|
||
|
||
A boolean that decides whether module names are prepended to all
|
||
:term:`object` names (for object types where a "module" of some kind is
|
||
defined), e.g. for :rst:dir:`py:function` directives. Default is ``True``.
|
||
|
||
.. confval:: show_authors
|
||
|
||
A boolean that decides whether :rst:dir:`codeauthor` and
|
||
:rst:dir:`sectionauthor` directives produce any output in the built files.
|
||
|
||
.. confval:: 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
|
||
``[]``.
|
||
|
||
.. versionadded:: 0.6
|
||
|
||
.. confval:: 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.
|
||
|
||
.. versionadded:: 0.6
|
||
|
||
.. confval:: 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 :mod:`~sphinx.ext.doctest` for more
|
||
possibilities of including doctests.
|
||
|
||
.. versionadded:: 1.0
|
||
.. versionchanged:: 1.1
|
||
Now also removes ``<BLANKLINE>``.
|
||
|
||
.. confval:: strip_signature_backslash
|
||
|
||
Default is ``False``.
|
||
When backslash stripping is enabled then every occurrence of ``\\`` in a
|
||
domain directive will be changed to ``\``, even within string literals.
|
||
This was the behaviour before version 3.0, and setting this variable to
|
||
``True`` will reinstate that behaviour.
|
||
|
||
.. versionadded:: 3.0
|
||
|
||
|
||
.. _intl-options:
|
||
|
||
Options for internationalization
|
||
--------------------------------
|
||
|
||
These options influence Sphinx's *Native Language Support*. See the
|
||
documentation on :ref:`intl` for details.
|
||
|
||
.. confval:: 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 :confval:`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.
|
||
|
||
.. versionadded:: 0.5
|
||
|
||
.. versionchanged:: 1.4
|
||
|
||
Support figure substitution
|
||
|
||
Currently supported languages by Sphinx are:
|
||
|
||
* ``ar`` -- Arabic
|
||
* ``bg`` -- Bulgarian
|
||
* ``bn`` -- Bengali
|
||
* ``ca`` -- Catalan
|
||
* ``cak`` -- Kaqchikel
|
||
* ``cs`` -- Czech
|
||
* ``cy`` -- Welsh
|
||
* ``da`` -- Danish
|
||
* ``de`` -- German
|
||
* ``el`` -- Greek
|
||
* ``en`` -- English
|
||
* ``eo`` -- Esperanto
|
||
* ``es`` -- Spanish
|
||
* ``et`` -- Estonian
|
||
* ``eu`` -- Basque
|
||
* ``fa`` -- Iranian
|
||
* ``fi`` -- Finnish
|
||
* ``fr`` -- French
|
||
* ``he`` -- Hebrew
|
||
* ``hi`` -- Hindi
|
||
* ``hi_IN`` -- Hindi (India)
|
||
* ``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`` -- Portuguese
|
||
* ``pt_BR`` -- Brazilian Portuguese
|
||
* ``pt_PT`` -- European Portuguese
|
||
* ``ro`` -- Romanian
|
||
* ``ru`` -- Russian
|
||
* ``si`` -- Sinhala
|
||
* ``sk`` -- Slovak
|
||
* ``sl`` -- Slovenian
|
||
* ``sq`` -- Albanian
|
||
* ``sr`` -- Serbian
|
||
* ``sr@latin`` -- Serbian (Latin)
|
||
* ``sr_RS`` -- Serbian (Cyrillic)
|
||
* ``sv`` -- Swedish
|
||
* ``ta`` -- Tamil
|
||
* ``te`` -- Telugu
|
||
* ``tr`` -- Turkish
|
||
* ``uk_UA`` -- Ukrainian
|
||
* ``ur`` -- Urdu
|
||
* ``vi`` -- Vietnamese
|
||
* ``zh_CN`` -- Simplified Chinese
|
||
* ``zh_TW`` -- Traditional Chinese
|
||
|
||
.. confval:: locale_dirs
|
||
|
||
.. versionadded:: 0.5
|
||
|
||
Directories in which to search for additional message catalogs (see
|
||
:confval:`language`), relative to the source directory. The directories on
|
||
this path are searched by the standard :mod:`gettext` module.
|
||
|
||
Internal messages are fetched from a text domain of ``sphinx``; so if you
|
||
add the directory :file:`./locale` to this setting, the message catalogs
|
||
(compiled from ``.po`` format using :program:`msgfmt`) must be in
|
||
:file:`./locale/{language}/LC_MESSAGES/sphinx.mo`. The text domain of
|
||
individual documents depends on :confval:`gettext_compact`.
|
||
|
||
The default is ``['locales']``.
|
||
|
||
.. versionchanged:: 1.5
|
||
Use ``locales`` directory as a default value
|
||
|
||
.. confval:: gettext_compact
|
||
|
||
.. versionadded:: 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``.
|
||
|
||
.. confval:: 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
|
||
:command:`pip install python-levenshtein`.
|
||
|
||
The default is ``False``.
|
||
|
||
.. versionadded:: 1.3
|
||
|
||
.. confval:: gettext_location
|
||
|
||
If true, Sphinx generates location information for messages in message
|
||
catalogs.
|
||
|
||
The default is ``True``.
|
||
|
||
.. versionadded:: 1.3
|
||
|
||
.. confval:: gettext_auto_build
|
||
|
||
If true, Sphinx builds mo file for each translation catalog files.
|
||
|
||
The default is ``True``.
|
||
|
||
.. versionadded:: 1.3
|
||
|
||
.. confval:: 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-block: literal blocks (``::`` annotation and ``code-block`` directive)
|
||
:doctest-block: doctest block
|
||
:raw: raw content
|
||
:image: image/figure uri and alt
|
||
|
||
For example: ``gettext_additional_targets = ['literal-block', 'image']``.
|
||
|
||
The default is ``[]``.
|
||
|
||
.. versionadded:: 1.3
|
||
|
||
.. confval:: 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.
|
||
|
||
.. versionadded:: 1.4
|
||
|
||
.. versionchanged:: 1.5
|
||
Added ``{path}`` and ``{basename}`` tokens.
|
||
|
||
|
||
.. _math-options:
|
||
|
||
Options for Math
|
||
----------------
|
||
|
||
These options influence Math notations.
|
||
|
||
.. confval:: math_number_all
|
||
|
||
Set this option to ``True`` if you want all displayed math to be numbered.
|
||
The default is ``False``.
|
||
|
||
.. confval:: 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``.
|
||
|
||
.. confval:: math_numfig
|
||
|
||
If ``True``, displayed math equations are numbered across pages when
|
||
:confval:`numfig` is enabled. The :confval:`numfig_secnum_depth` setting
|
||
is respected. The :rst:role:`eq`, not :rst:role:`numref`, role
|
||
must be used to reference equation numbers. Default is ``True``.
|
||
|
||
.. versionadded:: 1.7
|
||
|
||
|
||
.. _html-options:
|
||
|
||
Options for HTML output
|
||
-----------------------
|
||
|
||
These options influence HTML as well as HTML Help output, and other builders
|
||
that use Sphinx's HTMLWriter class.
|
||
|
||
.. confval:: html_theme
|
||
|
||
The "theme" that the HTML output should use. See the :doc:`section about
|
||
theming </usage/theming>`. The default is ``'alabaster'``.
|
||
|
||
.. versionadded:: 0.6
|
||
|
||
.. confval:: 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 :ref:`this section <builtin-themes>`.
|
||
|
||
.. versionadded:: 0.6
|
||
|
||
.. confval:: 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.
|
||
|
||
.. versionadded:: 0.6
|
||
|
||
.. confval:: html_style
|
||
|
||
The style sheet to use for HTML pages. A file of that name must exist
|
||
either in Sphinx's :file:`static/` path, or in one of the custom paths given
|
||
in :confval:`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.
|
||
|
||
.. confval:: 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 :samp:`'{<project>}
|
||
v{<revision>} documentation'`.
|
||
|
||
.. confval:: 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
|
||
:confval:`html_title`.
|
||
|
||
.. versionadded:: 0.4
|
||
|
||
.. confval:: 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``.
|
||
|
||
.. versionadded:: 1.8
|
||
|
||
.. confval:: 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
|
||
:option:`-A <sphinx-build -A>` command-line option of ``sphinx-build``.
|
||
|
||
.. versionadded:: 0.5
|
||
|
||
.. confval:: html_logo
|
||
|
||
If given, this must be the name of an image file (path relative to the
|
||
:term:`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``.
|
||
|
||
.. versionadded:: 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.
|
||
|
||
.. confval:: html_favicon
|
||
|
||
If given, this must be the name of an image file (path relative to the
|
||
:term:`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``.
|
||
|
||
.. versionadded:: 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.
|
||
|
||
.. confval:: 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 :confval:`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'})]
|
||
|
||
.. versionadded:: 1.8
|
||
|
||
.. confval:: 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 :confval:`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'})]
|
||
|
||
.. versionadded:: 1.8
|
||
|
||
.. confval:: 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
|
||
:file:`_static` directory after the theme's static files, so a file
|
||
named :file:`default.css` will overwrite the theme's
|
||
:file:`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
|
||
:confval:`html_extra_path`. It allows to copy dotfiles under
|
||
the directories.
|
||
|
||
.. versionchanged:: 0.4
|
||
The paths in :confval:`html_static_path` can now contain subdirectories.
|
||
|
||
.. versionchanged:: 1.0
|
||
The entries in :confval:`html_static_path` can now be single files.
|
||
|
||
.. versionchanged:: 1.8
|
||
The files under :confval:`html_static_path` are excluded from source
|
||
files.
|
||
|
||
.. confval:: html_extra_path
|
||
|
||
A list of paths that contain extra files not directly related to
|
||
the documentation, such as :file:`robots.txt` or :file:`.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.
|
||
|
||
.. versionadded:: 1.2
|
||
|
||
.. versionchanged:: 1.4
|
||
The dotfiles in the extra directory will be copied to the output
|
||
directory. And it refers :confval:`exclude_patterns` on copying extra
|
||
files and directories, and ignores if path matches to patterns.
|
||
|
||
.. confval:: html_last_updated_fmt
|
||
|
||
If this is not None, a 'Last updated on:' timestamp is inserted
|
||
at every page bottom, using the given :func:`strftime` format.
|
||
The empty string is equivalent to ``'%b %d, %Y'`` (or a
|
||
locale-dependent equivalent).
|
||
|
||
.. confval:: html_use_smartypants
|
||
|
||
If true, quotes and dashes are converted to typographically correct
|
||
entities. Default: ``True``.
|
||
|
||
.. deprecated:: 1.6
|
||
To disable smart quotes, use rather :confval:`smartquotes`.
|
||
|
||
.. confval:: html_add_permalinks
|
||
|
||
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.
|
||
|
||
.. versionadded:: 0.6
|
||
Previously, this was always activated.
|
||
|
||
.. versionchanged:: 1.1
|
||
This can now be a string to select the actual text of the link.
|
||
Previously, only boolean values were accepted.
|
||
|
||
.. confval:: 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:: 1.7
|
||
|
||
a single string value for ``html_sidebars`` will be removed in 2.0
|
||
|
||
Builtin sidebar templates that can be rendered are:
|
||
|
||
* **localtoc.html** -- a fine-grained table of contents of the current
|
||
document
|
||
* **globaltoc.html** -- a coarse-grained table of contents for the whole
|
||
documentation set, collapsed
|
||
* **relations.html** -- two links to the previous and next documents
|
||
* **sourcelink.html** -- a link to the source of the current document, if
|
||
enabled in :confval:`html_show_sourcelink`
|
||
* **searchbox.html** -- the "quick search" box
|
||
|
||
Example::
|
||
|
||
html_sidebars = {
|
||
'**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
|
||
'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).
|
||
|
||
.. versionadded:: 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.
|
||
|
||
.. confval:: 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 = {
|
||
'download': 'customdownload.html',
|
||
}
|
||
|
||
This will render the template ``customdownload.html`` as the page
|
||
``download.html``.
|
||
|
||
.. confval:: 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'``.
|
||
|
||
.. versionadded:: 1.0
|
||
|
||
.. confval:: html_use_index
|
||
|
||
If true, add an index to the HTML documents. Default is ``True``.
|
||
|
||
.. versionadded:: 0.4
|
||
|
||
.. confval:: 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``.
|
||
|
||
.. versionadded:: 0.4
|
||
|
||
.. confval:: html_copy_source
|
||
|
||
If true, the reST sources are included in the HTML build as
|
||
:file:`_sources/{name}`. The default is ``True``.
|
||
|
||
.. confval:: html_show_sourcelink
|
||
|
||
If true (and :confval:`html_copy_source` is true as well), links to the
|
||
reST sources will be added to the sidebar. The default is ``True``.
|
||
|
||
.. versionadded:: 0.6
|
||
|
||
.. confval:: html_sourcelink_suffix
|
||
|
||
Suffix to be appended to source links (see :confval:`html_show_sourcelink`),
|
||
unless they have this suffix already. Default is ``'.txt'``.
|
||
|
||
.. versionadded:: 1.5
|
||
|
||
.. confval:: html_use_opensearch
|
||
|
||
If nonempty, an `OpenSearch <http://www.opensearch.org/Home>`_ 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 ``''``.
|
||
|
||
.. confval:: html_file_suffix
|
||
|
||
This is the file name suffix for generated HTML files. The default is
|
||
``".html"``.
|
||
|
||
.. versionadded:: 0.4
|
||
|
||
.. confval:: html_link_suffix
|
||
|
||
Suffix for generated links to HTML files. The default is whatever
|
||
:confval:`html_file_suffix` is set to; it can be set differently (e.g. to
|
||
support different web server setups).
|
||
|
||
.. versionadded:: 0.6
|
||
|
||
.. confval:: html_show_copyright
|
||
|
||
If true, "(C) Copyright ..." is shown in the HTML footer. Default is
|
||
``True``.
|
||
|
||
.. versionadded:: 1.0
|
||
|
||
.. confval:: html_show_sphinx
|
||
|
||
If true, "Created using Sphinx" is shown in the HTML footer. Default is
|
||
``True``.
|
||
|
||
.. versionadded:: 0.4
|
||
|
||
.. confval:: 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.
|
||
|
||
.. versionadded:: 1.0
|
||
|
||
.. confval:: 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``.
|
||
|
||
.. versionadded:: 1.0
|
||
|
||
.. confval:: html_secnumber_suffix
|
||
|
||
Suffix for section numbers. Default: ``". "``. Set to ``" "`` to suppress
|
||
the final dot on section numbers.
|
||
|
||
.. versionadded:: 1.0
|
||
|
||
.. confval:: html_search_language
|
||
|
||
Language to be used for generating the HTML full-text search index. This
|
||
defaults to the global language selected with :confval:`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
|
||
|
||
.. admonition:: 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.
|
||
|
||
* `PorterStemmer <https://pypi.org/project/PorterStemmer/>`_ (``en``)
|
||
* `PyStemmer <https://pypi.org/project/PyStemmer/>`_ (all languages)
|
||
|
||
.. versionadded:: 1.1
|
||
With support for ``en`` and ``ja``.
|
||
|
||
.. versionchanged:: 1.3
|
||
Added additional languages.
|
||
|
||
.. confval:: 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 :class:`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 <https://pypi.org/project/Janome/>`_ is required.
|
||
|
||
.. deprecated:: 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:
|
||
_`dict option` is the dictionary to use for the MeCab algorithm.
|
||
:lib:
|
||
_`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:
|
||
_`user_dic_enc option` is the encoding for the user dictionary file
|
||
specified by ``user_dic`` option. Default is 'utf8'.
|
||
|
||
.. versionadded:: 1.1
|
||
|
||
.. versionchanged:: 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.
|
||
|
||
.. confval:: 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.
|
||
|
||
.. XXX describe interface for scorer here
|
||
|
||
.. versionadded:: 1.2
|
||
|
||
.. confval:: html_scaled_image_link
|
||
|
||
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``.
|
||
|
||
Document authors can this feature manually with giving ``no-scaled-link``
|
||
class to the image:
|
||
|
||
.. code-block:: rst
|
||
|
||
.. image:: sphinx.png
|
||
:scale: 50%
|
||
:class: no-scaled-link
|
||
|
||
.. versionadded:: 1.3
|
||
|
||
.. versionchanged:: 3.0
|
||
|
||
It is disabled for images having ``no-scaled-link`` class
|
||
|
||
.. confval:: html_math_renderer
|
||
|
||
The name of math_renderer extension for HTML output. The default is
|
||
``'mathjax'``.
|
||
|
||
.. versionadded:: 1.8
|
||
|
||
.. confval:: html_experimental_html5_writer
|
||
|
||
Output is processed with HTML5 writer. Default is ``False``.
|
||
|
||
.. versionadded:: 1.6
|
||
|
||
.. deprecated:: 2.0
|
||
|
||
.. confval:: html4_writer
|
||
|
||
Output is processed with HTML4 writer. Default is ``False``.
|
||
|
||
Options for Single HTML output
|
||
-------------------------------
|
||
|
||
.. confval:: 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 :confval:`html_sidebars`. By
|
||
default, it is same as :confval:`html_sidebars`.
|
||
|
||
|
||
.. _htmlhelp-options:
|
||
|
||
Options for HTML help output
|
||
-----------------------------
|
||
|
||
.. confval:: htmlhelp_basename
|
||
|
||
Output file base name for HTML help builder. Default is ``'pydoc'``.
|
||
|
||
.. confval:: htmlhelp_file_suffix
|
||
|
||
This is the file name suffix for generated HTML help files. The
|
||
default is ``".html"``.
|
||
|
||
.. versionadded:: 2.0
|
||
|
||
.. confval:: htmlhelp_link_suffix
|
||
|
||
Suffix for generated links to HTML files. The default is ``".html"``.
|
||
|
||
.. versionadded:: 2.0
|
||
|
||
|
||
.. _applehelp-options:
|
||
|
||
Options for Apple Help output
|
||
-----------------------------
|
||
|
||
.. versionadded:: 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 :program:`hiutil` and :program:`codesign` command line tools,
|
||
neither of which are Open Source.
|
||
|
||
You can disable the use of these tools using
|
||
:confval:`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.
|
||
|
||
.. confval:: applehelp_bundle_name
|
||
|
||
The basename for the Apple Help Book. Defaults to the :confval:`project`
|
||
name.
|
||
|
||
.. confval:: applehelp_bundle_id
|
||
|
||
The bundle ID for the help book bundle.
|
||
|
||
.. warning::
|
||
|
||
You *must* set this value in order to generate Apple Help.
|
||
|
||
.. confval:: applehelp_dev_region
|
||
|
||
The development region. Defaults to ``'en-us'``, which is Apple’s
|
||
recommended setting.
|
||
|
||
.. confval:: applehelp_bundle_version
|
||
|
||
The bundle version (as a string). Defaults to ``'1'``.
|
||
|
||
.. confval:: 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.
|
||
|
||
.. confval:: applehelp_kb_product
|
||
|
||
The product tag for use with :confval:`applehelp_kb_url`. Defaults to
|
||
:samp:`'{<project>}-{<release>}'`.
|
||
|
||
.. confval:: 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 :confval:`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.
|
||
|
||
.. confval:: 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.
|
||
|
||
.. confval:: 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.
|
||
|
||
.. confval:: applehelp_min_term_length
|
||
|
||
Controls the minimum term length for the help indexer. Defaults to
|
||
``None``, which means the default will be used.
|
||
|
||
.. confval:: 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 :confval:`language`, or if that is not set, to :confval:`en`.
|
||
|
||
.. confval:: 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 :confval:`language`, or if that is not set, to :confval:`en`.
|
||
|
||
.. confval:: applehelp_title
|
||
|
||
Specifies the help book title. Defaults to :samp:`'{<project>} Help'`.
|
||
|
||
.. confval:: 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.
|
||
|
||
.. confval:: applehelp_codesign_flags
|
||
|
||
A *list* of additional arguments to pass to :program:`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.
|
||
|
||
.. confval:: applehelp_indexer_path
|
||
|
||
The path to the :program:`hiutil` program. Defaults to
|
||
``'/usr/bin/hiutil'``.
|
||
|
||
.. confval:: applehelp_codesign_path
|
||
|
||
The path to the :program:`codesign` program. Defaults to
|
||
``'/usr/bin/codesign'``.
|
||
|
||
.. confval:: 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``.
|
||
|
||
|
||
.. _epub-options:
|
||
|
||
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 <http://dublincore.org/>`_.
|
||
|
||
.. confval:: epub_basename
|
||
|
||
The basename for the epub file. It defaults to the :confval:`project` name.
|
||
|
||
.. confval:: 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.
|
||
|
||
.. confval:: 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 :ref:`this section <builtin-themes>`.
|
||
|
||
.. versionadded:: 1.2
|
||
|
||
.. confval:: epub_title
|
||
|
||
The title of the document. It defaults to the :confval:`html_title` option
|
||
but can be set independently for epub creation. It defaults to the
|
||
:confval:`project` option.
|
||
|
||
.. versionchanged:: 2.0
|
||
It defaults to the ``project`` option.
|
||
|
||
.. confval:: epub_description
|
||
|
||
The description of the document. The default value is ``'unknown'``.
|
||
|
||
.. versionadded:: 1.4
|
||
|
||
.. versionchanged:: 1.5
|
||
Renamed from ``epub3_description``
|
||
|
||
.. confval:: epub_author
|
||
|
||
The author of the document. This is put in the Dublin Core metadata. It
|
||
defaults to the :confval:`author` option.
|
||
|
||
.. confval:: 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'``.
|
||
|
||
.. versionadded:: 1.4
|
||
|
||
.. versionchanged:: 1.5
|
||
Renamed from ``epub3_contributor``
|
||
|
||
.. confval:: epub_language
|
||
|
||
The language of the document. This is put in the Dublin Core metadata. The
|
||
default is the :confval:`language` option or ``'en'`` if unset.
|
||
|
||
.. confval:: 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 :confval:`author` option.
|
||
|
||
.. confval:: epub_copyright
|
||
|
||
The copyright of the document. It defaults to the :confval:`copyright`
|
||
option but can be set independently for epub creation.
|
||
|
||
.. confval:: 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'``.
|
||
|
||
.. confval:: epub_scheme
|
||
|
||
The publication scheme for the :confval:`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'``.
|
||
|
||
.. confval:: epub_uid
|
||
|
||
A unique identifier for the document. This is put in the Dublin Core
|
||
metadata. You may use a
|
||
`XML's Name format <https://www.w3.org/TR/REC-xml/#NT-NameStartChar>`_
|
||
string. You can't use hyphen, period, numbers as a first character. The
|
||
default value is ``'unknown'``.
|
||
|
||
.. confval:: 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 :file:`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 ``()``.
|
||
|
||
.. versionadded:: 1.1
|
||
|
||
.. confval:: 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 :confval:`html_css_files`.
|
||
|
||
.. versionadded:: 1.8
|
||
|
||
.. confval:: epub_guide
|
||
|
||
Meta data for the guide element of :file:`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 ``()``.
|
||
|
||
.. confval:: 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 :file:`toc.ncx`. Example::
|
||
|
||
epub_pre_files = [
|
||
('index.html', 'Welcome'),
|
||
]
|
||
|
||
The default value is ``[]``.
|
||
|
||
.. confval:: 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 :file:`toc.ncx`. The default value is ``[]``.
|
||
|
||
.. confval:: 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 ``[]``.
|
||
|
||
.. confval:: epub_tocdepth
|
||
|
||
The depth of the table of contents in the file :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.
|
||
|
||
.. confval:: 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``.
|
||
|
||
.. confval:: 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
|
||
|
||
.. versionadded:: 1.2
|
||
|
||
.. confval:: 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 Pillow, the Python Image Library,
|
||
installed to use this option. The default value is ``False`` because the
|
||
automatic conversion may lose information.
|
||
|
||
.. versionadded:: 1.2
|
||
|
||
.. confval:: 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.
|
||
|
||
.. versionadded:: 1.2
|
||
|
||
.. confval:: 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``.
|
||
|
||
.. versionadded:: 1.2
|
||
|
||
.. confval:: epub_use_index
|
||
|
||
If true, add an index to the epub document. It defaults to the
|
||
:confval:`html_use_index` option but can be set independently for epub
|
||
creation.
|
||
|
||
.. versionadded:: 1.2
|
||
|
||
.. confval:: epub_writing_mode
|
||
|
||
It specifies writing direction. It can accept ``'horizontal'`` (default) and
|
||
``'vertical'``
|
||
|
||
.. list-table::
|
||
:header-rows: 1
|
||
:stub-columns: 1
|
||
|
||
- * ``epub_writing_mode``
|
||
* ``'horizontal'``
|
||
* ``'vertical'``
|
||
- * writing-mode [#]_
|
||
* ``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.
|
||
|
||
.. [#] https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode
|
||
|
||
|
||
.. _latex-options:
|
||
|
||
Options for LaTeX output
|
||
------------------------
|
||
|
||
These options influence LaTeX output.
|
||
|
||
.. confval:: 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 :confval:`language` is ``'ja'``)
|
||
* ``'uplatex'`` -- upLaTeX (experimental)
|
||
|
||
``'pdflatex'``\ 's support for Unicode characters is limited.
|
||
|
||
.. note::
|
||
|
||
2.0 adds to ``'pdflatex'`` support in Latin language document of
|
||
occasional Cyrillic or Greek letters or words. This is not automatic,
|
||
see the discussion of the :confval:`latex_elements` ``'fontenc'`` key.
|
||
|
||
If your project uses Unicode characters, setting the engine to
|
||
``'xelatex'`` or ``'lualatex'`` and making sure to use an OpenType font
|
||
with wide-enough glyph coverage is often easier than trying to make
|
||
``'pdflatex'`` work with the extra Unicode characters. Since Sphinx 2.0
|
||
the default is the GNU FreeFont which covers well Latin, Cyrillic and
|
||
Greek.
|
||
|
||
.. versionchanged:: 2.1.0
|
||
|
||
Use ``xelatex`` (and LaTeX package ``xeCJK``) by default for Chinese
|
||
documents.
|
||
|
||
.. versionchanged:: 2.2.1
|
||
|
||
Use ``xelatex`` by default for Greek documents.
|
||
|
||
.. versionchanged:: 2.3
|
||
|
||
Add ``uplatex`` support.
|
||
|
||
Contrarily to :ref:`MathJaX math rendering in HTML output <math-support>`,
|
||
LaTeX requires some extra configuration to support Unicode literals in
|
||
:rst:dir:`math`: the only comprehensive solution (as far as we know) is to
|
||
use ``'xelatex'`` or ``'lualatex'`` *and* to add
|
||
``r'\usepackage{unicode-math}'`` (e.g. via the :confval:`latex_elements`
|
||
``'preamble'`` key). You may prefer
|
||
``r'\usepackage[math-style=literal]{unicode-math}'`` to keep a Unicode
|
||
literal such as ``α`` (U+03B1) for example as is in output, rather than
|
||
being rendered as :math:`\alpha`.
|
||
|
||
.. confval:: 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,
|
||
theme, toctree_only)``, where the items are:
|
||
|
||
*startdocname*
|
||
String that specifies the :term:`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 :confval:`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).
|
||
|
||
*theme*
|
||
LaTeX theme. See :confval:`latex_theme`.
|
||
|
||
*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.
|
||
|
||
.. versionadded:: 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.
|
||
|
||
.. versionadded:: 0.3
|
||
The 6th item ``toctree_only``. Tuples with 5 items are still accepted.
|
||
|
||
.. confval:: latex_logo
|
||
|
||
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``.
|
||
|
||
.. confval:: 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``.)
|
||
|
||
.. versionadded:: 1.4
|
||
|
||
.. confval:: latex_appendices
|
||
|
||
A list of document names to append as an appendix to all manuals.
|
||
|
||
.. confval:: 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 :confval:`html_domain_indices`.
|
||
|
||
.. versionadded:: 1.0
|
||
|
||
.. confval:: latex_show_pagerefs
|
||
|
||
If true, add page references after internal references. This is very useful
|
||
for printed copies of the manual. Default is ``False``.
|
||
|
||
.. versionadded:: 1.0
|
||
|
||
.. confval:: 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
|
||
|
||
.. versionadded:: 1.0
|
||
.. versionchanged:: 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.
|
||
|
||
.. confval:: 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
|
||
:rst:dir:`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``.
|
||
|
||
.. versionadded:: 1.6
|
||
|
||
.. confval:: latex_use_xindy
|
||
|
||
If ``True``, the PDF build from the LaTeX files created by Sphinx
|
||
will use :program:`xindy` (doc__) rather than :program:`makeindex`
|
||
for preparing the index of general terms (from :rst:dir:`index`
|
||
usage). This means that words with UTF-8 characters will get
|
||
ordered correctly for the :confval:`language`.
|
||
|
||
__ http://xindy.sourceforge.net/
|
||
|
||
- This option is ignored if :confval:`latex_engine` is ``'platex'``
|
||
(Japanese documents; :program:`mendex` replaces :program:`makeindex`
|
||
then).
|
||
|
||
- The default is ``True`` for ``'xelatex'`` or ``'lualatex'`` as
|
||
:program:`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 :program:`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.
|
||
|
||
.. versionadded:: 1.8
|
||
|
||
.. confval:: latex_elements
|
||
|
||
.. versionadded:: 0.5
|
||
|
||
Its :ref:`documentation <latex_elements_confval>` has moved to :doc:`/latex`.
|
||
|
||
.. confval:: 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'``.
|
||
|
||
.. versionadded:: 1.0
|
||
|
||
.. versionchanged:: 1.5
|
||
|
||
In Japanese docs (:confval:`language` is ``'ja'``), by default
|
||
``'jreport'`` is used for ``'howto'`` and ``'jsbook'`` for ``'manual'``.
|
||
|
||
.. confval:: 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.
|
||
|
||
.. versionadded:: 0.6
|
||
|
||
.. versionchanged:: 1.2
|
||
This overrides the files which is provided from Sphinx such as
|
||
``sphinx.sty``.
|
||
|
||
.. confval:: latex_theme
|
||
|
||
The "theme" that the LaTeX output should use. It is a collection of settings
|
||
for LaTeX output (ex. document class, top level sectioning unit and so on).
|
||
|
||
As a built-in LaTeX themes, ``manual`` and ``howto`` are bundled.
|
||
|
||
``manual``
|
||
A LaTeX theme for writing a manual. It imports the ``report`` document
|
||
class (Japanese documents use ``jsbook``).
|
||
|
||
``howto``
|
||
A LaTeX theme for writing an article. It imports the ``article`` document
|
||
class (Japanese documents use ``jreport`` rather). :confval:`latex_appendices`
|
||
is available only for this theme.
|
||
|
||
It defaults to ``'manual'``.
|
||
|
||
.. versionadded:: 3.0
|
||
|
||
.. confval:: latex_theme_options
|
||
|
||
A dictionary of options that influence the look and feel of the selected
|
||
theme.
|
||
|
||
.. versionadded:: 3.1
|
||
|
||
.. confval:: latex_theme_path
|
||
|
||
A list of paths that contain custom LaTeX themes as subdirectories. Relative
|
||
paths are taken as relative to the configuration directory.
|
||
|
||
.. versionadded:: 3.0
|
||
|
||
|
||
.. _text-options:
|
||
|
||
Options for text output
|
||
-----------------------
|
||
|
||
These options influence text output.
|
||
|
||
.. confval:: 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'``.
|
||
|
||
.. versionadded:: 1.1
|
||
|
||
.. confval:: 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 ``'*=-~"+`'``.
|
||
|
||
.. versionadded:: 1.1
|
||
|
||
.. confval:: text_add_secnumbers
|
||
|
||
A boolean that decides whether section numbers are included in text output.
|
||
Default is ``True``.
|
||
|
||
.. versionadded:: 1.7
|
||
|
||
.. confval:: text_secnumber_suffix
|
||
|
||
Suffix for section numbers in text output. Default: ``". "``. Set to
|
||
``" "`` to suppress the final dot on section numbers.
|
||
|
||
.. versionadded:: 1.7
|
||
|
||
|
||
.. _man-options:
|
||
|
||
Options for manual page output
|
||
------------------------------
|
||
|
||
These options influence manual page output.
|
||
|
||
.. confval:: 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 :term:`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 :confval:`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.
|
||
|
||
.. versionadded:: 1.0
|
||
|
||
.. confval:: man_show_urls
|
||
|
||
If true, add URL addresses after links. Default is ``False``.
|
||
|
||
.. versionadded:: 1.1
|
||
|
||
|
||
.. _texinfo-options:
|
||
|
||
Options for Texinfo output
|
||
--------------------------
|
||
|
||
These options influence Texinfo output.
|
||
|
||
.. confval:: 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 :term:`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
|
||
:confval:`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.
|
||
|
||
.. versionadded:: 1.1
|
||
|
||
.. confval:: texinfo_appendices
|
||
|
||
A list of document names to append as an appendix to all manuals.
|
||
|
||
.. versionadded:: 1.1
|
||
|
||
.. confval:: 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 :confval:`html_domain_indices`.
|
||
|
||
.. versionadded:: 1.1
|
||
|
||
.. confval:: 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
|
||
|
||
.. versionadded:: 1.1
|
||
|
||
.. confval:: 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``.
|
||
|
||
.. versionadded:: 1.2
|
||
|
||
.. confval:: 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'``
|
||
|
||
.. versionadded:: 1.1
|
||
|
||
|
||
.. _qthelp-options:
|
||
|
||
Options for QtHelp output
|
||
--------------------------
|
||
|
||
These options influence qthelp output. As this builder derives from the HTML
|
||
builder, the HTML options also apply where appropriate.
|
||
|
||
.. confval:: qthelp_basename
|
||
|
||
The basename for the qthelp file. It defaults to the :confval:`project`
|
||
name.
|
||
|
||
.. confval:: qthelp_namespace
|
||
|
||
The namespace for the qthelp file. It defaults to
|
||
``org.sphinx.<project_name>.<project_version>``.
|
||
|
||
.. confval:: qthelp_theme
|
||
|
||
The HTML theme for the qthelp output.
|
||
This defaults to ``'nonav'``.
|
||
|
||
.. confval:: 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 :ref:`this section <builtin-themes>`.
|
||
|
||
|
||
Options for the linkcheck builder
|
||
---------------------------------
|
||
|
||
.. confval:: 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+/']
|
||
|
||
.. versionadded:: 1.1
|
||
|
||
.. confval:: linkcheck_retries
|
||
|
||
The number of times the linkcheck builder will attempt to check a URL before
|
||
declaring it broken. Defaults to 1 attempt.
|
||
|
||
.. versionadded:: 1.4
|
||
|
||
.. confval:: linkcheck_timeout
|
||
|
||
A timeout value, in seconds, for the linkcheck builder. The default is to
|
||
use Python's global socket timeout.
|
||
|
||
.. versionadded:: 1.1
|
||
|
||
.. confval:: linkcheck_workers
|
||
|
||
The number of worker threads to use when checking links. Default is 5
|
||
threads.
|
||
|
||
.. versionadded:: 1.1
|
||
|
||
.. confval:: linkcheck_anchors
|
||
|
||
If true, check the validity of ``#anchor``\ s in links. Since this requires
|
||
downloading the whole document, it's considerably slower when enabled.
|
||
Default is ``True``.
|
||
|
||
.. versionadded:: 1.2
|
||
|
||
.. confval:: 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 :confval:`linkcheck_ignore` instead, for example
|
||
as follows::
|
||
|
||
linkcheck_ignore = [
|
||
'http://www.sphinx-doc.org/en/1.7/intro.html#'
|
||
]
|
||
|
||
.. versionadded:: 1.5
|
||
|
||
.. confval:: linkcheck_auth
|
||
|
||
Pass authentication information when doing a ``linkcheck`` build.
|
||
|
||
A list of ``(regex_pattern, auth_info)`` tuples where the items are:
|
||
|
||
*regex_pattern*
|
||
A regular expression that matches a URI.
|
||
*auth_info*
|
||
Authentication information to use for that URI. The value can be anything
|
||
that is understood by the ``requests`` library (see `requests
|
||
Authentication <requests-auth>`_ for details).
|
||
|
||
.. _requests-auth: https://requests.readthedocs.io/en/master/user/authentication/
|
||
|
||
The ``linkcheck`` builder will use the first matching ``auth_info`` value
|
||
it can find in the :confval:`linkcheck_auth` list, so values earlier in the
|
||
list have higher priority.
|
||
|
||
Example::
|
||
|
||
linkcheck_auth = [
|
||
('https://foo\.yourcompany\.com/.+', ('johndoe', 'secret')),
|
||
('https://.+\.yourcompany\.com/.+', HTTPDigestAuth(...)),
|
||
]
|
||
|
||
.. versionadded:: 2.3
|
||
|
||
|
||
Options for the XML builder
|
||
---------------------------
|
||
|
||
.. confval:: xml_pretty
|
||
|
||
If true, pretty-print the XML. Default is ``True``.
|
||
|
||
.. versionadded:: 1.2
|
||
|
||
|
||
.. rubric:: Footnotes
|
||
|
||
.. [1] 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.
|
||
|
||
|
||
.. _c-config:
|
||
|
||
Options for the C domain
|
||
------------------------
|
||
|
||
.. confval:: c_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.
|
||
|
||
.. versionadded:: 3.0
|
||
|
||
.. confval:: c_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.
|
||
|
||
.. versionadded:: 3.0
|
||
|
||
|
||
.. _cpp-config:
|
||
|
||
Options for the C++ domain
|
||
--------------------------
|
||
|
||
.. confval:: cpp_index_common_prefix
|
||
|
||
A list of prefixes that will be ignored when sorting C++ objects in the
|
||
global index. For example ``['awesome_lib::']``.
|
||
|
||
.. versionadded:: 1.5
|
||
|
||
.. confval:: 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.
|
||
|
||
.. versionadded:: 1.5
|
||
|
||
.. confval:: 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.
|
||
|
||
.. versionadded:: 1.5
|
||
|
||
|
||
Example of configuration file
|
||
=============================
|
||
|
||
.. literalinclude:: /_static/conf.py.txt
|
||
:language: python
|