Configuration
*************

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

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

The configuration file is executed as Python code at build time (using
"importlib.import_module()", and with the current directory set to its
containing directory), and therefore can execute arbitrarily complex
code. Sphinx then reads simple names from the file's namespace as its
configuration.

Important points to note:

* If not otherwise documented, values must be strings, and their
  default is the empty string.

* The term "fully-qualified name" refers to a string that names an
  importable Python object inside a module; for example, the FQN
  ""sphinx.builders.Builder"" means the "Builder" class in the
  "sphinx.builders" module.

* Remember that document names use "/" as the path separator and don't
  contain the file name extension.

* Since "conf.py" is read as a Python file, the usual rules apply for
  encodings and Unicode support.

* The contents of the config namespace are pickled (so that Sphinx can
  find out when configuration changes), so it may not contain
  unpickleable values -- delete them from the namespace with "del" if
  appropriate.  Modules are removed automatically, so you don't need
  to "del" your imports after use.

* There is a special object named "tags" available in the config file.
  It can be used to query and change the tags (see Including content
  based on tags).  Use "tags.has('tag')" to query, "tags.add('tag')"
  and "tags.remove('tag')" to change. Only tags set via the "-t"
  command-line option or via "tags.add('tag')" can be queried using
  "tags.has('tag')". Note that the current builder tag is not
  available in "conf.py", as it is created *after* the builder is
  initialized.


Project information
===================

project

   The documented project's name.

author

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

copyright

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

   Changed in version 7.1: The value may now be a sequence of
   copyright statements in the above form, which will be displayed
   each to their own line.

project_copyright

   An alias of "copyright".

   New in version 3.5.

version

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

release

   The full project version, used as the replacement for "|release|"
   and e.g. in the HTML templates.  For example, for the Python
   documentation, this may be something like "2.6.0rc1".

   If you don't need the separation provided between "version" and
   "release", just set them both to the same value.


General configuration
=====================

extensions

   A list of strings that are module names of extensions. These can be
   extensions coming with Sphinx (named "sphinx.ext.*") or custom
   ones.

   Note that you can extend "sys.path" within the conf file if your
   extensions live in another directory -- but make sure you use
   absolute paths. If your extension path is relative to the
   *configuration directory*, use "os.path.abspath()" like so:

      import sys, os

      sys.path.append(os.path.abspath('sphinxext'))

      extensions = ['extname']

   That way, you can load an extension called "extname" from the
   subdirectory "sphinxext".

   The configuration file itself can be an extension; for that, you
   only need to provide a "setup()" function in it.

source_suffix

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

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

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

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

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

   Note:

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

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

   Changed in version 1.8: Support file type mapping

source_encoding

   The encoding of all reST source files.  The recommended encoding,
   and the default value, is "'utf-8-sig'".

   New in version 0.5: Previously, Sphinx accepted only UTF-8 encoded
   sources.

source_parsers

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

   For example:

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

   Note:

     Refer to Markdown for more information on using Markdown with
     Sphinx.

   New in version 1.3.

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

master_doc

   Same as "root_doc".

   Changed in version 4.0: Renamed "master_doc" to "root_doc".

root_doc

   The document name of the "root" document, that is, the document
   that contains the root "toctree" directive.  Default is "'index'".

   Changed in version 2.0: The default is changed to "'index'" from
   "'contents'".

   Changed in version 4.0: Renamed "root_doc" from "master_doc".

exclude_patterns

   A list of glob-style patterns [1] that should be excluded when
   looking for source files. 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

   * "'library/xml'" -- ignores the "library/xml" directory

   * "'library/xml*'" -- ignores all files and directories starting
     with "library/xml"

   * "'**/.svn'" -- ignores all ".svn" directories

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

   New in version 1.0.

include_patterns

   A list of glob-style patterns [1] that are used to find source
   files. They are matched against the source file names relative to
   the source directory, using slashes as directory separators on all
   platforms. The default is "**", meaning that all files are
   recursively included from the source directory.

   Example patterns:

   * "'**'" -- all files in the source directory and subdirectories,
     recursively

   * "'library/xml'" -- just the "library/xml" directory

   * "'library/xml*'" -- all files and directories starting with
     "library/xml"

   * "'**/doc'" -- all "doc" directories (this might be useful if
     documentation is co-located with source files)

   New in version 5.1.

templates_path

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

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

template_bridge

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

rst_epilog

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

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

   New in version 0.6.

rst_prolog

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

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

   New in version 1.0.

primary_domain

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

   New in version 1.0.

default_role

   The name of a reST role (builtin or Sphinx extension) to use as the
   default role, that is, for text marked up "`like this`".  This can
   be set to "'py:obj'" to make "`filter`" a cross-reference to the
   Python function "filter".  The default is "None", which doesn't
   reassign the default role.

   The default role can always be set within individual documents
   using the standard reST default-role directive.

   New in version 0.4.

keep_warnings

   If true, keep warnings as "system message" paragraphs in the built
   documents.  Regardless of this setting, warnings are always written
   to the standard error stream when "sphinx-build" is run.

   The default is "False", the pre-0.5 behavior was to always keep
   them.

   New in version 0.5.

