Options for figure numbering¶

numfig¶

Type:

bool

Default:

False

IfTrue, figures, tables and code-blocks are automatically numberedif they have a caption.Thenumref role is enabled.Obeyed so far only by HTML and LaTeX builders.

Note

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

Added in version 1.3.

numfig_format¶

Type:

dict[str,str]

Default:

{}

A dictionary mapping'figure','table','code-block' and'section' to stringsthat are used for format of figure numbers.The marker%s will be replaced with the figure number.

The defaults are:

numfig_format={'code-block':'Listing%s','figure':'Fig.%s','section':'Section','table':'Table%s',}

Added in version 1.3.

numfig_secnum_depth¶

Type:

int

Default:

1

• If set to0, figures, tables, and code-blocksare continuously numbered starting at1.

• If1, the numbering will bex.1,x.2, …withx representing the section number.(If there is no top-level section, the prefix will not be added ).This naturally applies only if section numbering has been activated viathe:numbered: option of thetoctree directive.

• If2, the numbering will bex.y.1,x.y.2, …withx representing the section number andy the sub-section number.If located directly under a section, there will be noy. prefix,and if there is no top-level section, the prefix will not be added.

• Any other positive integer can be used, following the rules above.

Added in version 1.3.

Changed in version 1.7:The LaTeX builder obeys this settingifnumfig is set toTrue.

Options for highlighting¶

highlight_language¶

Type:

str

Default:

'default'

The default language to highlight source code in.The default is'default',which suppresses warnings if highlighting as Python code fails.

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

Added in version 0.5.

Changed in version 1.4:The default is now'default'.

highlight_options¶

Type:

dict[str,dict[str,Any]]

Default:

{}

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

Example:

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

Added in version 1.3.

Changed in version 3.5:Allow configuring highlight options for multiple lexers.

pygments_style¶

Type:

str

Default:

'sphinx'

The style name to use for Pygments highlighting of source code.If not set, either the theme’s default styleor'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.

Options for HTTP requests¶

tls_verify¶

Type:

bool

Default:

True

If True, Sphinx verifies server certificates.

Added in version 1.5.

tls_cacerts¶

Type:

str|dict[str,str]

Default:

''

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

Added in version 1.5.

Tip

Sphinx usesrequests as a HTTP library internally.Iftls_cacerts is not set,Sphinx falls back to requests’ default behaviour.SeeSSL Cert Verification for further details.

user_agent¶

Type:

str

Default:

'Mozilla/5.0 (X11; Linux x86_64; rv:100.0) Gecko/20100101 Firefox/100.0 Sphinx/X.Y.Z'

Set the User-Agent used by Sphinx for HTTP requests.

Added in version 2.3.

Options for internationalisation¶

These options influence Sphinx’sNative Language Support.See the documentation onInternationalization for details.

language¶

Type:

str

Default:

'en'

The code for the language the documents are written in.Any text automatically generated by Sphinx will be in that language.Also, Sphinx will try to substitute individual paragraphsfrom your documents with the translation sets obtainedfromlocale_dirs.Sphinx will search language-specific figures named byfigure_language_filename(e.g. the German version ofmyfigure.png will bemyfigure.de.pngby default setting)and substitute them for original figures.In the LaTeX builder, a suitable language will be selectedas an option for theBabel package.

Added in version 0.5.

Changed in version 1.4:Support figure substitution

Changed in version 5.0:The default is now'en' (previouslyNone).

Currently supported languages by Sphinx are:

• ar – Arabic

• bg – Bulgarian

• bn – Bengali

• ca – Catalan

• cak – Kaqchikel

• cs – Czech

• cy – Welsh

• da – Danish

• de – German

• el – Greek

• en – English (default)

• eo – Esperanto

• es – Spanish

• et – Estonian

• eu – Basque

• fa – Iranian

• fi – Finnish

• fr – French

• he – Hebrew

• hi – Hindi

• hi_IN – Hindi (India)

• hr – Croatian

• hu – Hungarian

• id – Indonesian

• it – Italian

• ja – Japanese

• ko – Korean

• lt – Lithuanian

• lv – Latvian

• mk – Macedonian

• nb_NO – Norwegian Bokmal

• ne – Nepali

• nl – Dutch

• pl – Polish

• pt – Portuguese

• pt_BR – Brazilian Portuguese

• pt_PT – European Portuguese

• ro – Romanian

• ru – Russian

• si – Sinhala

• sk – Slovak

• sl – Slovenian

• sq – Albanian

• sr – Serbian

• sr@latin – Serbian (Latin)

• sr_RS – Serbian (Cyrillic)

• sv – Swedish

• ta – Tamil

• te – Telugu

• tr – Turkish

• uk_UA – Ukrainian

• ur – Urdu

• vi – Vietnamese

• zh_CN – Simplified Chinese

• zh_TW – Traditional Chinese

locale_dirs¶

Type:

list[str]

Default:

['locales']

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

Internal messages are fetched from a text domain ofsphinx;so if you add the directory./locales to this setting,the message catalogs(compiled from.po format usingmsgfmt)must be in./locales/language/LC_MESSAGES/sphinx.mo.The text domain of individual documentsdepends ongettext_compact.

Note

The-voptiontosphinx-buildis useful to check thelocale_dirs setting is working as expected.If the message catalog directory not found, debug messages are emitted.

Added in version 0.5.

Changed in version 1.5:Uselocales directory as a default value

gettext_allow_fuzzy_translations¶

Type:

bool

Default:

False

If True, “fuzzy” messages in the message catalogs are used for translation.

Added in version 4.3.

gettext_compact¶

Type:

bool|str

Default:

True

• IfTrue, a document’s text domain isits docname if it is a top-level project fileand its very base directory otherwise.

• IfFalse, a document’s text domain isthe docname, in full.

• If set to a string, every document’s text domain isset to this string, making all documents use single text domain.

Withgettext_compact=True, the documentmarkup/code.rst ends up in themarkup text domain.With this option set toFalse, it ismarkup/code.With this option set to'sample', it issample.

Added in version 1.1.

Changed in version 3.3:Allow string values.

gettext_uuid¶

Type:

bool

Default:

False

IfTrue, Sphinx generates UUID informationfor version tracking in message catalogs.It is used to:

• Add a UUID line for eachmsgid in.pot files.

• Calculate similarity between new msgids and previously saved old msgids.(This calculation can take a long time.)

Tip

If you want to accelerate the calculation,you can use a third-party package (Levenshtein) by runningpip install levenshtein.

Added in version 1.3.

gettext_location¶

Type:

bool

Default:

True

IfTrue, Sphinx generates location informationfor messages in message catalogs.

Added in version 1.3.

gettext_auto_build¶

Type:

bool

Default:

True

IfTrue, Sphinx builds a.mo filefor each translation catalog file.

Added in version 1.3.

gettext_additional_targets¶

Type:

set[str]|Sequence[str]

Default:

[]

Enablegettext translation for certain element types.Example:

gettext_additional_targets={'literal-block','image'}

The following element types are supported:

• 'index' – index terms

• 'literal-block' – literal blocks(:: annotation andcode-block directive)

• 'doctest-block' – doctest block

• 'raw' – raw content

• 'image' – image/figure uri

Added in version 1.3.

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

Changed in version 7.4:Permit and prefer a set type.

figure_language_filename¶

Type:

str

Default:

'{root}.{language}{ext}'

The filename format for language-specific figures.The available format tokens are:

