sphinx/doc/usage/configuration.rst

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

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


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.  This 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 ``'restrcturedtext'`` file type.  You can
   add a new file type using source parser extensions.  Please read a document
   of the extension to know what file type the extension supports.

   This also allows a list of file extensions.  In that case, Sphinx conciders
   that all they are ``'restructuredtext'``.  Default is
   ``{'.rst': 'restructuredtext'}``.

   .. note:: file extensions have to start with dot (like ``.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 defualt 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.secnum
   * epub.unknown_project_files

   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``

.. 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, for use with Docutils ``0.14`` or later, 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.

   .. versionadded:: 1.6.6

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


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.

.. 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 <http://pygments.org/docs/lexers/>`_.

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


.. _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:

   * ``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

.. 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: ``::`` and ``code-block``.
   :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 that are used for format of label of references to equations.
   As a special character, ``{number}`` will be replaced to equaition number.

   Example: ``'Eq.{number}'`` is rendered as ``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 </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``.

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

   .. versionadded:: 1.3

.. 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.  This feature needs docutils 0.13 or
   newer.  Default is ``False``.

   .. versionadded:: 1.6

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.

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

   .. 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. Refer to :doc:`/latex` for more
information.

.. 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'``)

   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 :confval:`latex_elements` ``'fontpkg'`` key allows to set up the
   document fonts, see :ref:`this example <latex-basic>`.  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
   :confval:`latex_elements` ``'babel'`` key to override Sphinx's default.

   .. _`Latin Modern`: http://www.gust.org.pl/projects/e-foundry/latin-modern
   .. _`polyglossia`: https://ctan.org/pkg/polyglossia
   .. _`babel`: https://ctan.org/pkg/babel
   .. _`babel-russian`: https://ctan.org/pkg/babel-russian
   .. _`Libertinus`: https://ctan.org/pkg/libertinus

.. 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,
   documentclass, 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).

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

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

   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'``.

        .. versionadded:: 1.5

     ``'sphinxsetup'``
        A comma separated list of ``key=value`` package options for the Sphinx
        LaTeX style, default empty. See :doc:`/latex`.

        .. versionadded:: 1.5

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

        .. versionadded:: 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.

        .. versionchanged:: 1.5
           For :confval:`latex_engine` set to ``'xelatex'``, the default
           is ``'\\usepackage{polyglossia}\n\\setmainlanguage{<language>}'``.
        .. versionchanged:: 1.6
           ``'lualatex'`` uses same default setting as ``'xelatex'``
        .. versionchanged:: 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).

        .. versionchanged:: 1.2
           Defaults to ``''`` when the :confval:`language` uses the Cyrillic
           script.
        .. versionchanged:: 1.5
           Defaults to ``''`` when :confval:`latex_engine` is ``'xelatex'``.
        .. versionchanged:: 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 :doc:`/latex`.

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

        .. versionadded:: 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.

        .. versionadded:: 1.3

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

        .. deprecated:: 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.

        .. versionadded:: 1.2
        .. versionchanged:: 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.

        .. versionadded:: 1.5

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

        .. versionchanged:: 1.4.3
           Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all
           compilers.

     ``'cmappkg'``
        "cmap" package inclusion, default ``'\\usepackage{cmap}'``.

        .. versionadded:: 1.2

     ``'fontenc'``
        "fontenc" package inclusion, default ``'\\usepackage[T1]{fontenc}'``.

        .. versionchanged:: 1.5
           Defaults to ``'\\usepackage{fontspec}'`` when
           :confval:`latex_engine` is ``'xelatex'``.
        .. versionchanged:: 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 :ref:`'sphinxsetup' options
        <latexsphinxsetup>`.

        .. versionadded:: 1.5

        .. versionchanged:: 1.5.2
           ``dvipdfm`` option if :confval:`latex_engine` is ``'platex'``.

        .. versionadded:: 1.5.3
           The :ref:`'sphinxsetup' keys for the margins
           <latexsphinxsetuphmargin>`.

        .. versionchanged:: 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
           :ref:`hmargin <latexsphinxsetuphmargin>` documentation for more.

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

        .. attention::

           Loading of packages "hyperref" and "hypcap" is mandatory.

        .. versionadded:: 1.5
           Previously this was done from inside :file:`sphinx.sty`.

     ``'maketitle'``
        "maketitle" call, default ``'\\maketitle'`` (but it has been
        redefined by the Sphinx ``manual`` and ``howto`` classes.) Override
        if you want to generate a differently-styled title page.

     ``'releasename'``
        value that prefixes ``'release'`` element on title page, default
        ``'Release'``. As for *title* and *author* used in the tuples of
        :confval:`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.

        .. versionchanged:: 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.

        .. versionadded:: 1.2
        .. versionchanged:: 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
        :confval:`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.

        .. versionadded:: 1.8

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

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

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


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


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.


.. _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 brances (``()``, ``[]``, 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