suppress_warnings

   A list of warning types to suppress arbitrary warning messages.

   Sphinx supports following warning types:

   * "app.add_node"

   * "app.add_directive"

   * "app.add_role"

   * "app.add_generic_role"

   * "app.add_source_parser"

   * "autosectionlabel.*"

   * "download.not_readable"

   * "epub.unknown_project_files"

   * "epub.duplicated_toc_entry"

   * "i18n.inconsistent_references"

   * "index"

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

   * "toc.not_readable"

   * "toc.secnum"

   You can choose from these types.  You can also give only the first
   component to exclude all warnings attached to it.

   Now, this option should be considered *experimental*.

   New in version 1.4.

   Changed in version 1.5: Added "misc.highlighting_failure"

   Changed in version 1.5.1: Added "epub.unknown_project_files"

   Changed in version 1.6: Added "ref.footnote"

   Changed in version 2.1: Added "autosectionlabel.*"

   Changed in version 3.3.0: Added "epub.duplicated_toc_entry"

   Changed in version 4.3: Added "toc.excluded" and "toc.not_readable"

   New in version 4.5:

      Added "i18n.inconsistent_references"

   New in version 7.1: Added "index" warning type.

needs_sphinx

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

   New in version 1.0.

   Changed in version 1.4: also accepts micro version string

needs_extensions

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

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

   New in version 1.3.

manpages_url

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

   * "page" - the manual page ("man")

   * "section" - the manual section ("1")

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

   This also supports manpages specified as "man.1".

   Note:

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

   New in version 1.7.

nitpicky

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

   New in version 1.0.

nitpick_ignore

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

   New in version 1.1.

   Changed in version 6.2: Changed allowable container types to a set,
   list, or tuple

nitpick_ignore_regex

   An extended version of "nitpick_ignore", which instead interprets
   the "type" and "target" strings as regular expressions. Note, that
   the regular expression must match the whole string (as if the "^"
   and "$" markers were inserted).

   For example, "(r'py:.*', r'foo.*bar\.B.*')" will ignore nitpicky
   warnings for all python entities that start with "'foo'" and have
   "'bar.B'" in them, such as "('py:const',
   'foo_package.bar.BAZ_VALUE')" or "('py:class', 'food.bar.Barman')".

   New in version 4.1.

   Changed in version 6.2: Changed allowable container types to a set,
   list, or tuple

numfig

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

   Note:

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

   New in version 1.3.

numfig_format

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

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

   New in version 1.3.

numfig_secnum_depth

   * if set to "0", figures, tables and code-blocks are continuously
     numbered starting at "1".

   * if "1" (default) numbers will be "x.1", "x.2", ... with "x" the
     section number (top level sectioning; no "x." if no section).
     This naturally applies only if section numbering has been
     activated via the ":numbered:" option of the "toctree" directive.

   * "2" means that numbers will be "x.y.1", "x.y.2", ... if located
     in a sub-section (but still "x.1", "x.2", ... if located directly
     under a section and "1", "2", ... if not in any top level
     section.)

   * etc...

   New in version 1.3.

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

smartquotes

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

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

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

smartquotes_action

   This string customizes the Smart Quotes transform.  See the 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 "...".

   New in version 1.6.6.

smartquotes_excludes

   This is a "dict" whose default is:

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

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

   Note:

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

   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:

        make latex O="-D smartquotes_action="

     This can follow some "make html" with no problem, in contrast to
     the situation from the prior note.

   New in version 1.6.6.

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

   New in version 2.3.

tls_verify

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

   New in version 1.5.

tls_cacerts

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

   New in version 1.5.

   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.

today
today_fmt

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

   * If you set "today" to a non-empty value, it is used.

   * Otherwise, the current time is formatted using "time.strftime()"
     and the format given in "today_fmt".

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

highlight_language

   The default language to highlight source code in.  The default is
   "'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.

   The value should be a valid Pygments lexer name, see Showing code
   examples for more details.

   New in version 0.5.

   Changed in version 1.4: The default is now "'default'".  If you
   prefer Python 2 only highlighting, you can set it back to
   "'python'".

highlight_options

   A dictionary that maps language names to options for the lexer
   modules of Pygments.  These are lexer-specific; for the options
   understood by each, see the Pygments documentation.

   Example:

      highlight_options = {
        'default': {'stripall': True},
        'php': {'startinline': True},
      }

   A single dictionary of options are also allowed.  Then it is
   recognized as options to the lexer specified by
   "highlight_language":

      # configuration for the ``highlight_language``
      highlight_options = {'stripall': True}

   New in version 1.3.

   Changed in version 3.5: Allow to configure highlight options for
   multiple languages

pygments_style

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

   Changed in version 0.3: If the value is a fully-qualified name of a
   custom Pygments style class, this is then used as custom style.

maximum_signature_line_length

   If a signature's length in characters exceeds the number set, each
   parameter within the signature will be displayed on an individual
   logical line.

   When "None" (the default), there is no maximum length and the
   entire signature will be displayed on a single logical line.

   A 'logical line' is similar to a hard line break---builders or
   themes may choose to 'soft wrap' a single logical line, and this
   setting does not affect that behaviour.

   Domains may provide options to suppress any hard wrapping on an
   individual object directive, such as seen in the C, C++, and Python
   domains (e.g. "py:function:single-line-parameter-list").

   New in version 7.1.

add_function_parentheses

   A boolean that decides whether parentheses are appended to function
   and method role text (e.g. the content of ":func:`input`") to
   signify that the name is callable.  Default is "True".

add_module_names

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

toc_object_entries

   Create table of contents entries for domain objects (e.g.
   functions, classes, attributes, etc.). Default is "True".