• {root}: the filename, including any path component,without the file extension.For example:images/filename.

• {path}: the directory path component of the filename,with a trailing slash if non-empty.For example:images/.

• {basename}: the filename without the directory pathor file extension components.For example:filename.

• {ext}: the file extension.For example:.png.

• {language}: the translation language.For example:en.

• {docpath}: the directory path component for the current document,with a trailing slash if non-empty.For example:dirname/.

By default, an image directive..image:: images/filename.png,using an image atimages/filename.png,will use the language-specific figure filenameimages/filename.en.png.

Iffigure_language_filename is set as below,the language-specific figure filename will beimages/en/filename.png instead.

figure_language_filename='{path}{language}/{basename}{ext}'

Added in version 1.4.

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

Changed in version 3.2:Added{docpath} token.

translation_progress_classes¶

Type:

bool|'translated'|'untranslated'

Default:

False

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

True

Addtranslated anduntranslated classesto all nodes with translatable content.

'translated'

Only add thetranslated class.

'untranslated'

Only add theuntranslated class.

False

Do not add any classes to indicate translation progress.

Added in version 7.1.

Options for markup¶

default_role¶

Type:

str

Default:

None

The name of a reStructuredText role (builtin or Sphinx extension)to use as the default role, that is, for text marked up`likethis`.This can be set to'py:obj' to make`filter`a cross-reference to the Python function “filter”.

The default role can always be set within individual documents usingthe standard reStructuredTextdefault-role directive.

Added in version 0.4.

keep_warnings¶

Type:

bool

Default:

False

Keep warnings as “system message” paragraphs in the rendered documents.Warnings are always written to the standard error streamwhensphinx-build is run, regardless of this setting.

Added in version 0.5.

option_emphasise_placeholders¶

Type:

bool

Default:

False

