enumerate(sequence[, start=0])

Return an iterator that yields tuples of an index and an item of the sequence. (And so on.)

• Other extensions:
• Static files
• Selecting a theme
• /usage/advanced/setuptools
• Templating
• Using extensions
• Writing extensions

• Overview
• Linux
• macOS
• Windows
• Installation from PyPI
• Docker
• Installation from source

• sphinxdoc/sphinx
• sphinxdoc/sphinx-latexpdf

• one asterisk: *text* for emphasis (italics),
• two asterisks: **text** for strong emphasis (boldface), and
• backquotes: ``text`` for code samples.

• it may not be nested,
• content may not start or end with whitespace: * text* is wrong,
• it must be separated from surrounding text by non-word characters. Use a backslash escaped space to work around that: thisis\ *one*\ word.

• field lists (ref, with caveats noted in Field Lists)
• option lists (ref)
• quoted literal blocks (ref)
• doctest blocks (ref)

• If it occurs as a paragraph of its own, that paragraph is completely left out of the document.
• If it is preceded by whitespace, the marker is removed.
• If it is preceded by non-whitespace, the marker is replaced by a single colon.

• # with overline, for parts
• * with overline, for chapters
• =, for sections
• -, for subsections
• ^, for subsubsections
• ", for paragraphs

• emphasis – equivalent of *emphasis*
• strong – equivalent of **strong**
• literal – equivalent of ``literal``
• subscript – subscript text
• superscript – superscript text
• title-reference – for titles of books, periodicals, and other materials

• Admonitions: attention, caution, danger, error, hint, important, note, tip, warning and the generic admonition. (Most themes style only “note” and “warning” specially.)
• Images:

•

Additional body elements:

•

Special tables:

•

Special directives:

•

HTML specifics:

•

Influencing markup:

Since these are only per-file, better use Sphinx’s facilities for setting the default_role.

• pleasefindthiskey, pleasefindthiskeytoo to English builds;
• bittediesenkeyfinden to German builds;
• backup to builds in all languages.

• Separation of inline markup: As said above, inline markup spans must be separated from the surrounding text by non-word characters, you have to use a backslash-escaped space to get around that. See the reference for the details.
• No nested inline markup: Something like *see :func:`foo`* is not possible.

• You may supply an explicit title and reference target, like in reST direct hyperlinks: :role:`title <target>` will refer to target, but the link text will be title.
• If you prefix the content with !, no reference/hyperlink will be created.
• If you prefix the content with ~, the link text will only be the last component of the target. For example, :py:meth:`~Queue.Queue.get` will refer to Queue.Queue.get but only display get as the link text. This does not work with all cross-reference roles, but is domain specific.

  In HTML output, the link’s title attribute (that is e.g. shown as a tool-tip on mouse-hover) will always be the full target name.

:any:

New in version 1.3.

This convenience role tries to do its best to find a valid target for its reference text.

If none or multiple targets are found, a warning will be emitted. In the case of multiple targets, you can change “any” to a specific role.

This role is a good candidate for setting default_role. If you do, you can write cross-references without a lot of markup overhead. For example, in this Python function documentation

.. function:: install()


   This function installs a `handler` for every signal known by the


   `signal` module.  See the section `about-signals` for more information.

there could be references to a glossary term (usually :term:`handler`), a Python module (usually :py:mod:`signal` or :mod:`signal`) and a section (usually :ref:`about-signals`).

The any role also works together with the intersphinx extension: when no local cross-reference is found, all object types of intersphinx inventories are also searched.

• Python
• C
• C++
• JavaScript
• ReST

:ref:

To support cross-referencing to arbitrary locations in any document, the standard reST labels are used. For this to work label names must be unique throughout the entire documentation. There are two ways in which you can refer to labels:

.. _my-reference-label:
Section to cross-reference
--------------------------
This is the text of the section.
It refers to the section itself, see :ref:`my-reference-label`.

.. _my-figure:
.. figure:: whatever


   Figure caption

NOTE:

Using ref is advised over standard reStructuredText links to sections (like `Section title`_) because it works across files, when section headings are changed, will raise warnings if incorrect, and works for all builders that support cross-references.

:doc:

Link to the specified document; the document name can be specified in absolute or relative fashion. For example, if the reference :doc:`parrot` occurs in the document sketches/index, then the link refers to sketches/parrot. If the reference is :doc:`/people` or :doc:`../people`, the link refers to people.

If no explicit link text is given (like usual: :doc:`Monty Python members </people>`), the link caption will be the title of the given document.

:download:

This role lets you link to files within your source tree that are not reST documents that can be viewed, but files that can be downloaded.

When you use this role, the referenced file is automatically marked for inclusion in the output when building (obviously, for HTML output only). All downloadable files are put into a _downloads/<unique hash>/ subdirectory of the output directory; duplicate filenames are handled.

An example:

See :download:`this example script <../example.py>`.

The given filename is usually relative to the directory the current source file is contained in, but if it absolute (starting with /), it is taken as relative to the top source directory.

The example.py file will be copied to the output directory, and a suitable link generated to it.

Not to show unavailable download links, you should wrap whole paragraphs that have this role:

.. only:: builder_html


   See :download:`this example script <../example.py>`.

:numref:

Link to the specified figures, tables, code-blocks and sections; the standard reST labels are used. When you use this role, it will insert a reference to the figure with link text by its figure number like “Fig. 1.1”.

If an explicit link text is given (as usual: :numref:`Image of Sphinx (Fig. %s) <my-figure>`), the link caption will serve as title of the reference. As placeholders, %s and {number} get replaced by the figure number and {name} by the figure caption. If no explicit link text is given, the numfig_format setting is used as fall-back default.

If numfig is False, figures are not numbered, so this role inserts not a reference but the label or the link text.

:envvar:

An environment variable. Index entries are generated. Also generates a link to the matching envvar directive, if it exists.

:token:

The name of a grammar token (used to create links between productionlist directives).

:keyword:

The name of a keyword in Python. This creates a link to a reference label with that name, if it exists.

:option:

A command-line option to an executable program. This generates a link to a option directive, if it exists.

:term:

Reference to a term in a glossary. A glossary is created using the glossary directive containing a definition list with terms and definitions. It does not have to be in the same file as the term markup, for example the Python docs have one global glossary in the glossary.rst file.

If you use a term that’s not explained in a glossary, you’ll get a warning during build.

:math:

Role for inline math. Use like this:

Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.

:eq:

Same as math:numref.

:abbr:

An abbreviation. If the role content contains a parenthesized explanation, it will be treated specially: it will be shown in a tool-tip in HTML, and output only once in LaTeX.

Example: :abbr:`LIFO (last-in, first-out)`.

New in version 0.6.

:command:

The name of an OS-level command, such as rm.

:dfn:

Mark the defining instance of a term in the text. (No index entries are generated.)

:file:

The name of a file or directory. Within the contents, you can use curly braces to indicate a “variable” part, for example:

... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...

In the built documentation, the x will be displayed differently to indicate that it is to be replaced by the Python minor version.

:guilabel:

Labels presented as part of an interactive user interface should be marked using guilabel. This includes labels from text-based interfaces such as those created using curses or other text-based libraries. Any label used in the interface should be marked with this role, including button labels, window titles, field names, menu and menu selection names, and even values in selection lists.

Changed in version 1.0: An accelerator key for the GUI label can be included using an ampersand; this will be stripped and displayed underlined in the output (example: :guilabel:`&Cancel`). To include a literal ampersand, double it.

:kbd:

Mark a sequence of keystrokes. What form the key sequence takes may depend on platform- or application-specific conventions. When there are no relevant conventions, the names of modifier keys should be spelled out, to improve accessibility for new users and non-native speakers. For example, an xemacs key sequence may be marked like :kbd:`C-x C-f`, but without reference to a specific application or platform, the same sequence should be marked as :kbd:`Control-x Control-f`.

:mailheader:

The name of an RFC 822-style mail header. This markup does not imply that the header is being used in an email message, but can be used to refer to any header of the same “style.” This is also used for headers defined by the various MIME specifications. The header name should be entered in the same way it would normally be found in practice, with the camel-casing conventions being preferred where there is more than one common usage. For example: :mailheader:`Content-Type`.

:makevar:

The name of a make variable.

:manpage:

A reference to a Unix manual page including the section, e.g. :manpage:`ls(1)`. Creates a hyperlink to an external site rendering the manpage if manpages_url is defined.

:menuselection:

Menu selections should be marked using the menuselection role. This is used to mark a complete sequence of menu selections, including selecting submenus and choosing a specific operation, or any subsequence of such a sequence. The names of individual selections should be separated by -->.

For example, to mark the selection “Start > Programs”, use this markup:

:menuselection:`Start --> Programs`

When including a selection that includes some trailing indicator, such as the ellipsis some operating systems use to indicate that the command opens a dialog, the indicator should be omitted from the selection name.

menuselection also supports ampersand accelerators just like guilabel.

:mimetype:

The name of a MIME type, or a component of a MIME type (the major or minor portion, taken alone).

:newsgroup:

The name of a Usenet newsgroup.

:program:

The name of an executable program. This may differ from the file name for the executable for some platforms. In particular, the .exe (or other) extension should be omitted for Windows programs.

:regexp:

A regular expression. Quotes should not be included.

:samp:

A piece of literal text, such as code. Within the contents, you can use curly braces to indicate a “variable” part, as in file. For example, in :samp:`print 1+{variable}`, the part variable would be emphasized.

If you don’t need the “variable part” indication, use the standard ``code`` instead.

Changed in version 1.8: Allowed to escape curly braces with backslash

:pep:

A reference to a Python Enhancement Proposal. This generates appropriate index entries. The text “PEP number” is generated; in the HTML output, this text is a hyperlink to an online copy of the specified PEP. You can link to a specific section by saying :pep:`number#anchor`.

:rfc:

A reference to an Internet Request for Comments. This generates appropriate index entries. The text “RFC number” is generated; in the HTML output, this text is a hyperlink to an online copy of the specified RFC. You can link to a specific section by saying :rfc:`number#anchor`.

|release|

Replaced by the project release the documentation refers to. This is meant to be the full version string including alpha/beta/release candidate tags, e.g. 2.5.2b3. Set by release.

|version|

Replaced by the project version the documentation refers to. This is meant to consist only of the major and minor version parts, e.g. 2.5, even for version 2.5.1. Set by version.

|today|

Replaced by either today’s date (the date on which the document is read), or the date set in the build configuration file. Normally has the format April 14, 2007. Set by today_fmt and today.

.. toctree::

This directive inserts a “TOC tree” at the current location, using the individual TOCs (including “sub-TOC trees”) of the documents given in the directive body. Relative document names (not beginning with a slash) are relative to the document the directive occurs in, absolute names are relative to the source directory. A numeric maxdepth option may be given to indicate the depth of the tree; by default, all levels are included. [1]

The representation of “TOC tree” is changed in each output format. The builders that output multiple files (ex. HTML) treat it as a collection of hyperlinks. On the other hand, the builders that output a single file (ex. LaTeX, man page, etc.) replace it with the content of the documents on the TOC tree.

Consider this example (taken from the Python docs’ library reference index):

.. toctree::


   :maxdepth: 2


   intro


   strings


   datatypes


   numeric


   (many more documents listed here)

This accomplishes two things:

Entries

Document titles in the toctree will be automatically read from the title of the referenced document. If that isn’t what you want, you can specify an explicit title and target using a similar syntax to reST hyperlinks (and Sphinx’s cross-referencing syntax). This looks like:

.. toctree::


   intro


   All about strings <strings>


   datatypes

The second line above will link to the strings document, but will use the title “All about strings” instead of the title of the strings document.

You can also add external links, by giving an HTTP URL instead of a document name.

Section numbering

If you want to have section numbers even in HTML output, give the toplevel toctree a numbered option. For example:

.. toctree::


   :numbered:


   foo


   bar

Numbering then starts at the heading of foo. Sub-toctrees are automatically numbered (don’t give the numbered flag to those).

Numbering up to a specific depth is also possible, by giving the depth as a numeric argument to numbered.

Additional options

You can use the caption option to provide a toctree caption and you can use the name option to provide an implicit target name that can be referenced by using ref:

.. toctree::


   :caption: Table of Contents


   :name: mastertoc


   foo

If you want only the titles of documents in the tree to show up, not other headings of the same level, you can use the titlesonly option:

.. toctree::


   :titlesonly:


   foo


   bar

You can use “globbing” in toctree directives, by giving the glob flag option. All entries are then matched against the list of available documents, and matches are inserted into the list alphabetically. Example:

.. toctree::


   :glob:


   intro*


   recipe/*


   *

This includes first all documents whose names start with intro, then all documents in the recipe folder, then all remaining documents (except the one containing the directive, of course.) [2]

The special entry name self stands for the document containing the toctree directive. This is useful if you want to generate a “sitemap” from the toctree.

You can use the reversed flag option to reverse the order of the entries in the list. This can be useful when using the glob flag option to reverse the ordering of the files. Example:

.. toctree::


   :glob:


   :reversed:


   recipe/*

You can also give a “hidden” option to the directive, like this:

.. toctree::


   :hidden:


   doc_1


   doc_2

This will still notify Sphinx of the document hierarchy, but not insert links into the document at the location of the directive – this makes sense if you intend to insert these links yourself, in a different style, or in the HTML sidebar.

In cases where you want to have only one top-level toctree and hide all other lower level toctrees you can add the “includehidden” option to the top-level toctree entry:

.. toctree::


   :includehidden:


   doc_1


   doc_2

All other toctree entries can then be eliminated by the “hidden” option.

In the end, all documents in the source directory (or subdirectories) must occur in some toctree directive; Sphinx will emit a warning if it finds a file that is not included, because that means that this file will not be reachable through standard navigation.

Use exclude_patterns to explicitly exclude documents or directories from building completely. Use the “orphan” metadata to let a document be built, but notify Sphinx that it is not reachable via a toctree.

The “master document” (selected by master_doc) is the “root” of the TOC tree hierarchy. It can be used as the documentation’s main page, or as a “full table of contents” if you don’t give a maxdepth option.

Changed in version 0.3: Added “globbing” option.

Changed in version 0.6: Added “numbered” and “hidden” options as well as external links and support for “self” references.

Changed in version 1.0: Added “titlesonly” option.

Changed in version 1.1: Added numeric argument to “numbered”.

Changed in version 1.2: Added “includehidden” option.

Changed in version 1.3: Added “caption” and “name” option.

• genindex, modindex, search

  These are used for the general index, the Python module index, and the search page, respectively.

  The general index is populated with entries from modules, all index-generating object descriptions, and from index directives.

  The Python module index contains one entry per py:module directive.

  The search page contains a form that uses the generated JSON search index and JavaScript to full-text search the generated documents for search words; it should work on every major browser that supports modern JavaScript.

• every name beginning with _

  Though few such names are currently used by Sphinx, you should not create documents or document-containing directories with such names. (Using _ as a prefix for a custom template directory is fine.)

.. note::

An especially important bit of information about an API that a user should be aware of when using whatever bit of API the note pertains to. The content of the directive should be written in complete sentences and include all appropriate punctuation.

Example:

.. note::


   This function is not suitable for sending spam e-mails.

.. warning::

An important bit of information about an API that a user should be very aware of when using whatever bit of API the warning pertains to. The content of the directive should be written in complete sentences and include all appropriate punctuation. This differs from note in that it is recommended over note for information regarding security.

.. versionadded:: version

This directive documents the version of the project which added the described feature to the library or C API. When this applies to an entire module, it should be placed at the top of the module section before any prose.

The first argument must be given and is the version in question; you can add a second argument consisting of a brief explanation of the change.

Example:

.. versionadded:: 2.5


   The *spam* parameter.

Note that there must be no blank line between the directive head and the explanation; this is to make these blocks visually continuous in the markup.

.. versionchanged:: version

Similar to versionadded, but describes when and what changed in the named feature in some way (new parameters, changed side effects, etc.).

.. deprecated:: version

Similar to versionchanged, but describes when the feature was deprecated. An explanation can also be given, for example to inform the reader what should be used instead. Example:

.. deprecated:: 3.1


   Use :func:`spam` instead.

.. seealso::

Many sections include a list of references to module documentation or external documents. These lists are created using the seealso directive.

The seealso directive is typically placed in a section just before any subsections. For the HTML output, it is shown boxed off from the main flow of the text.

The content of the seealso directive should be a reST definition list. Example:

.. seealso::


   Module :py:mod:`zipfile`


      Documentation of the :py:mod:`zipfile` standard module.


   `GNU tar manual, Basic Tar Format <http://link>`_


      Documentation for tar archive files, including GNU tar extensions.

There’s also a “short form” allowed that looks like this:

.. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`

New in version 0.5: The short form.

.. rubric:: title

This directive creates a paragraph heading that is not used to create a table of contents node.

NOTE:

.. centered::

This directive creates a centered boldfaced line of text. Use it as follows:

.. centered:: LICENSE AGREEMENT

Deprecated since version 1.1: This presentation-only directive is a legacy from older versions. Use a rst-class directive instead and add an appropriate style.

.. hlist::

This directive must contain a bullet list. It will transform it into a more compact list by either distributing more than one item horizontally, or reducing spacing between items, depending on the builder.

For builders that support the horizontal distribution, there is a columns option that specifies the number of columns; it defaults to 2. Example:

.. hlist::


   :columns: 3


   * A list of


   * short items


   * that should be


   * displayed


   * horizontally

New in version 0.6.

• none (no highlighting)
• default (similar to python3 but with a fallback to none without warning highlighting fails; the default when highlight_language isn’t set)
• guess (let Pygments guess the lexer based on contents, only works with certain well-recognizable languages)
• python
• rest
• c
• … and any other lexer alias that Pygments supports

.. highlight:: language

Example:

.. highlight:: c

This language is used until the next highlight directive is encountered. As discussed previously, language can be any lexer alias supported by Pygments.

options

.. highlight:: python


   :linenothreshold: 5

.. code-block:: [language]

Example:

.. code-block:: ruby


   Some Ruby code.

The directive’s alias name sourcecode works as well. This directive takes a language name as an argument. It can be any lexer alias supported by Pygments. If it is not given, the setting of highlight directive will be used. If not set, highlight_language will be used.

Changed in version 2.0: The language argument becomes optional.

options

.. code-block:: ruby


   :linenos:


   Some more Ruby code.

.. code-block:: ruby


   :lineno-start: 10


   Some more Ruby code, with line numbering starting at 10.

.. code-block:: python


   :emphasize-lines: 3,5


   def some_function():


       interesting = False


       print 'This line is highlighted.'


       print 'This one is not...'


       print '...but this one is.'

.. code-block:: python


   :caption: this.py


   :name: this-py


   print 'Explicit is better than implicit.'

.. code-block:: ruby


   :dedent: 4


       some ruby code

.. literalinclude:: filename

Longer displays of verbatim text may be included by storing the example text in an external file containing only plain text. The file may be included using the literalinclude directive. [3] For example, to include the Python source file example.py, use:

.. literalinclude:: example.py

The file name is usually relative to the current file’s path. However, if it is absolute (starting with /), it is relative to the top source directory.

Additional options

Like code-block, the directive supports the linenos flag option to switch on line numbers, the lineno-start option to select the first line number, the emphasize-lines option to emphasize particular lines, the name option to provide an implicit target name, the dedent option to strip indentation characters for the code block, and a language option to select a language different from the current file’s standard language. In addition, it supports the caption option; however, this can be provided with no argument to use the filename as the caption. Example with options:

.. literalinclude:: example.rb


   :language: ruby


   :emphasize-lines: 12,15-18


   :linenos:

Tabs in the input are expanded if you give a tab-width option with the desired tab width.

Include files are assumed to be encoded in the source_encoding. If the file has a different encoding, you can specify it with the encoding option:

.. literalinclude:: example.py


   :encoding: latin-1

The directive also supports including only parts of the file. If it is a Python module, you can select a class, function or method to include using the pyobject option:

.. literalinclude:: example.py


   :pyobject: Timer.start

This would only include the code lines belonging to the start() method in the Timer class within the file.

Alternately, you can specify exactly which lines to include by giving a lines option:

.. literalinclude:: example.py


   :lines: 1,3,5-10,20-

This includes the lines 1, 3, 5 to 10 and lines 20 to the last line.

Another way to control which part of the file is included is to use the start-after and end-before options (or only one of them). If start-after is given as a string option, only lines that follow the first line containing that string are included. If end-before is given as a string option, only lines that precede the first lines containing that string are included. The start-at and end-at options behave in a similar way, but the lines containing the matched string are included.

start-after/start-at and end-before/end-at can have same string. start-after/start-at filter lines before the line that contains option string (start-at will keep the line). Then end-before/end-at filter lines after the line that contains option string (end-at will keep the line and end-before skip the first line).

NOTE:

[first-section]
var_in_first=true
[second-section]
var_in_second=true
[third-section]
var_in_third=true

if __name__ == "__main__":


    # [initialize]


    app.start(":8000")


    # [initialize]

When lines have been selected in any of the ways described above, the line numbers in emphasize-lines refer to those selected lines, counted consecutively starting at 1.

When specifying particular parts of a file to display, it can be useful to display the original line numbers. This can be done using the lineno-match option, which is however allowed only when the selection consists of contiguous lines.

You can prepend and/or append a line to the included code, using the prepend and append option, respectively. This is useful e.g. for highlighting PHP code that doesn’t include the <?php/?> markers.

If you want to show the diff of the code, you can specify the old file by giving a diff option:

.. literalinclude:: example.py


   :diff: example.py.orig

This shows the diff between example.py and example.py.orig with unified diff format.

A force option can ignore minor errors on highlighting.

Changed in version 0.4.3: Added the encoding option.

Changed in version 0.6: Added the pyobject, lines, start-after and end-before options, as well as support for absolute filenames.

Changed in version 1.0: Added the prepend, append, and tab-width options.

Changed in version 1.3: Added the diff, lineno-match, caption, name, and dedent options.

Changed in version 1.5: Added the start-at, and end-at options.

Changed in version 1.6: With both start-after and lines in use, the first line as per start-after is considered to be with line number 1 for lines.

Changed in version 2.1: Added the force option.

.. glossary::

This directive must contain a reST definition-list-like markup with terms and definitions. The definitions will then be referenceable with the term role. Example:

.. glossary::


   environment


      A structure where information about all documents under the root is


      saved, and used for cross-referencing.  The environment is pickled


      after the parsing stage, so that successive runs only need to read


      and parse new and changed documents.


   source directory


      The directory which, including its subdirectories, contains all


      source files for one Sphinx project.

In contrast to regular definition lists, multiple terms per entry are allowed, and inline markup is allowed in terms. You can link to all of the terms. For example:

.. glossary::


   term 1


   term 2


      Definition of both terms.

(When the glossary is sorted, the first term determines the sort order.)

If you want to specify “grouping key” for general index entries, you can put a “key” as “term : key”. For example:

.. glossary::


   term 1 : A


   term 2 : B


      Definition of both terms.

Note that “key” is used for grouping key as is. The “key” isn’t normalized; key “A” and “a” become different groups. The whole characters in “key” is used instead of a first character; it is used for “Combining Character Sequence” and “Surrogate Pairs” grouping key.

In i18n situation, you can specify “localized term : key” even if original text only have “term” part. In this case, translated “localized term” will be categorized in “key” group.

New in version 0.6: You can now give the glossary directive a :sorted: flag that will automatically sort the entries alphabetically.

Changed in version 1.1: Now supports multiple terms and inline markup in terms.

Changed in version 1.4: Index key for glossary term should be considered experimental.

.. sectionauthor:: name <email>

Identifies the author of the current section. The argument should include the author’s name such that it can be used for presentation and email address. The domain name portion of the address should be lower case. Example:

.. sectionauthor:: Guido van Rossum <guido@python.org>

By default, this markup isn’t reflected in the output in any way (it helps keep track of contributions), but you can set the configuration value show_authors to True to make them produce a paragraph in the output.

.. codeauthor:: name <email>

The codeauthor directive, which can appear multiple times, names the authors of the described code, just like sectionauthor names the author(s) of a piece of documentation. It too only produces output if the show_authors configuration value is True.

.. index:: <entries>

This directive contains one or more index entries. Each entry consists of a type and a value, separated by a colon.

For example:

.. index::


   single: execution; context


   module: __main__


   module: sys


   triple: module; search; path
The execution context
---------------------
...

This directive contains five entries, which will be converted to entries in the generated index which link to the exact location of the index statement (or, in case of offline media, the corresponding page number).

Since index directives generate cross-reference targets at their location in the source, it makes sense to put them before the thing they refer to – e.g. a heading, as in the example above.

The possible entry types are:

You can mark up “main” index entries by prefixing them with an exclamation mark. The references to “main” entries are emphasized in the generated index. For example, if two pages contain

.. index:: Python

and one page contains

.. index:: ! Python

then the backlink to the latter page is emphasized among the three backlinks.

For index directives containing only “single” entries, there is a shorthand notation:

.. index:: BNF, grammar, syntax, notation

This creates four index entries.

Changed in version 1.1: Added see and seealso types, as well as marking main entries.

options

.. index:: Python


   :name: py-index

New in version 3.0.

:index:

While the index directive is a block-level markup and links to the beginning of the next paragraph, there is also a corresponding role that sets the link target directly where it is used.

The content of the role can be a simple phrase, which is then kept in the text and used as an index entry. It can also be a combination of text and index entry, styled like with explicit targets of cross-references. In that case, the “target” part can be a full entry as described for the directive above. For example:

This is a normal reST :index:`paragraph` that contains several
:index:`index entries <pair: index; entry>`.

New in version 1.1.

.. only:: <expression>

Include the content of the directive only if the expression is true. The expression should consist of tags, like this:

.. only:: html and draft

Undefined tags are false, defined tags (via the -t command-line option or within conf.py, see here) are true. Boolean expressions, also using parentheses (like html and (latex or draft)) are supported.

The format and the name of the current builder (html, latex or text) are always set as a tag [4]. To make the distinction between format and name explicit, they are also added with the prefix format_ and builder_, e.g. the epub builder defines the tags html, epub, format_html and builder_epub.

These standard tags are set after the configuration file is read, so they are not available there.

All tags must follow the standard Python identifier syntax as set out in the Identifiers and keywords documentation. That is, a tag expression may only consist of tags that conform to the syntax of Python variables. In ASCII, this consists of the uppercase and lowercase letters A through Z, the underscore _ and, except for the first character, the digits 0 through 9.

New in version 0.6.

Changed in version 1.2: Added the name of the builder and the prefixes.

WARNING:

• grid table syntax (ref),
• simple table syntax (ref),
• csv-table syntax,
• or list-table syntax.

.. tabularcolumns:: column spec

This directive gives a “column spec” for the next table occurring in the source file. The spec is the second argument to the LaTeX tabulary package’s environment (which Sphinx uses to translate tables). It can have values like

|l|l|l|

which means three left-adjusted, nonbreaking columns. For columns with longer text that should automatically be broken, use either the standard p{width} construct, or tabulary’s automatic specifiers:

The automatic widths of the LRCJ columns are attributed by tabulary in proportion to the observed shares in a first pass where the table cells are rendered at their natural “horizontal” widths.

By default, Sphinx uses a table layout with J for every column.

New in version 0.3.

Changed in version 1.6: Merged cells may now contain multiple paragraphs and are much better handled, thanks to custom Sphinx LaTeX macros. This novel situation motivated the switch to J specifier and not L by default.

HINT:

WARNING:

Since Sphinx 1.5, the \X{a}{b} specifier is used (there is a backslash in the specifier letter). It is like p{width} with the width set to a fraction a/b of the current line width. You can use it in the tabularcolumns (it is not a problem if some LaTeX macro is also called \X.)

It is not needed for b to be the total number of columns, nor for the sum of the fractions of the \X specifiers to add up to one. For example |\X{2}{5}|\X{1}{5}|\X{1}{5}| is legitimate and the table will occupy 80% of the line width, the first of its three columns having the same width as the sum of the next two.

This is used by the :widths: option of the table directive.

Since Sphinx 1.6, there is also the \Y{f} specifier which admits a decimal argument, such has \Y{0.15}: this would have the same effect as \X{3}{20}.

Changed in version 1.6: Merged cells from complex grid tables (either multi-row, multi-column, or both) now allow blockquotes, lists, literal blocks, … as do regular cells.

Sphinx’s merged cells interact well with p{width}, \X{a}{b}, \Y{f} and tabulary’s columns.

NOTE:

.. math::

Directive for displayed math (math that takes the whole line for itself).

The directive supports multiple equations, which should be separated by a blank line:

.. math::


   (a + b)^2 = a^2 + 2ab + b^2


   (a - b)^2 = a^2 - 2ab + b^2

In addition, each single equation is set within a split environment, which means that you can have multiple aligned lines in an equation, aligned at & and separated by \\:

.. math::


   (a + b)^2  &=  (a + b)(a + b) \\


              &=  a^2 + 2ab + b^2

For more details, look into the documentation of the AmSMath LaTeX package.

When the math is only one line of text, it can also be given as a directive argument:

.. math:: (a + b)^2 = a^2 + 2ab + b^2

Normally, equations are not numbered. If you want your equation to get a number, use the label option. When given, it selects an internal label for the equation, by which it can be cross-referenced, and causes an equation number to be issued. See eq for an example. The numbering style depends on the output format.

There is also an option nowrap that prevents any wrapping of the given math in a math environment. When you give this option, you must make sure yourself that the math is properly set up. For example:

.. math::


   :nowrap:


   \begin{eqnarray}


      y    & = & ax^2 + bx + c \\


      f(x) & = & x^2 + 2xy + y^2


   \end{eqnarray}

.. productionlist:: [productionGroup]

This directive is used to enclose a group of productions. Each production is given on a single line and consists of a name, separated by a colon from the following definition. If the definition spans multiple lines, each continuation line must begin with a colon placed at the same column as in the first line.

The productionGroup argument to productionlist serves to distinguish different sets of production lists that belong to different grammars. Multiple production lists with the same productionGroup thus define rules in the same scope.

Blank lines are not allowed within productionlist directive arguments.

The definition can contain token names which are marked as interpreted text (e.g. “sum ::= `integer` "+" `integer`”) – this generates cross-references to the productions of these tokens. Outside of the production list, you can reference to token productions using token. However, if you have given a productionGroup argument you must prefix the token name in the cross-reference with the group name and a colon, e.g., “myGroup:sum” instead of just “sum”. If the group should not be shown in the title of the link either an explicit title can be given (e.g., “myTitle <myGroup:sum>”), or the target can be prefixed with a tilde (e.g., “~myGroup:sum”).

Note that no further reST parsing is done in the production, so that you don’t have to escape * or | characters.

tocdepth

The maximum depth for a table of contents of this file.

:tocdepth: 2

NOTE:

New in version 0.4.

nocomments

If set, the web application won’t display a comment form for a page generated from this source file.

:nocomments:

orphan

If set, warnings about this file not being included in any toctree will be suppressed.

:orphan:

New in version 1.0.

nosearch

If set, full text search for this file is disabled.

:nosearch:

NOTE:

New in version 3.0.

.. default-domain:: name

Select a new default domain. While the primary_domain selects a global default, this only has an effect within the same file.

• You may supply an explicit title and reference target: :role:`title <target>` will refer to target, but the link text will be title.
• If you prefix the content with !, no reference/hyperlink will be created.
• If you prefix the content with ~, the link text will only be the last component of the target. For example, :py:meth:`~Queue.Queue.get` will refer to Queue.Queue.get but only display get as the link text.

.. py:module:: name

This directive marks the beginning of the description of a module (or package submodule, in which case the name should be fully qualified, including the package name). It does not create content (like e.g. py:class does).

This directive will also cause an entry in the global module index.

options

.. py:currentmodule:: name

This directive tells Sphinx that the classes, functions etc. documented from here are in the given module (like py:module), but it will not create index entries, an entry in the Global Module Index, or a link target for py:mod. This is helpful in situations where documentation for things in a module is spread over multiple files or sections – one location has the py:module directive, the others only py:currentmodule.

.. py:function:: name(parameters)

Describes a module-level function. The signature should include the parameters as given in the Python function definition, see Python Signatures. For example:

.. py:function:: Timer.repeat(repeat=3, number=1000000)

For methods you should use py:method.

The description normally includes information about the parameters required and how they are used (especially whether mutable objects passed as parameters are modified), side effects, and possible exceptions.

This information can (in any py directive) optionally be given in a structured form, see Info field lists.

options

.. py:data:: name

Describes global data in a module, including both variables and values used as “defined constants.” Class and object attributes are not documented using this environment.

options

.. py:exception:: name

Describes an exception class. The signature can, but need not include parentheses with constructor arguments.

options

.. py:class:: name

.. py:class:: name(parameters)

Describes a class. The signature can optionally include parentheses with parameters which will be shown as the constructor arguments. See also Python Signatures.

Methods and attributes belonging to the class should be placed in this directive’s body. If they are placed outside, the supplied name should contain the class name so that cross-references still work. Example:

.. py:class:: Foo


   .. py:method:: quux()
-- or --
.. py:class:: Bar
.. py:method:: Bar.quux()

The first way is the preferred one.

options

.. py:attribute:: name

Describes an object data attribute. The description should include information about the type of the data to be expected and whether it may be changed directly.

options

.. py:method:: name(parameters)

Describes an object method. The parameters should not include the self parameter. The description should include similar information to that described for function. See also Python Signatures and Info field lists.

options

.. py:staticmethod:: name(parameters)

Like py:method, but indicates that the method is a static method.

New in version 0.4.

.. py:classmethod:: name(parameters)

Like py:method, but indicates that the method is a class method.

New in version 0.6.

.. py:decorator:: name

.. py:decorator:: name(parameters)

Describes a decorator function. The signature should represent the usage as a decorator. For example, given the functions

def removename(func):


    func.__name__ = ''


    return func
def setnewname(name):


    def decorator(func):


        func.__name__ = name


        return func


    return decorator

the descriptions should look like this:

.. py:decorator:: removename


   Remove name of the decorated function.
.. py:decorator:: setnewname(name)


   Set name of the decorated function to *name*.

(as opposed to .. py:decorator:: removename(func).)

There is no py:deco role to link to a decorator that is marked up with this directive; rather, use the py:func role.

.. py:decoratormethod:: name

.. py:decoratormethod:: name(signature)

Same as py:decorator, but for decorators that are methods.

Refer to a decorator method using the py:meth role.

• param, parameter, arg, argument, key, keyword: Description of a parameter.
• type: Type of a parameter. Creates a link if possible.
• raises, raise, except, exception: That (and when) a specific exception is raised.
• var, ivar, cvar: Description of a variable.
• vartype: Type of a variable. Creates a link if possible.
• returns, return: Description of the return value.
• rtype: Return type. Creates a link if possible.
• meta: Add metadata to description of the python object. The metadata will not be shown on output document. For example, :meta private: indicates the python object is private member. It is used in sphinx.ext.autodoc for filtering members.

:py:mod:

Reference a module; a dotted name may be used. This should also be used for package names.

:py:func:

Reference a Python function; dotted names may be used. The role text needs not include trailing parentheses to enhance readability; they will be added automatically by Sphinx if the add_function_parentheses config value is True (the default).

:py:data:

Reference a module-level variable.

:py:const:

Reference a “defined” constant. This may be a Python variable that is not intended to be changed.

:py:class:

Reference a class; a dotted name may be used.

:py:meth:

Reference a method of an object. The role text can include the type name and the method name; if it occurs within the description of a type, the type name can be omitted. A dotted name may be used.

:py:attr:

Reference a data attribute of an object.

:py:exc:

Reference an exception. A dotted name may be used.

:py:obj:

Reference an object of unspecified type. Useful e.g. as the default_role.

New in version 0.4.

.. c:member:: declaration

.. c:var:: declaration

Describes a C struct member or variable. Example signature:

.. c:member:: PyObject *PyTypeObject.tp_bases

The difference between the two directives is only cosmetic.

.. c:function:: function prototype

Describes a C function. The signature should be given as in C, e.g.:

.. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

Note that you don’t have to backslash-escape asterisks in the signature, as it is not parsed by the reST inliner.

.. c:macro:: name

.. c:macro:: name(arg list)

Describes a C macro, i.e., a C-language #define, without the replacement text.

New in version 3.0: The function style variant.

.. c:struct:: name

Describes a C struct.

New in version 3.0.

.. c:union:: name

Describes a C union.

New in version 3.0.

.. c:enum:: name

Describes a C enum.

New in version 3.0.

.. c:enumerator:: name

Describes a C enumerator.

New in version 3.0.

.. c:type:: typedef-like declaration

.. c:type:: name

Describes a C type, either as a typedef, or the alias for an unspecified type.

:c:member:

:c:data:

:c:var:

:c:func:

:c:macro:

:c:struct:

:c:union:

:c:enum:

:c:enumerator:

:c:type:

Reference a C declaration, as defined above. Note that c:member, c:data, and c:var are equivalent.

New in version 3.0: The var, struct, union, enum, and enumerator roles.

struct Data

.. c:alias:: name

Insert one or more alias declarations. Each entity can be specified as they can in the c:any role.

For example:

.. c:var:: int data
.. c:function:: int f(double k)
.. c:alias:: data


             f

becomes

New in version 3.2.

Options

:c:expr:

:c:texpr:

Insert a C expression or type either as inline code (cpp:expr) or inline text (cpp:texpr). For example:

.. c:var:: int a = 42
.. c:function:: int f(int i)
An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`).
A type: :c:expr:`const Data*`
(or as text :c:texpr:`const Data*`).

will be rendered as follows:

An expression: a * f(a) (or as text: a * f(a)).

A type: const Data* (or as text const Data*).

New in version 3.0.

.. c:namespace:: scope specification

Changes the current scope for the subsequent objects to the given scope, and resets the namespace directive stack. Note that nested scopes can be specified by separating with a dot, e.g.:

.. c:namespace:: Namespace1.Namespace2.SomeStruct.AnInnerStruct

All subsequent objects will be defined as if their name were declared with the scope prepended. The subsequent cross-references will be searched for starting in the current scope.

Using NULL or 0 as the scope will change to global scope.

.. c:namespace-push:: scope specification

Change the scope relatively to the current scope. For example, after:

.. c:namespace:: A.B
.. c:namespace-push:: C.D

the current scope will be A.B.C.D.

.. c:namespace-pop::

Undo the previous c:namespace-push directive (not just pop a scope). For example, after:

.. c:namespace:: A.B
.. c:namespace-push:: C.D
.. c:namespace-pop::

the current scope will be A.B (not A.B.C).

If no previous c:namespace-push directive has been used, but only a c:namespace directive, then the current scope will be reset to global scope. That is, .. c:namespace:: A.B is equivalent to:

.. c:namespace:: NULL
.. c:namespace-push:: A.B

.. cpp:class:: class specifier

.. cpp:struct:: class specifier

Describe a class/struct, possibly with specification of inheritance, e.g.,:

.. cpp:class:: MyClass : public MyBase, MyOtherBase

The difference between cpp:class and cpp:struct is only cosmetic: the prefix rendered in the output, and the specifier shown in the index.

The class can be directly declared inside a nested scope, e.g.,:

.. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase

A class template can be declared:

.. cpp:class:: template<typename T, std::size_t N> std::array

or with a line break:

.. cpp:class:: template<typename T, std::size_t N> \


               std::array

Full and partial template specialisations can be declared:

.. cpp:class:: template<> \


               std::array<bool, 256>
.. cpp:class:: template<typename T> \


               std::array<T, 42>

New in version 2.0: The cpp:struct directive.

.. cpp:function:: (member) function prototype

Describe a function or member function, e.g.,:

.. cpp:function:: bool myMethod(int arg1, std::string arg2)


   A function with parameters and types.
.. cpp:function:: bool myMethod(int, double)


   A function with unnamed parameters.
.. cpp:function:: const T &MyClass::operator[](std::size_t i) const


   An overload for the indexing operator.
.. cpp:function:: operator bool() const


   A casting operator.
.. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept


   A constexpr function.
.. cpp:function:: MyClass::MyClass(const MyClass&) = default


   A copy constructor with default implementation.

Function templates can also be described:

.. cpp:function:: template<typename U> \


                  void print(U &&u)

and function template specialisations:

.. cpp:function:: template<> \


                  void print(int i)

.. cpp:member:: (member) variable declaration

.. cpp:var:: (member) variable declaration

Describe a variable or member variable, e.g.,:

.. cpp:member:: std::string MyClass::myMember
.. cpp:var:: std::string MyClass::myOtherMember[N][M]
.. cpp:member:: int a = 42

Variable templates can also be described:

.. cpp:member:: template<class T> \


                constexpr T pi = T(3.1415926535897932385)

.. cpp:type:: typedef declaration

.. cpp:type:: name

.. cpp:type:: type alias declaration

Describe a type as in a typedef declaration, a type alias declaration, or simply the name of a type with unspecified type, e.g.,:

.. cpp:type:: std::vector<int> MyList


   A typedef-like declaration of a type.
.. cpp:type:: MyContainer::const_iterator


   Declaration of a type alias with unspecified type.
.. cpp:type:: MyType = std::unordered_map<int, std::string>


   Declaration of a type alias.

A type alias can also be templated:

.. cpp:type:: template<typename T> \


              MyContainer = std::vector<T>

The example are rendered as follows.

.. cpp:enum:: unscoped enum declaration

.. cpp:enum-struct:: scoped enum declaration

.. cpp:enum-class:: scoped enum declaration

Describe a (scoped) enum, possibly with the underlying type specified. Any enumerators declared inside an unscoped enum will be declared both in the enum scope and in the parent scope. Examples:

.. cpp:enum:: MyEnum


   An unscoped enum.
.. cpp:enum:: MySpecificEnum : long


   An unscoped enum with specified underlying type.
.. cpp:enum-class:: MyScopedEnum


   A scoped enum.
.. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type


   A scoped enum with non-default visibility, and with a specified


   underlying type.

.. cpp:enumerator:: name

.. cpp:enumerator:: name = constant

Describe an enumerator, optionally with its value defined, e.g.,:

.. cpp:enumerator:: MyEnum::myEnumerator
.. cpp:enumerator:: MyEnum::myOtherEnumerator = 42

.. cpp:union:: name

Describe a union.

New in version 1.8.

.. cpp:concept:: template-parameter-list name

WARNING:

Describe a concept. It must have exactly 1 template parameter list. The name may be a nested name. Example:

.. cpp:concept:: template<typename It> std::Iterator


   Proxy to an element of a notional sequence that can be compared,


   indirected, or incremented.


   **Notation**


   .. cpp:var:: It r


      An lvalue.


   **Valid Expressions**


   - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.


   - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when


     :cpp:expr:`r` is incrementable.

This will render as follows:

New in version 1.5.

• :noindexentry:, see Basic Markup.
• :tparam-line-spec:, for templated declarations. If specified, each template parameter will be rendered on a separate line.

  New in version 1.6.

class Data

.. cpp:alias:: name or function signature

Insert one or more alias declarations. Each entity can be specified as they can in the cpp:any role. If the name of a function is given (as opposed to the complete signature), then all overloads of the function will be listed.

For example:

.. cpp:alias:: Data::a


               overload_example::C::f

becomes

whereas:

.. cpp:alias:: void overload_example::C::f(double d) const


               void overload_example::C::f(double d)

becomes

New in version 2.0.

std::Iterator{It} void advance(It &it)

A function template with a template parameter constrained to be an Iterator.

std::LessThanComparable{T} class MySortedContainer

A class template with a template parameter constrained to be LessThanComparable.

:cpp:expr:

:cpp:texpr:

Insert a C++ expression or type either as inline code (cpp:expr) or inline text (cpp:texpr). For example:

.. cpp:var:: int a = 42
.. cpp:function:: int f(int i)
An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`).
A type: :cpp:expr:`const MySortedContainer<int>&`
(or as text :cpp:texpr:`const MySortedContainer<int>&`).

will be rendered as follows:

An expression: a * f(a) (or as text: a * f(a)).

A type: const MySortedContainer<int>& (or as text const MySortedContainer<int>&).

New in version 1.7: The cpp:expr role.

New in version 1.8: The cpp:texpr role.

.. cpp:namespace:: scope specification

Changes the current scope for the subsequent objects to the given scope, and resets the namespace directive stack. Note that the namespace does not need to correspond to C++ namespaces, but can end in names of classes, e.g.,:

.. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass

All subsequent objects will be defined as if their name were declared with the scope prepended. The subsequent cross-references will be searched for starting in the current scope.

Using NULL, 0, or nullptr as the scope will change to global scope.

A namespace declaration can also be templated, e.g.,:

.. cpp:class:: template<typename T> \


               std::vector
.. cpp:namespace:: template<typename T> std::vector
.. cpp:function:: std::size_t size() const

declares size as a member function of the class template std::vector. Equivalently this could have been declared using:

.. cpp:class:: template<typename T> \


               std::vector


   .. cpp:function:: std::size_t size() const

or:

.. cpp:class:: template<typename T> \


               std::vector

.. cpp:namespace-push:: scope specification

Change the scope relatively to the current scope. For example, after:

.. cpp:namespace:: A::B
.. cpp:namespace-push:: C::D

the current scope will be A::B::C::D.

New in version 1.4.

.. cpp:namespace-pop::

Undo the previous cpp:namespace-push directive (not just pop a scope). For example, after:

.. cpp:namespace:: A::B
.. cpp:namespace-push:: C::D
.. cpp:namespace-pop::

the current scope will be A::B (not A::B::C).

If no previous cpp:namespace-push directive has been used, but only a cpp:namespace directive, then the current scope will be reset to global scope. That is, .. cpp:namespace:: A::B is equivalent to:

.. cpp:namespace:: nullptr
.. cpp:namespace-push:: A::B

New in version 1.4.

• param, parameter, arg, argument: Description of a parameter.
• tparam: Description of a template parameter.
• returns, return: Description of a return value.
• throws, throw, exception: Description of a possibly thrown exception.

:cpp:any:

:cpp:class:

:cpp:struct:

:cpp:func:

:cpp:member:

:cpp:var:

:cpp:type:

:cpp:concept:

:cpp:enum:

:cpp:enumerator:

Reference a C++ declaration by name (see below for details). The name must be properly qualified relative to the position of the link.

New in version 2.0: The cpp:struct role as alias for the cpp:class role.

class C

• Arbitrary overload: C::f, C::f()
• Also arbitrary overload: C::f(), C::f()
• Specific overload: void C::f(), void C::f()
• Specific overload: void C::f(int), void C::f(int)
• Specific overload: void C::f(double), void C::f(double)
• Specific overload: void C::f(double) const, void C::f(double) const

class Wrapper

• template\<typename TOuter> Wrapper::Outer (template<typename TOuter> Wrapper::Outer)
• template\<typename TOuter> template\<typename TInner> Wrapper::Outer<TOuter>::Inner (template<typename TOuter> template<typename TInner> Wrapper::Outer<TOuter>::Inner)

• Wrapper::Outer (Wrapper::Outer)
• Wrapper::Outer::Inner (Wrapper::Outer::Inner)
• template\<typename TInner> Wrapper::Outer::Inner (template<typename TInner> Wrapper::Outer::Inner)

template<typename TOuter> class Outer

template<> class Outer<int>

template<typename T> class Outer<T*>

.. option:: name args, name args, ...

Describes a command line argument or switch. Option argument names should be enclosed in angle brackets. Examples:

.. option:: dest_dir


   Destination directory.
.. option:: -m <module>, --module <module>


   Run a module as a script.

The directive will create cross-reference targets for the given options, referenceable by option (in the example case, you’d use something like :option:`dest_dir`, :option:`-m`, or :option:`--module`).

cmdoption directive is a deprecated alias for the option directive.

.. envvar:: name

Describes an environment variable that the documented code or program uses or defines. Referenceable by envvar.

.. program:: name

Like py:currentmodule, this directive produces no output. Instead, it serves to notify Sphinx that all following option directives document options for the program called name.

If you use program, you have to qualify the references in your option roles by the program name, so if you have the following situation

.. program:: rm
.. option:: -r


   Work recursively.
.. program:: svn
.. option:: -r revision


   Specify the revision to work upon.

then :option:`rm -r` would refer to the first option, while :option:`svn -r` would refer to the second one.

The program name may contain spaces (in case you want to document subcommands like svn add and svn commit separately).

New in version 0.5.

.. describe:: text

.. object:: text

This directive produces the same formatting as the specific ones provided by domains, but does not create index entries or cross-referencing targets. Example:

.. describe:: PAPER


   You can set this variable to select a paper size.

.. js:module:: name

This directive sets the module name for object declarations that follow after. The module name is used in the global module index and in cross references. This directive does not create an object heading like py:class would, for example.

By default, this directive will create a linkable entity and will cause an entry in the global module index, unless the noindex option is specified. If this option is specified, the directive will only update the current module name.

New in version 1.6.

.. js:function:: name(signature)

Describes a JavaScript function or method. If you want to describe arguments as optional use square brackets as documented for Python signatures.

You can use fields to give more details about arguments and their expected types, errors which may be thrown by the function, and the value being returned:

.. js:function:: $.getJSON(href, callback[, errback])


   :param string href: An URI to the location of the resource.


   :param callback: Gets called with the object.


   :param errback:


       Gets called in case the request fails. And a lot of other


       text so we need multiple lines.


   :throws SomeError: For whatever reason in that case.


   :returns: Something.

This is rendered as:

.. js:method:: name(signature)

This directive is an alias for js:function, however it describes a function that is implemented as a method on a class object.

New in version 1.6.

.. js:class:: name

Describes a constructor that creates an object. This is basically like a function but will show up with a class prefix:

.. js:class:: MyAnimal(name[, age])


   :param string name: The name of the animal


   :param number age: an optional age for the animal

This is rendered as:

.. js:data:: name

Describes a global variable or constant.

.. js:attribute:: object.name

Describes the attribute name of object.

:js:mod:

:js:func:

:js:meth:

:js:class:

:js:data:

:js:attr:

.. rst:directive:: name

Describes a reST directive. The name can be a single directive name or actual directive syntax (.. prefix and :: suffix) with arguments that will be rendered differently. For example:

.. rst:directive:: foo


   Foo description.
.. rst:directive:: .. bar:: baz


   Bar description.

will be rendered as:

.. rst:directive:option:: name

Describes an option for reST directive. The name can be a single option name or option name with arguments which separated with colon (:). For example:

.. rst:directive:: toctree


   .. rst:directive:option:: caption: caption of ToC


   .. rst:directive:option:: glob

will be rendered as:

options

.. rst:directive:: toctree


   .. rst:directive:option:: maxdepth


      :type: integer or no value

.. rst:role:: name

Describes a reST role. For example:

.. rst:role:: foo


   Foo description.

will be rendered as:

:rst:dir:

:rst:role:

:math:numref:

Role for cross-referencing equations defined by math directive via their label. Example:

.. math:: e^{i\pi} + 1 = 0


   :label: euler
Euler's identity, equation :math:numref:`euler`, was elected one of the
most beautiful mathematical formulas.

New in version 1.8.

1.

Install the Markdown parser recommonmark:

pip install --upgrade recommonmark

NOTE:

2.

Add recommonmark to the list of configured extensions:

extensions = ['recommonmark']

Changed in version 1.8: Version 1.8 deprecates and version 3.0 removes the source_parsers configuration variable that was used by older recommonmark versions.

3.

If you want to use Markdown files with extensions other than .md, adjust the source_suffix variable. The following example configures Sphinx to parse all files with the extensions .md and .txt as Markdown:

source_suffix = {


    '.rst': 'restructuredtext',


    '.txt': 'markdown',


    '.md': 'markdown',
}

4.

You can further configure recommonmark to allow custom syntax that standard CommonMark doesn’t support. Read more in the recommonmark documentation.

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

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

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.

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:

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

Changed in version 1.8: Support file type mapping

source_encoding

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

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

source_parsers

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

For example:

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

NOTE:

New in version 1.3.

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

master_doc

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

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

exclude_patterns

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

Example patterns:

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

New in version 1.0.

templates_path

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

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

template_bridge

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

rst_epilog

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

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

New in version 0.6.

rst_prolog

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

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

New in version 1.0.

primary_domain

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

New in version 1.0.

default_role

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

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

New in version 0.4.

keep_warnings

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

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

New in version 0.5.

suppress_warnings

A list of warning types to suppress arbitrary warning messages.

Sphinx supports following warning types:

You can choose from these types.

Now, this option should be considered experimental.

New in version 1.4.

Changed in version 1.5: Added misc.highlighting_failure

Changed in version 1.5.1: Added epub.unknown_project_files

Changed in version 1.6: Added ref.footnote

Changed in version 2.1: Added autosectionlabel.*

Changed in version 3.3.0: Added epub.duplicated_toc_entry

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 dev-extensions for how to do that).

New in version 1.3.

manpages_url

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

This also supports manpages specified as man.1.

NOTE:

New in version 1.7.

nitpicky

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

New in version 1.0.

nitpick_ignore

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

New in version 1.1.

numfig

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

NOTE:

New in version 1.3.

numfig_format

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

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

New in version 1.3.

numfig_secnum_depth

New in version 1.3.

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

smartquotes

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

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

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

smartquotes_action

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

New in version 1.6.6.

smartquotes_excludes

This is a dict whose default is:

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

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

NOTE:

HINT:

make latex O="-D smartquotes_action="

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:

today

today_fmt

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

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

highlight_language

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

New in version 0.5.

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

highlight_options

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

New in version 1.3.

pygments_style

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

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

add_function_parentheses

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

add_module_names

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

show_authors

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

modindex_common_prefix

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

New in version 0.6.

trim_footnote_reference_space

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

New in version 0.6.

trim_doctest_flags

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

New in version 1.0.

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

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.

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 None, which means that no translation will be done.

New in version 0.5.

Changed in version 1.4: Support figure substitution

Currently supported languages by Sphinx are:

locale_dirs

New in version 0.5.

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

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

The default is ['locales'].

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

gettext_compact

New in version 1.1.

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

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:

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:

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

The default is [].

New in version 1.3.

figure_language_filename

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

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.

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.

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 URL which points to the root of the HTML documentation. It is used to indicate the location of document like canonical_url.

New in version 1.8.

html_codeblock_linenos_style

The style of line numbers for code-blocks.

New in version 3.2.

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. It is placed at the top of the sidebar; its width should therefore not exceed 200 pixels. Default: None.

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

html_favicon

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

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

html_css_files

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

Example:

html_css_files = ['custom.css',


                  'https://example.com/css/custom.css',


                  ('print.css', {'media': 'print'})]

New in version 1.8.

html_js_files

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

Example:

html_js_files = ['script.js',


                 'https://example.com/scripts/custom.js',


                 ('custom.js', {'async': 'async'})]

New in version 1.8.

html_static_path

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

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

NOTE:

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

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_add_permalinks

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

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

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

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

html_sidebars

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

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

The values can be either lists or single strings.

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:

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. The default is ".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_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:

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:

Other option values depend on splitter value which you choose.

html_search_options = {


    'type': 'mecab',


    'dic_enc': 'utf-8',


    'dict': '/path/to/mecab.dic',


    'lib': '/path/to/libmecab.so',
}

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:

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, images itself links to the original image if it doesn’t have ‘target’ option or scale related options: ‘scale’, ‘width’, ‘height’. The default is True.

Document authors can this feature manually with giving no-scaled-link class to the image:

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

New in version 1.6.

Deprecated since version 2.0.

html4_writer

Output is processed with HTML4 writer. Default is False.

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.

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.

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:

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.

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', u'Cover Page'),)

The default value is ().

epub_pre_files

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

epub_pre_files = [


    ('index.html', 'Welcome'),
]

The default value is [].

epub_post_files

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

epub_exclude_files

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

epub_tocdepth

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

epub_tocdup

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

epub_tocscope

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

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:

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

latex_engine

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