toc_object_entries_show_parents

   A string that determines how domain objects (e.g. functions,
   classes, attributes, etc.) are displayed in their table of contents
   entry.

   Use "domain" to allow the domain to determine the appropriate
   number of parents to show. For example, the Python domain would
   show "Class.method()" and "function()", leaving out the "module."
   level of parents. This is the default setting.

   Use "hide" to only show the name of the element without any parents
   (i.e. "method()").

   Use "all" to show the fully-qualified name for the object (i.e.
   "module.Class.method()"),  displaying all parents.

   New in version 5.2.

show_authors

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

modindex_common_prefix

   A list of prefixes that are ignored for sorting the Python module
   index (e.g., if this is set to "['foo.']", then "foo.bar" is shown
   under "B", not "F"). This can be handy if you document a project
   that consists of a single package.  Works only for the HTML builder
   currently.  Default is "[]".

   New in version 0.6.

trim_footnote_reference_space

   Trim spaces before footnote references that are necessary for the
   reST parser to recognize the footnote, but do not look too nice in
   the output.

   New in version 0.6.

trim_doctest_flags

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

   New in version 1.0.

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

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.

   New in version 3.0.

option_emphasise_placeholders

   Default is "False". When enabled, emphasise placeholders in
   "option" directives. To display literal braces, escape with a
   backslash ("\{"). For example, "option_emphasise_placeholders=True"
   and ".. option:: -foption={TYPE}" would render with "TYPE"
   emphasised.

   New in version 5.1.


Options for internationalization
================================

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

language

   The code for the language the docs are written in.  Any text
   automatically generated by Sphinx will be in that language.  Also,
   Sphinx will try to substitute individual paragraphs from your
   documents with the translation sets obtained from "locale_dirs".
   Sphinx will search language-specific figures named by
   "figure_language_filename" (e.g. the German version of
   "myfigure.png" will be "myfigure.de.png" by default setting) 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 "'en'".

   New in version 0.5.

   Changed in version 1.4: Support figure substitution

   Changed in version 5.0.

   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 (default)

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

locale_dirs

   New in version 0.5.

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

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

   The default is "['locales']".

   Note:

     The "-v option for sphinx-build command" is useful to check the
     locale_dirs config works as expected.  It emits debug messages if
     message catalog directory not found.

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

gettext_allow_fuzzy_translations

   If true, "fuzzy" messages in the message catalogs are used for
   translation. The default is "False".

   New in version 4.3.

gettext_compact

   New in version 1.1.

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

   If set to string, all document's text domain is this string, making
   all documents use single text domain.

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

   Changed in version 3.3: The string value is now accepted.

gettext_uuid

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

   * Add uid line for each msgids in .pot files.

   * Calculate similarity between new msgids and previously saved old
     msgids. This calculation takes a long time.

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

   The default is "False".

   New in version 1.3.

gettext_location

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

   The default is "True".

   New in version 1.3.

gettext_auto_build

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

   The default is "True".

   New in version 1.3.

gettext_additional_targets

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

   Index:
      index terms

   Literal-block:
      literal blocks ("::" annotation and "code-block" directive)

   Doctest-block:
      doctest block

   Raw:
      raw content

   Image:
      image/figure uri

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

   The default is "[]".

   New in version 1.3.

   Changed in version 4.0: The alt text for image is translated by
   default.

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/"

   * "{docpath}" - the directory path component for the current
     document, with a trailing slash if non-empty.

   * "{basename}" - the filename without the directory path or file
     extension components, e.g. "filename"

   * "{ext}" - the file extension, e.g. ".png"

   * "{language}" - the translation language, e.g. "en"

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

   New in version 1.4.

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

   Changed in version 3.2: Added "{docpath}" token.

translation_progress_classes

   Control which, if any, classes are added to indicate translation
   progress. This setting would likely only be used by translators of
   documentation, in order to quickly indicate translated and
   untranslated content.

   * "True": add "translated" and "untranslated" classes to all nodes
     with translatable content.

   * "translated": only add the "translated" class.

   * "untranslated": only add the "untranslated" class.

   * "False": do not add any classes to indicate translation progress.

   Defaults to "False".

   New in version 7.1.


Options for Math
================

These options influence Math notations.

math_number_all

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

math_eqref_format

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

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

math_numfig

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

   New in version 1.7.


Options for HTML output
=======================

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

html_theme

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

   New in version 0.6.

html_theme_options

   A dictionary of options that influence the look and feel of the
   selected theme.  These are theme-specific.  For the options
   understood by the builtin themes, see this section.

   New in version 0.6.

html_theme_path

   A list of paths that contain custom themes, either as
   subdirectories or as zip files.  Relative paths are taken as
   relative to the configuration directory.

   New in version 0.6.

html_style

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

html_title

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

html_short_title

   A shorter "title" for the HTML docs.  This is used for links in the
   header and in the HTML Help docs.  If not given, it defaults to the
   value of "html_title".

   New in version 0.4.

html_baseurl

   The base URL which points to the root of the HTML documentation.
   It is used to indicate the location of document using The Canonical
   Link Relation. Default: "''".

   New in version 1.8.

html_codeblock_linenos_style

   The style of line numbers for code-blocks.

   * "'table'" -- display line numbers using "<table>" tag

   * "'inline'" -- display line numbers using "<span>" tag (default)

   New in version 3.2.

   Changed in version 4.0: It defaults to "'inline'".

   Deprecated since version 4.0.