When enabled, emphasise placeholders inoption directives.To display literal braces, escape with a backslash (\{).For example,option_emphasise_placeholders=Trueand..option::-foption={TYPE} would render withTYPE emphasised.

Added in version 5.1.

primary_domain¶

Type:

str

Default:

'py'

The name of the defaultdomain.Can also beNone to disable a default domain.The default is'py', for the Python domain.

Those objects in other domain(whether the domain name is given explicitly,or selected by adefault-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”).Example:

primary_domain='cpp'

Added in version 1.0.

rst_epilog¶

Type:

str

Default:

''

A string of reStructuredText that will be includedat the end of every source file that is read.This is a possible place to add substitutions thatshould be available in every file (another beingrst_prolog).Example:

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

Added in version 0.6.

rst_prolog¶

Type:

str

Default:

''

A string of reStructuredText that will be includedat the beginning of every source file that is read.This is a possible place to add substitutions thatshould be available in every file (another beingrst_epilog).Example:

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

Added in version 1.0.

show_authors¶

Type:

bool

Default:

False

A boolean that decides whethercodeauthor andsectionauthor directives produce any output in the built files.

trim_footnote_reference_space¶

Type:

bool

Default:

False

Trim spaces before footnote references that arenecessary for the reStructuredText parser to recognise the footnote,but do not look too nice in the output.

Added in version 0.6.

Options for Maths¶

These options control maths markup and notation.

math_eqref_format¶

Type:

str

Default:

'({number})'

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.

Added in version 1.7.

math_number_all¶

Type:

bool

Default:

False

Force all displayed equations to be numbered.Example:

math_number_all=True

Added in version 1.4.

math_numfig¶

Type:

bool

Default:

True

IfTrue, displayed math equations are numbered across pageswhennumfig is enabled.Thenumfig_secnum_depth setting is respected.Theeq, notnumref, rolemust be used to reference equation numbers.

Added in version 1.7.

math_numsep¶

Type:

str

Default:

'.'

A string that defines the separator between section numbersand the equation number whennumfig is enabled andnumfig_secnum_depth is positive.

Example:'-' gets rendered as1.2-3.

Added in version 7.4.

Options for the nitpicky mode¶

nitpicky¶

Type:

bool

Default:

False

Enables nitpicky mode ifTrue.In nitpicky mode, Sphinx will warn aboutall referenceswhere the target cannot be found.This is recommended for new projects as it ensures that all referencesare to valid targets.

You can activate this mode temporarily usingthe--nitpicky command-line option.Seenitpick_ignore for a way to mark missing referencesas “known missing”.

nitpicky=True

Added in version 1.0.

nitpick_ignore¶

Type:

set[tuple[str,str]]|Sequence[tuple[str,str]]

Default:

()

A set or list of(warning_type,target) tuplesthat should be ignored when generating warningsin"nitpickymode".Note thatwarning_type should include the domain name if present.Example:

nitpick_ignore={('py:func','int'),('envvar','LD_LIBRARY_PATH'),}

Added in version 1.1.

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

nitpick_ignore_regex¶

Type:

set[tuple[str,str]]|Sequence[tuple[str,str]]

Default:

()

An extended version ofnitpick_ignore,which instead interprets thewarning_type andtarget stringsas regular expressions.Note that the regular expression must match the whole string(as if the^ and$ markers were inserted).

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

Added in version 4.1.

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

Options for object signatures¶

add_function_parentheses¶

Type:

bool

Default:

True

A boolean that decides whether parentheses are appended to function andmethod role text (e.g. the content of:func:`input`) to signify that thename is callable.

maximum_signature_line_length¶

Type:

int|None

Default:

None

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

WhenNone, there is no maximum length and the entiresignature will be displayed on a single logical line.

A ‘logical line’ is similar to a hard line break—builders or themesmay choose to ‘soft wrap’ a single logical line,and this setting does not affect that behaviour.

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

Added in version 7.1.

strip_signature_backslash¶

Type:

bool

Default:

False

When backslash stripping is enabled then every occurrence of\\ in adomain directive will be changed to\, even within string literals.This was the behaviour before version 3.0, and setting this variable toTrue will reinstate that behaviour.

Added in version 3.0.

toc_object_entries¶

Type:

bool

Default:

True

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

Added in version 5.2.

toc_object_entries_show_parents¶

Type:

'domain'|'hide'|'all'

Default:

'domain'

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

Use'domain' to allow the domain to determinethe appropriate number of parents to show.For example, the Python domain would showClass.method()andfunction(),leaving out themodule. level of parents.

Use'hide' to only show the name of the elementwithout any parents (i.e.method()).

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

Added in version 5.2.

Options for source files¶

exclude_patterns¶

Type:

Sequence[str]

Default:

()

A list ofglob-style patterns that should be excluded when looking forsource files.They are matched against the source file namesrelative to the source directory,using slashes as directory separators on all platforms.exclude_patterns has priority overinclude_patterns.

Example patterns:

• 'library/xml.rst' – ignores thelibrary/xml.rst file

• 'library/xml' – ignores thelibrary/xml directory

• 'library/xml*' – ignores all files and directories starting withlibrary/xml

• '**/.git' – ignores all.git directories

• 'Thumbs.db' – ignores allThumbs.db files

exclude_patterns is also consulted when looking for static filesinhtml_static_path andhtml_extra_path.

Added in version 1.0.

include_patterns¶

Type:

Sequence[str]

Default:

('**',)

A list ofglob-style patterns that are used to find source files.They are matched against the source filenames relative to the source directory,using slashes as directory separators on all platforms.By default, all files are recursively included from the source directory.exclude_patterns has priority overinclude_patterns.

Example patterns:

• '**' – all files in the source directory and subdirectories,recursively

• 'library/xml' – just thelibrary/xml directory

• 'library/xml*' – all files and directories starting withlibrary/xml

• '**/doc' – alldoc directories (this might be useful ifdocumentation is co-located with source files)

Added in version 5.1.

master_doc¶

root_doc¶

Type:

str

Default:

'index'

Sphinx builds a tree of documents based on thetoctree directivescontained within the source files.This sets the name of the document containing the mastertoctree directive,and hence the root of the entire tree.Example:

master_doc='contents'

Changed in version 2.0:Default is'index' (previously'contents').

Added in version 4.0:Theroot_doc alias.

source_encoding¶

Type:

str

Default:

'utf-8-sig'

The file encoding of all source files.The recommended encoding is'utf-8-sig'.

Added in version 0.5.

Deprecated since version 8.3:Support for source encodings other than UTF-8 is deprecated.Sphinx 10 will only support UTF-8 files.

source_suffix¶

Type:

dict[str,str]|Sequence[str]|str

Default:

{'.rst':'restructuredtext'}

A dictionary mapping the file extensions (suffixes)of source files to their file types.Sphinx considers all files files with suffixes insource_suffixto be source files.Example:

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

By default, Sphinx only supports the'restructuredtext' file type.Further file types can be added with extensions that register differentsource file parsers, such asMyST-Parser.Refer to the extension’s documentation to see which file types it supports.

If the value is a string or sequence of strings,Sphinx will consider that they are all'restructuredtext' files.

Note

File extensions must begin with a dot ('.').

Changed in version 1.3:Support a list of file extensions.

Changed in version 1.8:Change to a map of file extensions to file types.

Options for smart quotes¶

smartquotes¶

Type:

bool

Default:

True

IfTrue, theSmart Quotes transformwill be used to convert quotation marks and dashesto typographically correct entities.

Added in version 1.6.6:Replaces the now-removedhtml_use_smartypants.It applies by default to all builders exceptman andtext(seesmartquotes_excludes.)

Note

Adocutils.conf file located in theconfiguration directory(or a global~/.docutils file) is obeyed unconditionally if itdeactivates smart quotes via the correspondingDocutils option.But if itactivates them, thensmartquotes does prevail.

smartquotes_action¶

Type:

str

Default:

'qDe'

Customise the Smart Quotes transform.See below for the permitted codes.The default'qDe' educatesnormalquote characters",',em- and en-Dashes---,--,andellipses.....

'q'

Convert quotation marks

'b'

Convert backtick quotation marks(``double'' only)

'B'

Convert backtick quotation marks(``double'' and`single')

'd'

Convert dashes(convert-- to em-dashes and--- to en-dashes)

'D'

Convert dashes (old school)(convert-- to en-dashes and--- to em-dashes)

'i'

Convert dashes (inverted old school)(convert-- to em-dashes and--- to en-dashes)

'e'

Convert ellipses...

'w'

Convert'"' entities to'"'

Added in version 1.6.6.

smartquotes_excludes¶

Type:

dict[str,list[str]]

Default:

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

Control when the Smart Quotes transform is disabled.Permitted keys are'builders' and'languages', andThe values are lists of strings.

Each entry gives a sufficient condition to ignore thesmartquotes setting and deactivate the Smart Quotes transform.Example:

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

Note

Currently, in case of invocation ofmake with multipletargets, the first target name is the only one which is tested againstthe'builders' entry and it decides for all.Also, amaketext followingmakehtml needs to be issuedin the formmaketextSPHINXOPTS="-E" to force re-parsingof source files, as the cached ones are already transformed.On the other hand the issue does not arise withdirect usage ofsphinx-build as it caches(in its default usage) the parsed source files in per builder locations.

Hint

An alternative way to effectively deactivate (or customise) thesmart quotes for a given builder, for examplelatex,is to usemake this way:

make latex SPHINXOPTS="-D smartquotes_action="

This can follow somemakehtml with no problem, in contrast to thesituation from the prior note.

Added in version 1.6.6.

Options for templating¶

template_bridge¶

Type:

str

Default:

''

A string with the fully-qualified name of a callable (or simply a class)that returns an instance ofTemplateBridge.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-awareif HTML themes are to be used.)Example:

template_bridge='module.CustomTemplateBridge'

templates_path¶

Type:

Sequence[str]

Default:

()

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

templates_path=['.templates']

Changed in version 1.3:As these files are not meant to be built,they are automatically excluded when discovering source files.

Options for warning control¶

show_warning_types¶

Type:

bool

Default:

True

Add the type of each warning as a suffix to the warning message.For example,WARNING:[...][index] orWARNING:[...][toc.circular].This setting can be useful for determining which warnings types to includein asuppress_warnings list.

Added in version 7.3.0.

Changed in version 8.0.0:The default is nowTrue.

suppress_warnings¶

Type:

Sequence[str]

Default:

()

A list of warning codes to suppress arbitrary warning messages.

Added in version 1.4.

By default, Sphinx supports the following warning codes:

• app.add_directive

• app.add_generic_role

• app.add_node

• app.add_role

• app.add_source_parser

• config.cache

• docutils

• download.not_readable

• duplicate_declaration.c

• duplicate_declaration.cpp

• epub.duplicated_toc_entry

• epub.unknown_project_files

• i18n.babel

• i18n.inconsistent_references

• i18n.not_readable

• i18n.not_writeable

• image.not_readable

• index

• misc.copy_overwrite

• misc.highlighting_failure

• ref.any

• ref.citation

• ref.doc

• ref.footnote

• ref.keyword

• ref.numref

• ref.option

• ref.python

• ref.ref

• ref.term

• toc.circular

• toc.duplicate_entry

• toc.empty_glob

• toc.excluded

• toc.no_title

• toc.not_included

• toc.not_readable

• toc.secnum

Extensions can also define their own warning types.Those defined by the first-partysphinx.ext extensions are:

• autodoc

• autodoc.import_object

• autodoc.mocked_object

• autosectionlabel.<documentname>

• autosummary

• autosummary.import_cycle

• intersphinx.external

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

Added in version 1.4:ref.citation,ref.doc,ref.keyword,ref.numref,ref.option,ref.ref, andref.term.

Added in version 1.4.2:app.add_directive,app.add_generic_role,app.add_node,app.add_role, andapp.add_source_parser.

Added in version 1.5:misc.highlighting_failure.

Added in version 1.5.1:epub.unknown_project_files.

Added in version 1.5.2:toc.secnum.

Added in version 1.6:ref.footnote,download.not_readable, andimage.not_readable.

Added in version 1.7:ref.python.

Added in version 2.0:autodoc.import_object.

Added in version 2.1:autosectionlabel.<documentname>.

Added in version 3.1:toc.circular.

Added in version 3.3:epub.duplicated_toc_entry.

Added in version 4.3:toc.excluded andtoc.not_readable.

Added in version 4.5:i18n.inconsistent_references.

Added in version 7.1:index.

Added in version 7.3:config.cache,intersphinx.external, andtoc.no_title.

Added in version 7.4:docutils andautosummary.import_cycle.

Added in version 8.0:misc.copy_overwrite.

Added in version 8.2:autodoc.mocked_object,duplicate_declaration.c,duplicate_declaration.cpp,i18n.babel,i18n.not_readable,i18n.not_writeable,ref.any,toc.duplicate_entry,toc.empty_glob, andtoc.not_included.

Options for HTML output¶

These options influence HTML output.Various other builders are derived from the HTML output,and also make use of these options.

html_theme¶

Type:

str

Default:

'alabaster'

The theme for HTML output.See theHTML theming section.

Added in version 0.6.

Changed in version 1.3:The default theme is now'alabaster'.

html_theme_options¶

Type:

dict[str,Any]

Default:

{}

A dictionary of options that influence thelook and feel of the selected theme.These are theme-specific.The options understood by thebuiltin themes are describedhere.

Added in version 0.6.

html_theme_path¶

Type:

list[str]

Default:

[]

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

Added in version 0.6.

html_style¶

Type:

Sequence[str]|str

Default:

()

Stylesheets to use for HTML pages.The stylesheet given by the selected theme is used by defaultA file of that name must exist either in Sphinx’sstatic/ pathor in one of the custom paths given inhtml_static_path.If you only want to add or override a few things from the theme,use CSS@import to import the theme’s stylesheet.

Changed in version 5.1:The value can be a iterable of strings.

html_title¶

Type:

str

Default:

'projectreleasedocumentation'

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.

html_short_title¶

Type:

str

Default:

The value ofhtml_title

A shorter “title” for HTML documentation.This is used for links in the header and in the HTML Help documentation.

Added in version 0.4.

html_baseurl¶

Type:

str

Default:

''

The base URL which points to the root of the HTML documentation.It is used to indicate the location of document usingthe Canonical Link Relation.

Added in version 1.8.

html_codeblock_linenos_style¶

Type:

'inline'|'table'

Default:

'inline'

The style of line numbers for code-blocks.

'table'

Display line numbers using<table> tag

'inline'

Display line numbers using<span> tag

Added in version 3.2.

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

Deprecated since version 4.0.

html_context¶

Type:

dict[str,Any]

Default:

{}

A dictionary of values to pass intothe template engine’s context for all pages.Single values can also be put in this dictionary usingsphinx-build’s--html-define command-line option.

Added in version 0.5.

html_logo¶

Type:

str

Default:

''

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

Added in version 0.4.1:The image file will be copied to the_static directory,but only if the file does not already exist there.

Changed in version 4.0:Also accepts a URL.

html_favicon¶

Type:

str

Default:

''

If given, this must be the name of an image file(path relative to theconfiguration directory)that is thefavicon of the documentation,or a URL that points an image file for the favicon.Browsers use this as the icon for tabs, windows and bookmarks.It should be a 16-by-16 pixel icon inthe PNG, SVG, GIF, or ICO file formats.

Example:

html_favicon='static/favicon.png'

Added in version 0.4:The image file will be copied to the_static,but only if the file does not already exist there.

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

html_css_files¶

Type:

Sequence[str|tuple[str,dict[str,str]]]

Default:

[]

A list of CSS files.The entry must be afilename stringor a tuple containing thefilename string and theattributes dictionary.Thefilename must be relative to thehtml_static_path,or a full URI with scheme like'https://example.org/style.css'.Theattributes dictionary is used for the<link> tag’s attributes.

Example:

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

The special attributepriority can be set as an integerto load the CSS file at an earlier or later step.For more information, refer toSphinx.add_css_file().

Added in version 1.8.

Changed in version 3.5:Support thepriority attribute

html_js_files¶

Type:

Sequence[str|tuple[str,dict[str,str]]]

Default:

[]

A list of JavaScript files.The entry must be afilename stringor a tuple containing thefilename string and theattributes dictionary.Thefilename must be relative to thehtml_static_path,or a full URI with scheme like'https://example.org/script.js'.Theattributes dictionary is used for the<script> tag’s attributes.

Example:

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

As a special attribute,priority can be set as an integerto load the JavaScript file at an earlier or later step.For more information, refer toSphinx.add_js_file().

Added in version 1.8.

Changed in version 3.5:Support thepriority attribute

html_static_path¶

Type:

list[str]

Default:

[]

A list of paths that contain custom static files(such as style sheets or script files).Relative paths are taken as relative to theconfiguration directory.They are copied to the output’s_static directoryafter the theme’s static files,so a file nameddefault.css will overwritethe theme’sdefault.css.

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

Note

For security reasons, dotfiles underhtml_static_pathwill not be copied.If you would like to copy them intentionally,explicitly add each file to this setting:

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

An alternative approach is to usehtml_extra_path,which allows copying dotfiles under the directories.

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

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

Changed in version 1.8:The files underhtml_static_path are excluded from sourcefiles.

html_extra_path¶

Type:

list[str]

Default:

[]

A list of paths that contain extra files not directly related tothe documentation,such asrobots.txt or.htaccess.Relative paths are taken as relative to theconfiguration 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.

Added in version 1.2.

Changed in version 1.4:The dotfiles in the extra directory will be copiedto the output directory.And it refersexclude_patterns on copying extrafiles and directories, and ignores if path matches to patterns.

html_last_updated_fmt¶

Type:

str

Default:

None

If set, a ‘Last updated on:’ timestamp is inserted into the page footerusing the givenstrftime() format.The empty string is equivalent to'%b%d, %Y'(or a locale-dependent equivalent).

html_last_updated_use_utc¶

Type:

bool

Default:

False

Use GMT/UTC (+00:00) instead of the system’s local time zonefor the time supplied tohtml_last_updated_fmt.This is most useful when the format used includes the time.

html_permalinks¶

Type:

bool

Default:

True

Add link anchors for each heading and description environment.

Added in version 3.5.

html_permalinks_icon¶

Type:

str

Default:

'¶' (the paragraph sign)

Text for link anchors for each heading and description environment.HTML entities and Unicode are allowed.

Added in version 3.5.

html_sidebars¶

Type:

dict[str,Sequence[str]]

Default:

{}

A dictionary defining custom sidebar templates,mapping document names to template names.

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

Each value must be a list of strings which specifiesthe complete list of sidebar templates to include.If all or some of the default sidebars are to be included,they must be put into this list as well.

The default sidebars (for documents that don’t match any pattern) aredefined by theme itself.The builtin themes use these templates by default:'localtoc.html','relations.html','sourcelink.html', and'searchbox.html'.

The bundled first-party sidebar templates that can be rendered are:

• localtoc.html – a fine-grained table of contents of the currentdocument

• globaltoc.html – a coarse-grained table of contents for the wholedocumentation set, collapsed

• relations.html – two links to the previous and next documents

• sourcelink.html – a link to the source of the current document,if enabled inhtml_show_sourcelink

• searchbox.html – the “quick search” box

Example:

html_sidebars={'**':['globaltoc.html','sourcelink.html','searchbox.html'],'using/windows':['windows-sidebar.html','searchbox.html'],}

This will render the custom templatewindows-sidebar.html and the quicksearch box within the sidebar of the given document, and render the defaultsidebars for all other pages (except that the local TOC is replaced by theglobal TOC).

Note that this value only has no effect ifthe chosen theme does not possess a sidebar,like the builtinscrolls andhaiku themes.

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

Deprecated since version 1.7:A single string value forhtml_sidebars will be removed.

Changed in version 2.0:html_sidebars must be a list of strings,and no longer accepts a single string value.

html_additional_pages¶

Type:

dict[str,str]

Default:

{}

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':'custom-download.html.jinja',}

This will render the templatecustom-download.html.jinjaas the pagedownload.html.

html_domain_indices¶

Type:

bool|Sequence[str]

Default:

True

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

This value can be a Boolean 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'.

Example:

html_domain_indices={'py-modindex',}

Added in version 1.0.

Changed in version 7.4:Permit and prefer a set type.

html_use_index¶

Type:

bool

Default:

True

Controls if an index is added to the HTML documents.

Added in version 0.4.

html_split_index¶

Type:

bool

Default:

False

Generates two versions of the index:once as a single page with all the entries,and once as one page per starting letter.

Added in version 0.4.

html_copy_source¶

Type:

bool

Default:

True

If True, the reStructuredText sources are included in the HTML build as_sources/docname.

html_show_sourcelink¶

Type:

bool

Default:

True

If True (andhtml_copy_source is true as well),links to the reStructuredText sources will be added to the sidebar.

Added in version 0.6.

html_sourcelink_suffix¶

Type:

str

Default:

'.txt'

The suffix to append to source links(seehtml_show_sourcelink),unless files they have this suffix already.

Added in version 1.5.

html_use_opensearch¶

Type:

str

Default:

''

If nonempty, anOpenSearchdescription 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 URLfrom which these documents are served (without trailing slash),e.g.'https://docs.python.org'.

Added in version 0.2.

html_file_suffix¶

Type:

str

Default:

'.html'

The file name suffix (file extension) for generated HTML files.

Added in version 0.4.

html_link_suffix¶

Type:

str

Default:

The value ofhtml_file_suffix

The suffix for generated links to HTML files.Intended to support more esoteric server setups.

Added in version 0.6.

html_show_copyright¶

Type:

bool

Default:

True

If True, “© Copyright …” is shown in the HTML footer,with the value or values fromcopyright.

Added in version 1.0.

html_show_search_summary¶

Type:

bool

Default:

True

Show a summary of the search result, i.e., the text around the keyword.

Added in version 4.5.

html_show_sphinx¶

Type:

bool

Default:

True

Add “Created usingSphinx” to the HTML footer.

Added in version 0.4.

html_output_encoding¶

Type:

str

Default:

'utf-8'

Encoding of HTML output files.This encoding name must both be a valid Python encoding nameand a valid HTMLcharset value.

Added in version 1.0.

html_compact_lists¶

Type:

bool

Default:

True

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

Added in version 1.0.

html_secnumber_suffix¶

Type:

str

Default:

'. '

Suffix for section numbers in HTML output.Set to' ' to suppress the final dot on section numbers.

Added in version 1.0.

html_search_language¶

Type:

str

Default:

The value oflanguage

Language to be used for generating the HTML full-text search index.This defaults to the global language selected withlanguage.English ('en') is used as a fall-back optionif there is no support for this language.

Support exists for the following languages:

• da – Danish

• nl – Dutch

• en – English

• fi – Finnish

• fr – French

• de – German

• hu – Hungarian

• it – Italian

• ja – Japanese

• no – Norwegian

• pt – Portuguese

• ro – Romanian

• ru – Russian

• es – Spanish

• sv – Swedish

• tr – Turkish

• zh – Chinese

Tip

Accelerating build speed

Each language (except Japanese) provides its own stemming algorithm.Sphinx uses a Python implementation by default.If you want to accelerate building the index file,you can use a third-party package (PyStemmer) by runningpip install PyStemmer.

Added in version 1.1:Support English (en) and Japanese (ja).

Changed in version 1.3:Added additional languages.

html_search_options¶

Type:

dict[str,str]

Default:

{}

A dictionary with options for the search language support.The meaning of these options depends on the language selected.Currently, only Japanese and Chinese support options.

Japanese:

type – the type of the splitter to use.

The other options depend on the splitter used.

'sphinx.search.ja.DefaultSplitter'

The TinySegmenter algorithm, used by default.

'sphinx.search.ja.MecabSplitter':

The MeCab bindingTo use this splitter, the ‘mecab’ python bindingor dynamic link library(‘libmecab.so’ for Linux, ‘libmecab.dll’ for Windows) is required.

'sphinx.search.ja.JanomeSplitter':

The Janome binding.To use this splitter,Janome is required.

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

Options for'mecab':

dic_enc:

dic_enc option is the encoding for the MeCab algorithm.

dict:

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

lib:

lib option is the library name for finding the MeCab libraryviactypes if the Python binding is not installed.

For example:

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

Options for'janome':

user_dic:

user_dic option is the user dictionary file path for Janome.

user_dic_enc:

user_dic_enc option is the encoding forthe user dictionary file specified byuser_dic option.Default is ‘utf8’.

Chinese:

dict

Thejieba dictionary path for using a custom dictionary.

Added in version 1.1.

Changed in version 1.4:Allow any custom splitter in thetype setting for Japanese.

html_search_scorer¶

Type:

str

Default:

''

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

The scorer must implement the following interface,and may optionally define thescore() functionfor more granular control.

constScorer={// Implement the following function to further tweak the score for each resultscore:result=>{const[docName,title,anchor,descr,score,filename]=result// ... calculate a new score ...returnscore},// query matches the full name of an objectobjNameMatch:11,// or matches in the last dotted part of the object nameobjPartialMatch:6,// Additive scores depending on the priority of the objectobjPrio:{0:15,// used to be importantResults1:5,// used to be objectResults2:-5,// used to be unimportantResults},//  Used when the priority is not in the mapping.objPrioDefault:0,// query found in titletitle:15,partialTitle:7,// query found in termsterm:5,partialTerm:2,};

Added in version 1.2.

html_scaled_image_link¶

Type:

bool

Default:

True

Link images that have been resized with ascale option (scale,width, orheight)to their original full-resolution image.This will not overwrite any link given by thetarget optionon the theimage directive, if present.

Tip

To disable this feature on a per-image basis,add theno-scaled-link class to the image directive:

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

Added in version 1.3.

Changed in version 3.0:Images with theno-scaled-link class will not be linked.

html_math_renderer¶

Type:

str

Default:

'mathjax'

The maths renderer to use for HTML output.The bundled renders aremathjax andimgmath.You must also load the relevant extension inextensions.

Added in version 1.8.

Options for Single HTML output¶

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

singlehtml_sidebars¶

Type:

dict[str,Sequence[str]]

Default:

The value ofhtml_sidebars

A dictionary defining custom sidebar templates,mapping document names to template names.

This has the same effect ashtml_sidebars,but the only permitted key is'index',and all other keys are ignored.

Options for HTML help output¶

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

htmlhelp_basename¶

Type:

str

Default:

'{project}doc'

Output file base name for HTML help builder.The default is theprojectnamewith spaces removed anddoc appended.

htmlhelp_file_suffix¶

Type:

str

Default:

'.html'

This is the file name suffix for generated HTML help files.

Added in version 2.0.

htmlhelp_link_suffix¶

Type:

str

Default:

The value ofhtmlhelp_file_suffix

Suffix for generated links to HTML files.

Added in version 2.0.

Options for Apple Help output¶

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

applehelp_bundle_name¶

Type:

str

Default:

The value ofproject

The basename for the Apple Help Book.The default is theprojectnamewith spaces removed.

applehelp_bundle_id¶

Type:

str

Default:

None

The bundle ID for the help book bundle.

Warning

Youmust set this value in order to generate Apple Help.

applehelp_bundle_version¶

Type:

str

Default:

'1'

The bundle version, as a string.

applehelp_dev_region¶

Type:

str

Default:

'en-us'

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

applehelp_icon¶

Type:

str

Default:

None

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

applehelp_kb_product¶

Type:

str

Default:

'project-release'

The product tag for use withapplehelp_kb_url.

applehelp_kb_url¶

Type:

str

Default:

None

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

Set this to toNone to disable remote search.

applehelp_remote_url¶

Type:

str

Default:

None

The URL for remote content.You can place a copy of your Help Book’sResources directoryat this location and Help Viewer will attempt to use itto fetch updated content.

For example, if you set it tohttps://example.com/help/Foo/and Help Viewer wants a copy ofindex.html foran English speaking customer,it will look athttps://example.com/help/Foo/en.lproj/index.html.

Set this to toNone for no remote content.

applehelp_index_anchors¶

Type:

bool

Default:

False

Tell the help indexer to index anchors in the generated HTML.This can be useful for jumping to a particular topicusing theAHLookupAnchor functionor theopenHelpAnchor:inBook: method in your code.It also allows you to usehelp:anchor URLs;see the Apple documentation for more information on this topic.

applehelp_min_term_length¶

Type:

str

Default:

None

Controls the minimum term length for the help indexer.IfNone, use the default length.

applehelp_stopwords¶

Type:

str

Default:

The value oflanguage

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

• German (de)

• English (en)

• Spanish (es)

• French (fr)

• Hungarian (hu)

• Italian (it)

• Swedish (sv)

applehelp_locale¶

Type:

str

Default:

The value oflanguage

Specifies the locale to generate help for.This is used to determine the name of the.lproj directoryinside the Help Book’sResources,and is passed to the help indexer.

applehelp_title¶

Type:

str

Default:

'projectHelp'

Specifies the help book title.

applehelp_codesign_identity¶

Type:

str

Default:

The value ofCODE_SIGN_IDENTITY

Specifies the identity to use for code signing.UseNone if code signing is not to be performed.

Defaults to the value of theCODE_SIGN_IDENTITYenvironment variable, which is set by Xcode for script build phases,orNone if that variable is not set.

applehelp_codesign_flags¶

Type:

list[str]

Default:

The value ofOTHER_CODE_SIGN_FLAGS

Alist of additional arguments to pass tocodesign whensigning the help book.

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

applehelp_codesign_path¶

Type:

str

Default:

'/usr/bin/codesign'

The path to thecodesign program.

applehelp_indexer_path¶

Type:

str

Default:

'/usr/bin/hiutil'

The path to thehiutil program.

applehelp_disable_external_tools¶

Type:

bool

Default:

False

Do 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-macOS platformand then complete the final steps on a Mac for some reason.

Options for EPUB output¶

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

epub_basename¶

Type:

str

Default:

The value ofproject

The basename for the EPUB file.

epub_theme¶

Type:

str

Default:

'epub'

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

epub_theme_options¶

Type:

dict[str,Any]

Default:

{}

A dictionary of options that influence thelook and feel of the selected theme.These are theme-specific.The options understood by thebuiltin themes are describedhere.

Added in version 1.2.

epub_title¶

Type:

str

Default:

The value ofproject

The title of the document.

Changed in version 2.0:It defaults to theproject option(previouslyhtml_title).

epub_description¶

Type:

str

Default:

'unknown'

The description of the document.

Added in version 1.4.

Changed in version 1.5:Renamed fromepub3_description

epub_author¶

Type:

str

Default:

The value ofauthor

The author of the document.This is put in the Dublin Core metadata.

epub_contributor¶

Type:

str

Default:

'unknown'

The name of a person, organisation, etc. that played a secondary rolein the creation of the content of an EPUB Publication.

Added in version 1.4.

Changed in version 1.5:Renamed fromepub3_contributor

epub_language¶

Type:

str

Default:

The value oflanguage

The language of the document.This is put in the Dublin Core metadata.

epub_publisher¶

Type:

str

Default:

The value ofauthor

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

epub_copyright¶

Type:

str

Default:

The value ofcopyright

The copyright of the document.Seecopyright for permitted formats.

epub_identifier¶

Type:

str

Default:

'unknown'

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.

epub_scheme¶

Type:

str

Default:

'unknown'

The publication scheme for theepub_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.

epub_uid¶

Type:

str

Default:

'unknown'

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

epub_cover¶

Type:

tuple[str,str]

Default:

()

The cover page information.This is a tuple containing the filenames of the cover imageand the html template.The rendered html cover page is inserted as the first itemin the spine incontent.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=()

Added in version 1.1.

epub_css_files¶

Type:

Sequence[str|tuple[str,dict[str,str]]]

Default:

[]

A list of CSS files.The entry must be afilename stringor a tuple containing thefilename string and theattributes dictionary.Thefilename must be relative to thehtml_static_path,or a full URI with scheme like'https://example.org/style.css'.Theattributes dictionary is used for the<link> tag’s attributes.For more information, seehtml_css_files.

Added in version 1.8.

epub_guide¶

Type:

Sequence[tuple[str,str,str]]

Default:

()

Meta data for the guide element ofcontent.opf.This is a sequence of tuples containingthetype, theuri and thetitle of the optional guide information.Seethe OPF documentation for details.If possible, default entries for thecover andtoc typesare automatically inserted.However, the types can be explicitly overwrittenif the default entries are not appropriate.

Example:

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

The default value is().

epub_pre_files¶

Type:

Sequence[tuple[str,str]]

Default:

()

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

Example:

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

epub_post_files¶

Type:

Sequence[tuple[str,str]]

Default:

()

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

Example:

epub_post_files=[('appendix.xhtml','Appendix'),]

epub_exclude_files¶

Type:

Sequence[str]

Default:

[]

A sequence of files that are generated/copied in the build directorybut should not be included in the EPUB file.

epub_tocdepth¶

Type:

int

Default:

3

The depth of the table of contents in the filetoc.ncx.It should be an integer greater than zero.

Tip

A deeply nested table of contents may be difficult to navigate.

epub_tocdup¶

Type:

bool

Default:

True

This flag determines if a ToC entry is inserted againat 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.

epub_tocscope¶

Type:

'default'|'includehidden'

Default:

'default'

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

'default'

Include all ToC entries that are not hidden

'includehidden'

Include all ToC entries

Added in version 1.2.

epub_fix_images¶

Type:

bool

Default:

False

Try and fix image formats that are not supported by some EPUB readers.At the moment palette images with a small colour table are upgraded.This is disabled by default because theautomatic conversion may lose information.You need the Python Image Library (Pillow) installed to use this option.

Added in version 1.2.

epub_max_image_width¶

Type:

int

Default:

0

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

Added in version 1.2.

epub_show_urls¶

Type:

'footnote'|'no'|'inline'

Default:

'footnote'

Control how to display URL addresses.This is very useful for readers that have no other meansto display the linked URL.The setting can have the following values:

'inline'

Display URLs inline in parentheses.

'footnote'

Display URLs in footnotes.

'no'

Do not display URLs.

The display of inline URLs can be customised by adding CSS rulesfor the classlink-target.

Added in version 1.2.

epub_use_index¶

Type:

bool

Default:

The value ofhtml_use_index

Add an index to the EPUB document.

Added in version 1.2.

epub_writing_mode¶

Type:

'horizontal'|'vertical'

Default:

'horizontal'

It specifies writing direction.It can accept'horizontal' and'vertical'

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

Options for LaTeX output¶

These options influence LaTeX output.

latex_engine¶

Type:

'pdflatex'|'xelatex'|'lualatex'|'platex'|'uplatex'

Default:

'pdflatex'

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

• 'pdflatex' – PDFLaTeX (default)

• 'xelatex' – XeLaTeX(default iflanguage is one ofel,zh_CN, orzh_TW)

• 'lualatex' – LuaLaTeX

• 'platex' – pLaTeX

• 'uplatex' – upLaTeX(default iflanguage is'ja')

Important

'pdflatex'‘s support for Unicode characters is limited.If your project uses Unicode characters,setting the engine to'xelatex' or'lualatex'and making sure to use an OpenType font with wide-enough glyph coverageis often easier than trying to make'pdflatex' workwith the extra Unicode characters.Since Sphinx 2.0, the default typeface is GNU FreeFont,which has good coverage of Latin, Cyrillic, and Greek glyphs.

Note

Sphinx 2.0 adds support for occasional Cyrillic and Greek letters orwords in documents using a Latin language and'pdflatex'. To enablethis, the'fontenc' key oflatex_elements must be used appropriately.

Note

Contrarily toMathJaX math rendering in HTML output,LaTeX requires some extra configuration to support Unicode literals inmath:the only comprehensive solution (as far as we know) is touse'xelatex' or'lualatex'and to addr'\usepackage{unicode-math}'(e.g. via the'preamble' key oflatex_elements).You may preferr'\usepackage[math-style=literal]{unicode-math}'to keep a Unicode literal such asα (U+03B1) as-is in output,rather than being rendered as\(\alpha\).

Changed in version 2.1.0:Use'xelatex' (and LaTeX packagexeCJK)by default for Chinese documents.

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

Changed in version 2.3:Add'uplatex' support.

Changed in version 4.0:Use'uplatex' by default for Japanese documents.

latex_documents¶

Type:

Sequence[tuple[str,str,str,str,str,bool]]

Default:

The default LaTeX documents

This value determines how to group the document treeinto LaTeX source files.It must be a list of tuples(startdocname,targetname,title,author,theme,toctree_only),where the items are:

startdocname

String that specifies thedocument name ofthe LaTeX file’s master document.All documents referenced by thestartdoc document inToC trees will be included in the LaTeX file.(If you want to use the default master document for your LaTeX build,provide yourmaster_doc here.)

targetname

File name of the LaTeX file in the output directory.

title

LaTeX document title.Can be empty to use the title of thestartdoc document.This is inserted as LaTeX markup,so special characters like a backslash or ampersandmust be represented by the proper LaTeX commandsif they are to be inserted literally.

author

Author for the LaTeX document.The same LaTeX markup caveat as fortitle applies.Use\\and to separate multiple authors, as in:'John\\andSarah'(backslashes must be Python-escaped to reach LaTeX).

theme

LaTeX theme.Seelatex_theme.

toctree_only

Must beTrue orFalse.If True, thestartdoc document itself is not included in the output,only the documents referenced by it via ToC trees.With this option, you can put extra stuff in the master documentthat shows up in the HTML, but not the LaTeX output.

Added in version 0.3:The 6th itemtoctree_only.Tuples with 5 items are still accepted.

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

latex_logo¶

Type:

str

Default:

''

If given, this must be the name of an image file(path relative to theconfiguration directory)that is the logo of the documentation.It is placed at the top of the title page.

latex_toplevel_sectioning¶

Type:

'part'|'chapter'|'section'

Default:

None

This value determines the topmost sectioning unit. The default setting is'section' iflatex_theme is'howto', and'chapter'if it is'manual'. The alternative in both cases is to specify'part', which means that LaTeX document will use the\partcommand.

In that case the numbering of sectioning units one level deep gets off-syncwith HTML numbering, as by default LaTeX does not reset\chapter numbering (or\section for'howto'theme) when encountering\part command.

Added in version 1.4.

latex_appendices¶

Type:

Sequence[str]

Default:

()

A list of document names to append as an appendix to all manuals.This is ignored iflatex_theme is set to'howto'.

latex_domain_indices¶

Type:

bool|Sequence[str]

Default:

True

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

This value can be a Boolean 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'.

Example:

latex_domain_indices={'py-modindex',}

Added in version 1.0.

Changed in version 7.4:Permit and prefer a set type.

latex_show_pagerefs¶

Type:

bool

Default:

False

Add page references after internal references.This is very useful for printed copies of the manual.

Added in version 1.0.

latex_show_urls¶

Type:

'no'|'footnote'|'inline'

Default:

'no'

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

'no'

Do not display URLs

'footnote'

Display URLs in footnotes

'inline'

Display URLs inline in parentheses

Added in version 1.0.

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

latex_use_latex_multicolumn¶

Type:

bool

Default:

False

Use standard LaTeX’s\multicolumn for merged cells in tables.

False

Sphinx’s own macros are used for merged cells from grid tables.They allow general contents (literal blocks, lists, blockquotes, …)but may have problems if thetabularcolumns directivewas used to inject LaTeX mark-up of the type>{..},<{..},@{..} as column specification.

True

Use LaTeX’s standard\multicolumn;this is incompatible with literal blocks in horizontally merged cells,and also with multiple paragraphs in such cellsif the table is rendered usingtabulary.

Added in version 1.6.

latex_table_style¶

Type:

list[str]

Default:

['booktabs','colorrows']

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

'booktabs'

No vertical lines, and only 2 or 3 horizontal lines(the latter if there is a header),using thebooktabs package.

'borderless'

No lines whatsoever.

'colorrows'

The table rows are rendered with alternating background colours.The interface to customise them is viadedicated keys ofThe sphinxsetup configuration setting.

Important

With the'colorrows' style,the\rowcolors LaTeX command becomes a no-op(this command has limitations and has never correctlysupported all types of tables Sphinx produces in LaTeX).Please use thelatex table color configuration keys instead.

To customise the styles for a table,use the:class: option if the table is defined using a directive,or otherwise insert arst-class directive before the table(cf.Tables).

Currently recognised classes arebooktabs,borderless,standard,colorrows,nocolorrows.The latter two can be combined with any of the first three.Thestandard class produces tables withboth horizontal and vertical lines(as had been the default prior to Sphinx 6.0.0).

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

Note

• It is hard-coded in LaTeX that a single cell will obey the row coloureven if there is a column colour set via\columncolorfrom a column specification (seetabularcolumns).Sphinx provides\sphinxnorowcolor which can be usedin a table column specification like this:

  >{\columncolor{blue}\sphinxnorowcolor}

• Sphinx also provides\sphinxcolorblend,which however requires thexcolor package.Here is an example:

  >{\sphinxcolorblend{!95!red}}

  It means that in this column,the row colours will be slightly tinted by red;refer toxcolor documentation for more on the syntax of its\blendcolors command(a\blendcolors in place of\sphinxcolorblendwould modify colours of the cellcontents,not of the cellbackground colour panel…).You can find an example of usage in theDeprecated APIssection of this document in PDF format.

  Hint

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

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

• It is possible for a simple cell to set a custom colour via theraw directive andthe\cellcolor LaTeX command usedanywhere in the cell contents.This currently is without effect in a merged cell, whatever its kind.

Hint

In a document not using'booktabs' globally,it is possible to style an individual table via thebooktabs class,but it will be necessary to addr'\usepackage{booktabs}'to the LaTeX preamble.

On the other hand one can usecolorrows class for individual tableswith no extra package (as Sphinx since 5.3.0 always loadscolortbl).

Added in version 5.3.0.

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

latex_use_xindy¶

Type:

bool

Default:

Trueiflatex_enginein{'xelatex','lualatex'}elseFalse

UseXindy to prepare the index of general terms.By default, the LaTeX builder usesmakeindexfor preparing the index of general terms .UsingXindy means that words with UTF-8 characters will beordered correctly for thelanguage.

• This option is ignored iflatex_engine is'platex'(Japanese documents;mendex replacesmakeindex then).

• The default isTruefor'xelatex' or'lualatex' asmakeindex creates.ind files containing invalid bytesfor the UTF-8 encoding if any indexed term starts witha non-ASCII character.With'lualatex' this then breaks the PDF build.

• The default isFalse for'pdflatex',butTrue is recommended for non-English documents as soonas some indexed terms use non-ASCII characters from the language script.Attempting to index a term whose first character is non-ASCIIwill break the build, iflatex_use_xindy is left to itsdefaultFalse.

Sphinx adds some dedicated support to thexindy base distributionfor using'pdflatex' engine with Cyrillic scripts.With both'pdflatex' and Unicode engines,Cyrillic documents handle the indexing of Latin names correctly,even those having diacritics.

Added in version 1.8.

latex_elements¶

Type:

dict[str,str]

Default:

{}

Added in version 0.5.

See the full documentation for latex_elements.

latex_docclass¶

Type:

dict[str,str]

Default:

{}

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

Added in version 1.0.

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

latex_additional_files¶

Type:

Sequence[str]

Default:

()

A list of file names, relative to theconfiguration directory,to copy to the build directory when building LaTeX output.This is useful to copy files that Sphinx doesn’t copy automatically,or to overwrite Sphinx LaTeX support files with custom versions.Image files that are referenced in source files (e.g. via..image::)are copied automatically and should not be listed there.

Attention

Filenames with the.tex extension will be automaticallyhanded over to the PDF build process triggered bysphinx-build-Mlatexpdfor bymake latexpdf.If the file was added only to be\input{}from a modified preamble,you must add a further suffix such as.txt to the filenameand adjust the\input{} macro accordingly.

Added in version 0.6.

Changed in version 1.2:This overrides the files provided from Sphinx such assphinx.sty.

latex_theme¶

Type:

str

Default:

'manual'

The “theme” that the LaTeX output should use.It is a collection of settings for LaTeX output(e.g. document class, top level sectioning unit and so on).

The bundled first-party LaTeX themes aremanual andhowto:

manual

A LaTeX theme for writing a manual.It imports thereport document class(Japanese documents usejsbook).

howto

A LaTeX theme for writing an article.It imports thearticle document class(Japanese documents usejreport).latex_appendices is only available for this theme.

Added in version 3.0.

latex_theme_options¶

Type:

dict[str,Any]

Default:

{}

A dictionary of options that influence thelook and feel of the selected theme.These are theme-specific.

Added in version 3.1.

latex_theme_path¶

Type:

list[str]

Default:

[]

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

Added in version 3.0.

Options for text output¶

These options influence text output.

text_add_secnumbers¶

Type:

bool

Default:

True

Include section numbers in text output.

Added in version 1.7.

text_newlines¶

Type:

'unix'|'windows'|'native'

Default:

'unix'

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

'unix'

Use Unix-style line endings (\n).

'windows'

Use Windows-style line endings (\r\n).

'native'

Use the line ending style of the platform the documentation is built on.

Added in version 1.1.

text_secnumber_suffix¶

Type:

str

Default:

'. '

Suffix for section numbers in text output.Set to' ' to suppress the final dot on section numbers.

Added in version 1.7.

text_sectionchars¶

Type:

str

Default:

'*=-~"+`'

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

Added in version 1.1.

Options for manual page output¶

These options influence manual page output.

man_pages¶

Type:

Sequence[tuple[str,str,str,str,str]]

Default:

The default manual pages

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

startdocname

String that specifies thedocument name ofthe manual page’s master document.All documents referenced by thestartdoc document inToC trees will be included in the manual page.(If you want to use the default master document for your manual pages build,provide yourmaster_doc here.)

name

Name of the manual page.This should be a short string without spaces or special characters.It is used to determine the file name as well as thename of the manual page (in the NAME section).

description

Description of the manual page.This is used in the NAME section.Can be an empty string if you do not want toautomatically generate the NAME section.

authors

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

section

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

Added in version 1.0.

man_show_urls¶

Type:

bool

Default:

False

Add URL addresses after links.

Added in version 1.1.

man_make_section_directory¶

Type:

bool

Default:

True

Make a section directory on build man page.

Added in version 3.3.

Changed in version 4.0:The default is nowFalse (previouslyTrue).

Changed in version 4.0.2:Revert the change in the default.

Options for Texinfo output¶

These options influence Texinfo output.

texinfo_documents¶

Type:

Sequence[tuple[str,str,str,str,str,str,str,bool]]

Default:

The default Texinfo documents

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

startdocname

String that specifies thedocument name ofthe Texinfo file’s master document.All documents referenced by thestartdoc document inToC trees will be included in the Texinfo file.(If you want to use the default master document for your Texinfo build,provide yourmaster_doc here.)

targetname

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

title

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

author

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

dir_entry

The name that will appear in the top-levelDIR menu file.

description

Descriptive text to appear in the top-levelDIR menu file.

category

Specifies the section which this entry will appear in the top-levelDIR menu file.

toctree_only

Must beTrue orFalse.If True, thestartdoc document itself is not included in the output,only the documents referenced by it via ToC trees.With this option, you can put extra stuff in the master documentthat shows up in the HTML, but not the Texinfo output.

Added in version 1.1.

texinfo_appendices¶

Type:

Sequence[str]

Default:

[]

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

Added in version 1.1.

texinfo_cross_references¶

Type:

bool

Default:

True

Generate inline references in a document.Disabling inline references can make an info file more readablewith a stand-alone reader (info).

Added in version 4.4.

texinfo_domain_indices¶

Type:

bool|Sequence[str]

Default:

True

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

This value can be a Boolean 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'.

Example:

texinfo_domain_indices={'py-modindex',}

Added in version 1.1.

Changed in version 7.4:Permit and prefer a set type.

texinfo_elements¶

Type:

dict[str,Any]

Default:

{}

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

• Keys that you may want to override include:

  'paragraphindent'

  Number of spaces to indent the first line of each paragraph,default2.Specify0 for no indentation.

  'exampleindent'

  Number of spaces to indent the lines for examples or literal blocks,default4.Specify0 for no indentation.

  'preamble'

  Texinfo markup inserted near the beginning of the file.

  'copying'

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

• Keys that are set by other optionsand therefore should not be overridden are'author','body','date','direntry''filename','project','release', and'title'.

Added in version 1.1.

texinfo_no_detailmenu¶

Type:

bool

Default:

False

Do not generate a@detailmenu in the “Top” node’s menucontaining entries for each sub-node in the document.

Added in version 1.2.

texinfo_show_urls¶

Type:

'footnote'|'no'|'inline'

Default:

'footnote'

Control how to display URL addresses.The setting can have the following values:

'footnote'

Display URLs in footnotes.

'no'

Do not display URLs.

'inline'

Display URLs inline in parentheses.

Added in version 1.1.

Options for QtHelp output¶

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

qthelp_basename¶

Type:

str

Default:

The value ofproject

The basename for the qthelp file.

qthelp_namespace¶

Type:

str

Default:

'org.sphinx.{project_name}.{project_version}'

The namespace for the qthelp file.