html_context

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

   New in version 0.5.

html_logo

   If given, this must be the name of an image file (path relative to
   the *configuration directory*) that is the logo of the docs, or URL
   that points an image file for the logo.  It is placed at the top of
   the sidebar; its width should therefore not exceed 200 pixels.
   Default: "None".

   New in version 0.4.1: The image file will be copied to the
   "_static" directory of the output HTML, but only if the file does
   not already exist there.

   Changed in version 4.0: Also accepts the URL for the logo file.

html_favicon

   If given, this must be the name of an image file (path relative to
   the *configuration directory*) that is the favicon of the docs, or
   URL that points an image file for the favicon.  Modern browsers use
   this as the icon for tabs, windows and bookmarks.  It should be a
   Windows-style icon file (".ico"), which is 16x16 or 32x32 pixels
   large.  Default: "None".

   New in version 0.4: The image file will be copied to the "_static"
   directory of the output HTML, but only if the file does not already
   exist there.

   Changed in version 4.0: Also accepts the URL for the favicon.

html_css_files

   A list of CSS files.  The entry must be a *filename* string or a
   tuple containing the *filename* string and the *attributes*
   dictionary.  The *filename* must be relative to the
   "html_static_path", or a full URI with scheme like
   "https://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'})]

   As a special attribute, *priority* can be set as an integer to load
   the CSS file earlier or lazier step.  For more information, refer
   "Sphinx.add_css_file()".

   New in version 1.8.

   Changed in version 3.5: Support priority attribute

html_js_files

   A list of JavaScript *filename*.  The entry must be a *filename*
   string or a tuple containing the *filename* string and the
   *attributes* dictionary.  The *filename* must be relative to the
   "html_static_path", or a full URI with scheme like
   "https://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'})]

   As a special attribute, *priority* can be set as an integer to load
   the CSS file earlier or lazier step.  For more information, refer
   "Sphinx.add_css_file()".

   New in version 1.8.

   Changed in version 3.5: Support priority attribute

html_static_path

   A list of paths that contain custom static files (such as style
   sheets or script files).  Relative paths are taken as relative to
   the configuration directory.  They are copied to the output's
   "_static" directory after the theme's static files, so a file named
   "default.css" will overwrite the theme's "default.css".

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

   Note:

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

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

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

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

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

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

html_extra_path

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

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

   New in version 1.2.

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

html_last_updated_fmt

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

html_use_smartypants

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

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

html_permalinks

   If true, Sphinx will add "permalinks" for each heading and
   description environment.  Default: "True".

   New in version 3.5.

html_permalinks_icon

   A text for permalinks for each heading and description environment.
   HTML tags are allowed.  Default: a paragraph sign; "¶"

   New in version 3.5.

html_sidebars

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

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

   The values can be either lists or single strings.

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

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

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

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

   Builtin sidebar templates that can be rendered are:

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

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

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

html_additional_pages

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

   Example:

      html_additional_pages = {
          'download': 'customdownload.html',
      }

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

html_domain_indices

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

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

   New in version 1.0.

html_use_index

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

   New in version 0.4.

html_split_index

   If true, the index is generated twice: once as a single page with
   all the entries, and once as one page per starting letter.  Default
   is "False".

   New in version 0.4.

html_copy_source

   If true, the reST sources are included in the HTML build as
   "_sources/*name*".  The default is "True".

html_show_sourcelink

   If true (and "html_copy_source" is true as well), links to the reST
   sources will be added to the sidebar.  The default is "True".

   New in version 0.6.

html_sourcelink_suffix

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

   New in version 1.5.

html_use_opensearch

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

html_file_suffix

   This is the file name suffix for generated HTML files, if set to a
   "str" value.  If left to the default "None", the suffix will be
   "".html"".

   New in version 0.4.

html_link_suffix

   Suffix for generated links to HTML files.  The default is whatever
   "html_file_suffix" is set to; it can be set differently (e.g. to
   support different web server setups).

   New in version 0.6.

html_show_copyright

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

   New in version 1.0.

html_show_search_summary

   If true, the text around the keyword is shown as summary of each
   search result. Default is "True".

   New in version 4.5.

html_show_sphinx

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

   New in version 0.4.

html_output_encoding

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

   New in version 1.0.

html_compact_lists

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

   New in version 1.0.

html_secnumber_suffix

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

   New in version 1.0.

html_search_language

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

   Support is present for these languages:

   * "da" -- Danish

   * "nl" -- Dutch

   * "en" -- English

   * "fi" -- Finnish

   * "fr" -- French

   * "de" -- German

   * "hu" -- Hungarian

   * "it" -- Italian

   * "ja" -- Japanese

   * "no" -- Norwegian

   * "pt" -- Portuguese

   * "ro" -- Romanian

   * "ru" -- Russian

   * "es" -- Spanish

   * "sv" -- Swedish

   * "tr" -- Turkish

   * "zh" -- Chinese

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

   * PorterStemmer ("en")

   * PyStemmer (all languages)

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

   Changed in version 1.3: Added additional languages.

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:
       is dotted module path string to specify Splitter implementation
      which should be derived from "sphinx.search.ja.BaseSplitter".
      If not specified or "None" is specified,
      "'sphinx.search.ja.DefaultSplitter'" will be used.

      You can choose from these modules:

      'sphinx.search.ja.DefaultSplitter':
         TinySegmenter algorithm. This is default splitter.

      'sphinx.search.ja.MecabSplitter':
         MeCab binding. To use this splitter, 'mecab' python binding
         or dynamic link library ('libmecab.so' for linux,
         'libmecab.dll' for windows) is required.

      'sphinx.search.ja.JanomeSplitter':
         Janome binding. To use this splitter, Janome is required.

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

   Other option values depend on splitter value which you choose.

   Options for "'mecab'":
      dic_enc:
          is the encoding for the MeCab algorithm.

      dict:
          is the dictionary to use for the MeCab algorithm.

      lib:
          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:
          is the user dictionary file path for Janome.

      user_dic_enc:
          is the encoding for the user dictionary file specified by
         "user_dic" option. Default is 'utf8'.

   New in version 1.1.

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

   The Chinese support has these options:

   * "dict"  -- the "jieba" dictionary path if want to use custom
     dictionary.

html_search_scorer

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

   New in version 1.2.

html_scaled_image_link

   If true, image 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 disable this feature manually with giving "no-
   scaled-link" class to the image:

      .. image:: sphinx.png
         :scale: 50%
         :class: no-scaled-link

   New in version 1.3.

   Changed in version 3.0: It is disabled for images having "no-
   scaled-link" class

html_math_renderer

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

   New in version 1.8.

html_experimental_html5_writer

   Output is processed with HTML5 writer.  Default is "False".

   New in version 1.6.

   Deprecated since version 2.0.

html4_writer

   Output is processed with HTML4 writer.  Default is "False".


Options for Single HTML output
==============================

singlehtml_sidebars

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


Options for HTML help output
============================

htmlhelp_basename

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

htmlhelp_file_suffix

   This is the file name suffix for generated HTML help files.  The
   default is "".html"".

   New in version 2.0.

htmlhelp_link_suffix

   Suffix for generated links to HTML files.  The default is
   "".html"".

   New in version 2.0.


Options for Apple Help output
=============================

New in version 1.3.

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

Note:

  Apple Help output will only work on Mac OS X 10.6 and higher, as it
  requires the **hiutil** and **codesign** command line tools, neither
  of which are Open Source.You can disable the use of these tools
  using "applehelp_disable_external_tools", but the result will not be
  a valid help book until the indexer is run over the ".lproj" folders
  within the bundle.

applehelp_bundle_name

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

applehelp_bundle_id

   The bundle ID for the help book bundle.

   Warning:

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

applehelp_dev_region

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

applehelp_bundle_version

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

applehelp_icon

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

applehelp_kb_product

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

applehelp_kb_url

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

   Defaults to "None" for no remote search.

applehelp_remote_url

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

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

   Defaults to "None" for no remote content.

applehelp_index_anchors

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

applehelp_min_term_length

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

applehelp_stopwords

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

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

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

applehelp_locale

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

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

applehelp_title

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

applehelp_codesign_identity

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

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

applehelp_codesign_flags

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

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

applehelp_indexer_path

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

applehelp_codesign_path

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

applehelp_disable_external_tools

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

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

   Defaults to "False".


Options for epub output
=======================

These options influence the epub output.  As this builder derives from
the HTML builder, the HTML options also apply where appropriate.  The
actual values for some of the options is not really important, they
just have to be entered into the Dublin Core metadata.

epub_basename

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

epub_theme

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

epub_theme_options

   A dictionary of options that influence the look and feel of the
   selected theme.  These are theme-specific.  For the options
   understood by the builtin themes, see this section.

   New in version 1.2.

epub_title

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

   Changed in version 2.0: It defaults to the "project" option.

epub_description

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

   New in version 1.4.

   Changed in version 1.5: Renamed from "epub3_description"

epub_author

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

epub_contributor

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

   New in version 1.4.

   Changed in version 1.5: Renamed from "epub3_contributor"

epub_language

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

epub_publisher

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

epub_copyright

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

epub_identifier

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

epub_scheme

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

epub_uid

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

epub_cover

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

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

   The default value is "()".

   New in version 1.1.

epub_css_files

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

   New in version 1.8.

epub_guide

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

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

   The default value is "()".

epub_pre_files

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

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

   The default value is "[]".

epub_post_files

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

epub_exclude_files

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

epub_tocdepth

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

epub_tocdup

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

epub_tocscope

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

   * "'default'" -- include all toc entries that are not hidden
     (default)

   * "'includehidden'" -- include all toc entries

   New in version 1.2.

epub_fix_images

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

   New in version 1.2.

epub_max_image_width

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

   New in version 1.2.

epub_show_urls

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

   * "'inline'" -- display URLs inline in parentheses (default)

   * "'footnote'" -- display URLs in footnotes

   * "'no'" -- do not display URLs

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

   New in version 1.2.

epub_use_index

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

   New in version 1.2.

epub_writing_mode

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

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

   [2] https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode


Options for LaTeX output
========================

These options influence LaTeX output.

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

   * "'uplatex'" -- upLaTeX (default if "language" is "'ja'")

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

   Changed in version 2.1.0: Use "xelatex" (and LaTeX package "xeCJK")
   by default for Chinese documents.

   Changed in version 2.2.1: Use "xelatex" by default for Greek
   documents.

   Changed in version 2.3: Add "uplatex" support.

   Changed in version 4.0: "uplatex" becomes the default setting of
   Japanese documents.

   Contrarily to MathJaX math rendering in HTML output, LaTeX requires
   some extra configuration to support Unicode literals in "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 "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 \alpha.

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 *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 root document for your LaTeX build,
      provide your "root_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 "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.

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

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

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

latex_toplevel_sectioning

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

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

   New in version 1.4.

latex_appendices

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

latex_domain_indices

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

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

   New in version 1.0.

latex_show_pagerefs

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

   New in version 1.0.

latex_show_urls

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

   * "'no'" -- do not display URLs (default)

   * "'footnote'" -- display URLs in footnotes

   * "'inline'" -- display URLs inline in parentheses

   New in version 1.0.

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

latex_use_latex_multicolumn

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

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

   New in version 1.6.

latex_table_style

   A list of styling classes (strings).  Currently supported:

   * "'booktabs'": no vertical lines, and only 2 or 3 horizontal lines
     (the latter if there is a header), using the booktabs package.

   * "'borderless'": no lines whatsoever.

   * "'colorrows'": the table rows are rendered with alternating
     background colours.  The interface to customize them is via
     dedicated keys of The sphinxsetup configuration setting.

     Important:

       With the "'colorrows'" style, the "\rowcolors" LaTeX command
       becomes a no-op (this command has limitations and has never
       correctly supported all types of tables Sphinx produces in
       LaTeX).  Please update your project to use instead the latex
       table color configuration keys.

   Default: "['booktabs', 'colorrows']"

   New in version 5.3.0.

   Changed in version 6.0.0: Modify default from "[]" to "['booktabs',
   'colorrows']".

   Each table can override the global style via ":class:" option, or
   ".. rst-class::" for no-directive tables (cf.  Tables). Currently
   recognized classes are "booktabs", "borderless", "standard",
   "colorrows", "nocolorrows".  The latter two can be combined with
   any of the first three.  The "standard" class produces tables with
   both horizontal and vertical lines (as has been the default so far
   with Sphinx).

   A single-row multi-column merged cell will obey the row colour, if
   it is set.  See also "TableMergeColor{Header,Odd,Even}" in the The
   sphinxsetup configuration setting section.

   Note:

     * It is hard-coded in LaTeX that a single cell will obey the row
       colour even if there is a column colour set via "\columncolor"
       from a column specification (see "tabularcolumns").  Sphinx
       provides "\sphinxnorowcolor" which can be used like this:

          >{\columncolor{blue}\sphinxnorowcolor}

       in a table column specification.

     * Sphinx also provides "\sphinxcolorblend" which however requires
       the xcolor package.  Here is an example:

          >{\sphinxcolorblend{!95!red}}

       It means that in this column, the row colours will be slightly
       tinted by red; refer to xcolor documentation for more on the
       syntax of its "\blendcolors" command (a "\blendcolors" in place
       of "\sphinxcolorblend" would modify colours of the cell
       *contents*, not of the cell *background colour panel*...).  You
       can find an example of usage in the Deprecated APIs section of
       this document in PDF format.

       Hint:

         If you want to use a special colour for the *contents* of the
         cells of a given column use ">{\noindent\color{<color>}}",
         possibly in addition to the above.

     * Multi-row merged cells, whether single column or multi-column
       currently ignore any set column, row, or cell colour.

     * It is possible for a simple cell to set a custom colour via the
       raw directive and the "\cellcolor" LaTeX command used anywhere
       in the cell contents.  This currently is without effect in a
       merged cell, whatever its kind.

   Hint:

     In a document not using "'booktabs'" globally, it is possible to
     style an individual table via the "booktabs" class, but it will
     be necessary to add "r'\usepackage{booktabs}'" to the LaTeX
     preamble.On the other hand one can use "colorrows" class for
     individual tables with no extra package (as Sphinx since 5.3.0
     always loads colortbl).

latex_use_xindy

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

   * This option is ignored if "latex_engine" is "'platex'" (Japanese
     documents; **mendex** replaces **makeindex** then).

   * The default is "True" for "'xelatex'" or "'lualatex'" as
     **makeindex**, if any indexed term starts with a non-ascii
     character, creates ".ind" files containing invalid bytes for
     UTF-8 encoding. With "'lualatex'" this then breaks the PDF build.

   * The default is "False" for "'pdflatex'" but "True" is recommended
     for non-English documents as soon as some indexed terms use non-
     ascii characters from the language script.

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

   New in version 1.8.

latex_elements

   New in version 0.5.

   Its documentation has moved to LaTeX customization.

latex_docclass

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

   New in version 1.0.

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

latex_additional_files

   A list of file names, relative to the configuration directory, to
   copy to the build directory when building LaTeX output.  This is
   useful to copy files that Sphinx doesn't copy automatically, e.g.
   if they are referenced in custom LaTeX added in "latex_elements".
   Image files that are referenced in source files (e.g. via "..
   image::") are copied automatically.

   You have to make sure yourself that the filenames don't collide
   with those of any automatically copied files.

   Attention:

     Filenames with extension ".tex" will automatically be handed over
     to the PDF build process triggered by "sphinx-build -M"
     "latexpdf" or by **make latexpdf**.  If the file was added only
     to be "\input{}" from a modified preamble, you must add a further
     suffix such as ".txt" to the filename and adjust accordingly the
     "\input{}" command added to the LaTeX document preamble.

   New in version 0.6.

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

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).
      "latex_appendices" is available only for this theme.

   It defaults to "'manual'".

   New in version 3.0.

latex_theme_options

   A dictionary of options that influence the look and feel of the
   selected theme.

   New in version 3.1.

latex_theme_path

   A list of paths that contain custom LaTeX themes as subdirectories.
   Relative paths are taken as relative to the configuration
   directory.

   New in version 3.0.


Options for text output
=======================

These options influence text output.

text_newlines

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

   * "'unix'": use Unix-style line endings ("\n")

   * "'windows'": use Windows-style line endings ("\r\n")

   * "'native'": use the line ending style of the platform the
     documentation is built on

   Default: "'unix'".

   New in version 1.1.

text_sectionchars

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

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

   New in version 1.1.

text_add_secnumbers

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

   New in version 1.7.

text_secnumber_suffix

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

   New in version 1.7.


Options for manual page output
==============================

These options influence manual page output.

man_pages

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

   *startdocname*
      String that specifies the *document name* of the manual page's
      master document. All documents referenced by the *startdoc*
      document in TOC trees will be included in the manual file.  (If
      you want to use the default root document for your manual pages
      build, use your "root_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. Can be an empty string if you do not want to
      automatically generate the NAME section.

   *authors*
      A list of strings with authors, or a single string.  Can be an
      empty string or list if you do not want to automatically
      generate an AUTHORS section in the manual page.

   *section*
      The manual page section.  Used for the output file name as well
      as in the manual page header.

   New in version 1.0.

man_show_urls

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

   New in version 1.1.

man_make_section_directory

   If true, make a section directory on build man page.  Default is
   True.

   New in version 3.3.

   Changed in version 4.0: The default is changed to "False" from
   "True".

   Changed in version 4.0.2: The default is changed to "True" from
   "False" again.


Options for Texinfo output
==========================

These options influence Texinfo output.

texinfo_documents

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

   *startdocname*
      String that specifies the *document name* of the the Texinfo
      file's master document.  All documents referenced by the
      *startdoc* document in TOC trees will be included in the Texinfo
      file.  (If you want to use the default master document for your
      Texinfo build, provide your "root_doc" here.)

   *targetname*
      File name (no extension) of the Texinfo file in the output
      directory.

   *title*
      Texinfo document title.  Can be empty to use the title of the
      *startdoc* document.  Inserted as Texinfo markup, so special
      characters like "@" and "{}" will need to be escaped to be
      inserted literally.

   *author*
      Author for the Texinfo document.  Inserted as Texinfo markup.
      Use "@*" to separate multiple authors, as in: "'John@*Sarah'".

   *dir_entry*
      The name that will appear in the top-level "DIR" menu file.

   *description*
      Descriptive text to appear in the top-level "DIR" menu file.

   *category*
      Specifies the section which this entry will appear in the top-
      level "DIR" menu file.

   *toctree_only*
      Must be "True" or "False".  If true, the *startdoc* document
      itself is not included in the output, only the documents
      referenced by it via TOC trees.  With this option, you can put
      extra stuff in the master document that shows up in the HTML,
      but not the Texinfo output.

   New in version 1.1.

texinfo_appendices

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

   New in version 1.1.

texinfo_domain_indices

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

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

   New in version 1.1.

texinfo_show_urls

   Control how to display URL addresses.

   * "'footnote'" -- display URLs in footnotes (default)

   * "'no'" -- do not display URLs

   * "'inline'" -- display URLs inline in parentheses

   New in version 1.1.

texinfo_no_detailmenu

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

   New in version 1.2.

texinfo_elements

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

   * Keys that you may want to override include:

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

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

     "'preamble'"
        Texinfo markup inserted near the beginning of the file.

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

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

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

   New in version 1.1.

texinfo_cross_references

   If false, do not generate inline references in a document.  That
   makes an info file more readable with stand-alone reader ("info").
   Default is "True".

   New in version 4.4.


Options for QtHelp output
=========================

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

qthelp_basename

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

qthelp_namespace

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

qthelp_theme

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

qthelp_theme_options

   A dictionary of options that influence the look and feel of the
   selected theme.  These are theme-specific.  For the options
   understood by the builtin themes, see this section.


Options for the linkcheck builder
=================================

linkcheck_ignore

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

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

   New in version 1.1.

linkcheck_allowed_redirects

   A dictionary that maps a pattern of the source URI to a pattern of
   the canonical URI. The linkcheck builder treats the redirected link
   as "working" when:

   * the link in the document matches the source URI pattern, and

   * the redirect location matches the canonical URI pattern.

   Example:

      linkcheck_allowed_redirects = {
          # All HTTP redirections from the source URI to the canonical URI will be treated as "working".
          r'https://sphinx-doc\.org/.*': r'https://sphinx-doc\.org/en/master/.*'
      }

   If set, linkcheck builder will emit a warning when disallowed
   redirection found.  It's useful to detect unexpected redirects
   under "the warn-is-error mode".

   New in version 4.1.

linkcheck_request_headers

   A dictionary that maps baseurls to HTTP request headers.

   The key is a URL base string like ""https://www.sphinx-doc.org/"".
   To specify headers for other hosts, ""*"" can be used.  It matches
   all hosts only when the URL does not match other settings.

   The value is a dictionary that maps header name to its value.

   Example:

      linkcheck_request_headers = {
          "https://www.sphinx-doc.org/": {
              "Accept": "text/html",
              "Accept-Encoding": "utf-8",
          },
          "*": {
              "Accept": "text/html,application/xhtml+xml",
          }
      }

   New in version 3.1.

linkcheck_retries

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

   New in version 1.4.

linkcheck_timeout

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

   New in version 1.1.

linkcheck_workers

   The number of worker threads to use when checking links.  Default
   is 5 threads.

   New in version 1.1.

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

   New in version 1.2.

linkcheck_anchors_ignore

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

   Tip:

     Use "linkcheck_anchors_ignore_for_url" to check a URL, but skip
     verifying that the anchors exist.

   Note:

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

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

   New in version 1.5.

linkcheck_anchors_ignore_for_url

   A list or tuple of regular expressions matching URLs for which
   Sphinx should not check the validity of anchors. This allows
   skipping anchor checks on a per-page basis while still checking the
   validity of the page itself. Default is an empty tuple "()".

   New in version 7.1.

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* for details).

   The "linkcheck" builder will use the first matching "auth_info"
   value it can find in the "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(...)),
      ]

   New in version 2.3.

linkcheck_rate_limit_timeout

   The "linkcheck" builder may issue a large number of requests to the
   same site over a short period of time. This setting controls the
   builder behavior when servers indicate that requests are rate-
   limited.

   If a server indicates when to retry (using the Retry-After header),
   "linkcheck" always follows the server indication.

   Otherwise, "linkcheck" waits for a minute before to retry and keeps
   doubling the wait time between attempts until it succeeds or
   exceeds the "linkcheck_rate_limit_timeout". By default, the timeout
   is 5 minutes.

   New in version 3.4.

linkcheck_exclude_documents

   A list of regular expressions that match documents in which Sphinx
   should not check the validity of links. This can be used for
   permitting link decay in legacy or historical sections of the
   documentation.

   Example:

      # ignore all links in documents located in a subfolder named 'legacy'
      linkcheck_exclude_documents = [r'.*/legacy/.*']

   New in version 4.4.


Options for the XML builder
===========================

xml_pretty

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

   New in version 1.2.

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


Options for the C domain
========================

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.

   New in version 3.0.

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.

   New in version 3.0.

c_extra_keywords

   A list of identifiers to be recognized as keywords by the C parser.
   It defaults to "['alignas', 'alignof', 'bool', 'complex',
   'imaginary', 'noreturn', 'static_assert', 'thread_local']".

   New in version 4.0.3.

c_maximum_signature_line_length

   If a signature's length in characters exceeds the number set, each
   parameter will be displayed on an individual logical line. This is
   a domain-specific setting, overriding
   "maximum_signature_line_length".

   New in version 7.1.


Options for the C++ domain
==========================

cpp_index_common_prefix

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

   New in version 1.5.

cpp_id_attributes

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

   New in version 1.5.

cpp_paren_attributes

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

   New in version 1.5.

cpp_maximum_signature_line_length

   If a signature's length in characters exceeds the number set, each
   parameter will be displayed on an individual logical line. This is
   a domain-specific setting, overriding
   "maximum_signature_line_length".

   New in version 7.1.


Options for the Python domain
=============================

python_display_short_literal_types

   This value controls how "Literal" types are displayed. The setting
   is a boolean, default "False".


   Examples
   --------

   The examples below use the following "py:function" directive:

      .. py:function:: serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None

   When "False", "Literal" types display as per standard Python
   syntax, i.e.:

         serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None

   When "True", "Literal" types display with a short, **PEP
   604**-inspired syntax, i.e.:

         serve_food(item: "egg" | "spam" | "lobster thermidor") -> None

   New in version 6.2.

python_use_unqualified_type_names

   If true, suppress the module name of the python reference if it can
   be resolved.  The default is "False".

   New in version 4.0.

   Note:

     This configuration is still in experimental

python_maximum_signature_line_length

   If a signature's length in characters exceeds the number set, each
   argument or type parameter will be displayed on an individual
   logical line. This is a domain-specific setting, overriding
   "maximum_signature_line_length".

   For the Python domain, the signature length depends on whether the
   type parameters or the list of arguments are being formatted. For
   the former, the signature length ignores the length of the
   arguments list; for the latter, the signature length ignores the
   length of the type parameters list.

   For instance, with *python_maximum_signature_line_length = 20*,
   only the list of type parameters will be wrapped while the
   arguments list will be rendered on a single line

      .. py:function:: add[T: VERY_LONG_SUPER_TYPE, U: VERY_LONG_SUPER_TYPE](a: T, b: U)

   New in version 7.1.


Options for the Javascript domain
=================================

javascript_maximum_signature_line_length

   If a signature's length in characters exceeds the number set, each
   parameter will be displayed on an individual logical line. This is
   a domain-specific setting, overriding
   "maximum_signature_line_length".

   New in version 7.1.


Example of configuration file
=============================

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

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

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

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

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

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

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

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

   # The master toctree document.
   root_doc = 'index'

   # General information about the project.
   project = 'test'
   copyright = '2016, test'
   author = 'test'

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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

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

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

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

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

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

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

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

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

   # Additional templates that should be rendered to pages, maps page names to
   # template names.
   #
   # html_additional_pages = {}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   # If true, show URL addresses after external links.
   #
   # latex_show_urls = False

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

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


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

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

   # If true, show URL addresses after external links.
   #
   # man_show_urls = False


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

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

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

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

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

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

   # If false, do not generate in manual @ref nodes.
   #
   # texinfo_cross_references = False

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

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

   numfig = True
   #language = 'ja'

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


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