diff --git a/CHANGES.rst b/CHANGES.rst index 21b7a557725..67b363757f3 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -60,6 +60,14 @@ Features added Patch by Tim Hoffmann. * #12536: Add the :rst:dir:`confval` directive. Patch by Adam Turner. +* #12537: :confval:`c_id_attributes`, :confval:`c_paren_attributes`, + :confval:`cpp_id_attributes`, and :confval:`cpp_paren_attributes` + can now be a tuple of strings. + :confval:`c_extra_keywords`, :confval:`gettext_additional_targets`, + :confval:`html_domain_indices`, :confval:`latex_domain_indices`, + and :confval:`texinfo_domain_indices`, + can now be a set of strings. + Patch by Adam Turner. Bugs fixed ---------- @@ -78,9 +86,8 @@ Bugs fixed * #12380: LaTeX: Footnote mark sometimes indicates ``Page N`` where ``N`` is the current page number and the footnote does appear on that same page. Patch by Jean-François B. -* #12416: :confval:`root_doc` is synchronized with :confval:`master_doc` - so that if either of the two values is modified, the other reflects that - modification. It is still recommended to use :confval:`root_doc`. +* #12416: Ensure that configuration setting aliases are always synchronised + when one value or the other is modified. Patch by Bénédikt Tran. * #12220: Fix loading custom template translations for ``en`` locale. Patch by Nicolas Peugnet. @@ -3828,7 +3835,7 @@ Deprecated * The arguments of ``Epub3Builder.build_navigation_doc()`` * The config variables - - :confval:`html_experimental_html5_writer` + - :confval:`!html_experimental_html5_writer` * The ``encoding`` argument of ``autodoc.Documenter.get_doc()``, ``autodoc.DocstringSignatureMixin.get_doc()``, @@ -3944,7 +3951,7 @@ Features added * #4611: epub: Show warning for duplicated ToC entries * #1851: Allow to omit an argument for :rst:dir:`code-block` directive. If omitted, it follows :rst:dir:`highlight` or :confval:`highlight_language` -* #4587: html: Add :confval:`html4_writer` to use old HTML4 writer +* #4587: html: Add :confval:`!html4_writer` to use old HTML4 writer * #6016: HTML search: A placeholder for the search summary prevents search result links from changing their position when the search terminates. This makes navigating search results easier. @@ -4264,7 +4271,7 @@ Deprecated 1.8.0b1 -* :confval:`source_parsers` is deprecated +* :confval:`!source_parsers` is deprecated * :confval:`autodoc_default_flags` is deprecated * quickstart: ``--epub`` option becomes default, so it is deprecated * Drop function based directive support. For now, Sphinx only supports class @@ -6404,7 +6411,7 @@ Features added -------------- * #1873, #1876, #2278: Add ``page_source_suffix`` html context variable. This - should be introduced with :confval:`source_parsers` feature. Thanks for Eric + should be introduced with :confval:`!source_parsers` feature. Thanks for Eric Holscher. @@ -6471,7 +6478,7 @@ Bugs fixed * #2186: Fix LaTeX output of \mathbb in math * #1480, #2188: LaTeX: Support math in section titles * #2071: Fix same footnote in more than two section titles => LaTeX/PDF Bug -* #2040: Fix UnicodeDecodeError in sphinx-apidoc when author contains non-ascii +* #2040: Fix UnicodeDecodeError in sphinx-apidoc when author contains non-ASCII characters * #2193: Fix shutil.SameFileError if source directory and destination directory are same @@ -6646,7 +6653,7 @@ Features added * The :confval:`source_suffix` config value can now be a list of multiple suffixes. * Add the ability to specify source parsers by source suffix with the - :confval:`source_parsers` config value. + :confval:`!source_parsers` config value. * #1675: A new builder, AppleHelpBuilder, has been added that builds Apple Help Books. diff --git a/doc/_static/conf.py.txt b/doc/_static/conf.py.txt deleted file mode 100644 index c5e75e05669..00000000000 --- a/doc/_static/conf.py.txt +++ /dev/null @@ -1,346 +0,0 @@ -# test documentation build configuration file, created by -# sphinx-quickstart on Sun Jun 26 00:00:43 2016. -# -# This file is executed through importlib.import_module with -# the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' - -# The encoding of source files. -# -# source_encoding = 'utf-8-sig' - -# The master toctree document. -root_doc = 'index' - -# General information about the project. -project = 'test' -copyright = '2016, test' -author = 'test' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = 'test' -# The full version, including alpha/beta/rc tags. -release = 'test' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -# -# today = '' -# -# Else, today_fmt is used as the format for a strftime call. -# -# today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# These patterns also affect html_static_path and html_extra_path -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] - -# The reST default role (used for this markup: `text`) to use for all -# documents. -# -# default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -# -# add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -# -# add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -# -# show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -# modindex_common_prefix = [] - -# If true, keep warnings as "system message" paragraphs in the built documents. -# keep_warnings = False - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False - - -# -- Options for HTML output ---------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = 'alabaster' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -# html_theme_path = [] - -# The name for this set of Sphinx documents. -# " v documentation" by default. -# -# html_title = 'test vtest' - -# A shorter title for the navigation bar. Default is the same as html_title. -# -# html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -# -# html_logo = None - -# The name of an image file (relative to this directory) to use as a favicon of -# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -# -# html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -# -# html_extra_path = [] - -# If not None, a 'Last updated on:' timestamp is inserted at every page -# bottom, using the given strftime format. -# The empty string is equivalent to '%b %d, %Y'. -# -# html_last_updated_fmt = None - -# Custom sidebar templates, maps document names to template names. -# -# html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -# -# html_additional_pages = {} - -# If false, no module index is generated. -# -# html_domain_indices = True - -# If false, no index is generated. -# -# html_use_index = True - -# If true, the index is split into individual pages for each letter. -# -# html_split_index = False - -# If true, links to the reST sources are added to the pages. -# -# html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -# -# html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -# -# html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -# -# html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -# html_file_suffix = None - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh' -# -# html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# 'ja' uses this config value. -# 'zh' user can custom change `jieba` dictionary path. -# -# html_search_options = {'type': 'default'} - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -# -# html_search_scorer = 'scorer.js' - -# Output file base name for HTML help builder. -htmlhelp_basename = 'testdoc' - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (root_doc, 'test.tex', 'test Documentation', - 'test', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -# -# latex_logo = None - -# If true, show page references after internal links. -# -# latex_show_pagerefs = False - -# If true, show URL addresses after external links. -# -# latex_show_urls = False - -# Documents to append as an appendix to all manuals. -# -# latex_appendices = [] - -# If false, no module index is generated. -# -# latex_domain_indices = True - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (root_doc, 'test', 'test Documentation', - [author], 1) -] - -# If true, show URL addresses after external links. -# -# man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (root_doc, 'test', 'test Documentation', - author, 'test', 'One line description of project.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -# -# texinfo_appendices = [] - -# If false, no module index is generated. -# -# texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -# -# texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -# -# texinfo_no_detailmenu = False - -# If false, do not generate in manual @ref nodes. -# -# texinfo_cross_references = False - -# -- A random example ----------------------------------------------------- - -import sys, os -sys.path.insert(0, os.path.abspath('.')) -exclude_patterns = ['zzz'] - -numfig = True -#language = 'ja' - -extensions.append('sphinx.ext.todo') -extensions.append('sphinx.ext.autodoc') -#extensions.append('sphinx.ext.autosummary') -extensions.append('sphinx.ext.intersphinx') -extensions.append('sphinx.ext.mathjax') -extensions.append('sphinx.ext.viewcode') -extensions.append('sphinx.ext.graphviz') - - -autosummary_generate = True -html_theme = 'default' -#source_suffix = ['.rst', '.txt'] diff --git a/doc/conf.py b/doc/conf.py index 65142491fc8..893d4862666 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -5,7 +5,7 @@ import re import time -import sphinx +from sphinx import __display_version__ os.environ['SPHINX_AUTODOC_RELOAD_MODULES'] = '1' @@ -27,8 +27,7 @@ project = 'Sphinx' copyright = f'2007-{time.strftime("%Y")}, the Sphinx developers' -version = sphinx.__display_version__ -release = version +release = version = __display_version__ show_authors = True nitpicky = True show_warning_types = True @@ -156,7 +155,7 @@ 'Sphinx', 'The Sphinx documentation builder.', 'Documentation tools', - 1, + True, ), ] @@ -241,12 +240,12 @@ from sphinx import addnodes # NoQA: E402 from sphinx.application import Sphinx # NoQA: E402, TCH001 -event_sig_re = re.compile(r'([a-zA-Z-]+)\s*\((.*)\)') +_event_sig_re = re.compile(r'([a-zA-Z-]+)\s*\((.*)\)') def parse_event(env, sig, signode): - m = event_sig_re.match(sig) - if not m: + m = _event_sig_re.match(sig) + if m is None: signode += addnodes.desc_name(sig, sig) return sig name, args = m.groups() @@ -330,5 +329,9 @@ def setup(app: Sphinx) -> None: app.connect('build-finished', build_redirects) fdesc = GroupedField('parameter', label='Parameters', names=['param'], can_collapse=True) app.add_object_type( - 'event', 'event', 'pair: %s; event', parse_event, doc_field_types=[fdesc] + 'event', + 'event', + 'pair: %s; event', + parse_event, + doc_field_types=[fdesc], ) diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst index 1476ce8473e..7504be35bba 100644 --- a/doc/extdev/deprecated.rst +++ b/doc/extdev/deprecated.rst @@ -1769,7 +1769,7 @@ The following is a list of deprecated interfaces. - 3.0 - ``warning()`` - * - :confval:`source_parsers` + * - :confval:`!source_parsers` - 1.8 - 3.0 - :meth:`~sphinx.application.Sphinx.add_source_parser()` diff --git a/doc/glossary.rst b/doc/glossary.rst index 85e0057a84f..27326768d5a 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -26,9 +26,9 @@ Glossary Sphinx and custom extensions can add their own. The basic directive syntax looks like this: - .. sourcecode:: rst + .. code-block:: rst - .. directivename:: argument ... + .. directive-name:: argument ... :option: value Content of the directive. diff --git a/doc/latex.rst b/doc/latex.rst index a4c8ede801f..7e35fddd212 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -758,7 +758,7 @@ Do not use quotes to enclose values, whether numerical or strings. wrapped. If ``true``, line breaks may happen at spaces (the last space before the - line break will be rendered using a special symbol), and at ascii + line break will be rendered using a special symbol), and at ASCII punctuation characters (i.e. not at letters or digits). Whenever a long string has no break points, it is moved to next line. If its length is longer than the line width it will overflow. @@ -1828,7 +1828,7 @@ Miscellany \newenvironment{sphinxclassred}{\color{red}}{} - Currently the class names must contain only ascii characters and avoid + Currently the class names must contain only ASCII characters and avoid characters special to LaTeX such as ``\``. .. versionadded:: 4.1.0 diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst index 295f95011b2..ac2e7caf26e 100644 --- a/doc/man/sphinx-build.rst +++ b/doc/man/sphinx-build.rst @@ -102,8 +102,10 @@ Options .. option:: -t tag, --tag tag - Define the tag *tag*. This is relevant for :rst:dir:`only` directives that - only include their content if this tag is set. + Define the tag *tag*. + This is relevant for :rst:dir:`only` directives that + include their content only if certain tags are set. + See :ref:`including content based on tags ` for further detail. .. versionadded:: 0.6 diff --git a/doc/usage/advanced/websupport/quickstart.rst b/doc/usage/advanced/websupport/quickstart.rst index e7c2b5146dd..b75c617847d 100644 --- a/doc/usage/advanced/websupport/quickstart.rst +++ b/doc/usage/advanced/websupport/quickstart.rst @@ -21,7 +21,7 @@ things are in a document. To do this you will need to create an instance of the support.build() This will read reStructuredText sources from ``srcdir`` and place the necessary -data in ``builddir``. The ``builddir`` will contain two sub-directories: one +data in ``builddir``. The ``builddir`` will contain two subdirectories: one named "data" that contains all the data needed to display documents, search through documents, and add comments to documents. The other directory will be called "static" and contains static files that should be served from "/static". diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index b283c2fb7d0..614db1a336a 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -1,5 +1,3 @@ -.. highlight:: python - .. _build-config: ============= @@ -9,10 +7,23 @@ Configuration .. module:: conf :synopsis: Build configuration file. +.. role:: code-c(code) + :language: C +.. role:: code-cpp(code) + :language: C++ +.. role:: code-js(code) + :language: JavaScript +.. role:: code-py(code) + :language: Python +.. role:: code-rst(code) + :language: reStructuredText +.. role:: code-tex(code) + :language: LaTeX + The :term:`configuration directory` must contain a file named :file:`conf.py`. This file (containing Python code) is called the "build configuration file" -and contains (almost) all configuration needed to customize Sphinx input -and output behavior. +and contains (almost) all configuration needed to customise Sphinx input +and output behaviour. An optional file `docutils.conf`_ can be added to the configuration directory to adjust `Docutils`_ configuration if not otherwise overridden or @@ -21,1051 +32,1385 @@ set by Sphinx. .. _`docutils`: https://docutils.sourceforge.io/ .. _`docutils.conf`: https://docutils.sourceforge.io/docs/user/config.html -The configuration file is executed as Python code at build time (using -:func:`importlib.import_module`, and with the current directory set to its -containing directory), and therefore can execute arbitrarily complex code. -Sphinx then reads simple names from the file's namespace as its configuration. - Important points to note: -* If not otherwise documented, values must be strings, and their default is the - empty string. - -* The term "fully-qualified name" refers to a string that names an importable - Python object inside a module; for example, the FQN - ``"sphinx.builders.Builder"`` means the ``Builder`` class in the - ``sphinx.builders`` module. - -* Remember that document names use ``/`` as the path separator and don't - contain the file name extension. - -* Since :file:`conf.py` is read as a Python file, the usual rules apply for - encodings and Unicode support. - -* The contents of the config namespace are pickled (so that Sphinx can find out - when configuration changes), so it may not contain unpickleable values -- - delete them from the namespace with ``del`` if appropriate. Modules are - removed automatically, so you don't need to ``del`` your imports after use. - - .. _conf-tags: +* If not otherwise documented, values must be strings, + and their default is the empty string. -* There is a special object named ``tags`` available in the config file. - It can be used to query and change the tags (see :ref:`tags`). Use - ``'tag' in tags`` 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 ``'tag' in tags``. - Note that the current builder tag is not available in ``conf.py``, as it is - created *after* the builder is initialized. +* The term "fully-qualified name" (FQN) refers to a string that names an importable + Python object inside a module; for example, the fully-qualified name + :code-py:`"sphinx.builders.Builder"` means the :code-py:`Builder` class in the + :code-py:`sphinx.builders` module. +* Document names use ``/`` as the path separator + and do not contain the file name extension. -Project information -------------------- - -.. confval:: project +.. _glob-style patterns: - The documented project's name. +* Where glob-style patterns are permitted, + you can use the standard shell constructs + (``*``, ``?``, ``[...]``, and ``[!...]``) + with the feature that none of these will match slashes (``/``). + A double star ``**`` can be used to match any sequence of characters + *including* slashes. -.. confval:: author +.. tip:: - The author name(s) of the document. The default value is ``'unknown'``. + The configuration file is executed as Python code at build time + (using :func:`importlib.import_module`, with the current directory set + to the :term:`configuration directory`), + and therefore can execute arbitrarily complex code. -.. confval:: copyright + Sphinx then reads simple names from the file's namespace as its configuration. + In general, configuration values should be simple strings, numbers, or + lists or dictionaries of simple values. - A copyright statement in the style ``'2008, Author Name'``. + 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 deleting imported modules is not needed. - .. versionchanged:: 7.1 - The value may now be a sequence of copyright statements in the above form, - which will be displayed each to their own line. -.. confval:: project_copyright +.. _conf-tags: - An alias of :confval:`copyright`. +Project tags +============ - .. versionadded:: 3.5 +There is a special object named ``tags`` available in the config file, +which exposes the :ref:`project tags `. +Tags are defined either via the +:option:`--tag ` command-line option +or :code-py:`tags.add('tag')`. +Note that the builder's name and format tags are not available in :file:`conf.py`. -.. confval:: version +It can be used to query and change the defined tags as follows: - The major project version, used as the replacement for ``|version|``. For - example, for the Python documentation, this may be something like ``2.6``. +* To query whether a tag is set, use :code-py:`'tag' in tags`. +* To add a tag, use :code-py:`tags.add('tag')`. +* To remove a tag, use :code-py:`tags.remove('tag')`. -.. confval:: release +Project information +=================== - 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``. +.. confval:: project + :type: :code-py:`str` + :default: :code-py:`'Project name not set'` - If you don't need the separation provided between :confval:`version` and - :confval:`release`, just set them both to the same value. + The documented project's name. + Example: + .. code-block:: python -General configuration ---------------------- + project = 'Thermidor' -.. confval:: extensions +.. confval:: author + :type: :code-py:`str` + :default: :code-py:`'Author name not set'` - A list of strings that are module names of :doc:`extensions - `. These can be extensions coming with Sphinx (named - ``sphinx.ext.*``) or custom ones. + The project's author(s). + Example: - Note that you can extend :data:`sys.path` within the conf file if your - extensions live in another directory -- but make sure you use absolute paths. - If your extension path is relative to the :term:`configuration directory`, - use :func:`os.path.abspath` like so:: + .. code-block:: python - import sys, os + author = 'Joe Bloggs' - sys.path.append(os.path.abspath('sphinxext')) +.. confval:: copyright + project_copyright + :type: :code-py:`str | Sequence[str]` + :default: :code-py:`''` - extensions = ['extname'] + A copyright statement. + Permitted styles are as follows, where 'YYYY' represents a four-digit year. - That way, you can load an extension called ``extname`` from the subdirectory - ``sphinxext``. + * :code-py:`copyright = 'YYYY'` + * :code-py:`copyright = 'YYYY, Author Name'` + * :code-py:`copyright = 'YYYY Author Name'` + * :code-py:`copyright = 'YYYY-YYYY, Author Name'` + * :code-py:`copyright = 'YYYY-YYYY Author Name'` - The configuration file itself can be an extension; for that, you only need - to provide a :func:`setup` function in it. + .. versionadded:: 3.5 + The :code-py:`project_copyright` alias. -.. confval:: source_suffix + .. versionchanged:: 7.1 + The value may now be a sequence of copyright statements in the above form, + which will be displayed each to their own line. - 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:: +.. confval:: version + :type: :code-py:`str` + :default: :code-py:`''` - source_suffix = { - '.rst': 'restructuredtext', - '.txt': 'restructuredtext', - '.md': 'markdown', - } + The major project version, used as the replacement for the :code-rst:`|version|` + :ref:`default substitution `. - 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. + This may be something like :code-py:`version = '4.2'`. + The full project version is defined in :confval:`release`. - The value may also be a list of file extensions: then Sphinx will consider - that they all map to the ``'restructuredtext'`` file type. + If your project does not draw a meaningful distinction between + between a 'full' and 'major' version, + set both :code-py:`version` and :code-py:`release` to the same value. - Default is ``{'.rst': 'restructuredtext'}``. +.. confval:: release + :type: :code-py:`str` + :default: :code-py:`''` - .. note:: file extensions have to start with a dot (e.g. ``.rst``). + The full project version, used as the replacement for the :code-rst:`|release|` + :ref:`default substitution `, and + e.g. in the HTML templates. - .. versionchanged:: 1.3 - Can now be a list of extensions. + This may be something like :code-py:`release = '4.2.1b0'`. + The major (short) project version is defined in :confval:`version`. - .. versionchanged:: 1.8 - Support file type mapping + If your project does not draw a meaningful distinction between + between a 'full' and 'major' version, + set both :code-py:`version` and :code-py:`release` to the same value. -.. confval:: source_encoding - The encoding of all reST source files. The recommended encoding, and the - default value, is ``'utf-8-sig'``. +General configuration +===================== - .. versionadded:: 0.5 - Previously, Sphinx accepted only UTF-8 encoded sources. +.. confval:: needs_sphinx + :type: :code-py:`str` + :default: :code-py:`''` -.. confval:: source_parsers + Set a minimum supported version of Sphinx required to build the project. + The format should be a ``'major.minor'`` version string like ``'1.1'`` + Sphinx will compare it with its version and refuse to build the project + if the running version of Sphinx is too old. + By default, there is no minimum version. - If given, a dictionary of parser classes for different source suffices. The - keys are the suffix, the values can be either a class or a string giving a - fully-qualified name of a parser class. The parser class can be either - ``docutils.parsers.Parser`` or :class:`sphinx.parsers.Parser`. Files with a - suffix that is not in the dictionary will be parsed with the default - reStructuredText parser. + .. versionadded:: 1.0 - For example:: + .. versionchanged:: 1.4 + Allow a ``'major.minor.micro'`` version string. - source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'} +.. confval:: extensions + :type: :code-py:`list[str]` + :default: :code-py:`[]` - .. note:: + A list of strings that are module names of + :doc:`Sphinx extensions `. + These can be extensions bundled with Sphinx (named ``sphinx.ext.*``) + or custom first-party or third-party extensions. - Refer to :doc:`/usage/markdown` for more information on using Markdown - with Sphinx. + To use a third-party extension, you must ensure that it is installed + and include it in the :code-py:`extensions` list, like so: - .. versionadded:: 1.3 + .. code-block:: python - .. deprecated:: 1.8 - Now Sphinx provides an API :meth:`.Sphinx.add_source_parser` to register - a source parser. Please use it instead. + extensions = [ + ... + 'numpydoc', + ] -.. confval:: master_doc + There are two options for first-party extensions. + The configuration file itself can be an extension; + for that, you only need to provide a :func:`setup` function in it. + Otherwise, you must ensure that your custom extension is importable, + and located in a directory that is in the Python path. - Same as :confval:`root_doc`. + Ensure that absolute paths are used when modifying :data:`sys.path`. + If your custom extensions live in a directory that is relative to the + :term:`configuration directory`, use :func:`os.path.abspath` like so: - .. versionchanged:: 4.0 - Renamed ``master_doc`` to ``root_doc``. + .. code-block:: python -.. confval:: root_doc + import os, sys; sys.path.append(os.path.abspath('sphinxext')) - The document name of the "root" document, that is, the document that - contains the root :rst:dir:`toctree` directive. Default is ``'index'``. + extensions = [ + ... + 'extname', + ] - .. versionchanged:: 2.0 - The default is changed to ``'index'`` from ``'contents'``. - .. versionchanged:: 4.0 - Renamed ``root_doc`` from ``master_doc``. + The directory structure illustrated above would look like this: -.. confval:: exclude_patterns + .. code-block:: none - A list of glob-style patterns [1]_ that should be excluded when looking for - source files. They are matched against the source file names relative - to the source directory, using slashes as directory separators on all - platforms. + / + ├── conf.py + └── sphinxext/ +    └── extname.py - Example patterns: - - ``'library/xml.rst'`` -- ignores the ``library/xml.rst`` file - - ``'library/xml'`` -- ignores the ``library/xml`` directory - - ``'library/xml*'`` -- ignores all files and directories starting with - ``library/xml`` - - ``'**/.svn'`` -- ignores all ``.svn`` directories +.. confval:: needs_extensions + :type: :code-py:`dict[str, str]` + :default: :code-py:`{}` + + If set, this value must be a dictionary specifying version requirements + for extensions in :confval:`extensions`. + The version strings should be in the ``'major.minor'`` form. + Requirements do not have to be specified for all extensions, + only for those you want to check. + Example: - :confval:`exclude_patterns` is also consulted when looking for static files - in :confval:`html_static_path` and :confval:`html_extra_path`. + .. code-block:: python - .. versionadded:: 1.0 + needs_extensions = { + 'sphinxcontrib.something': '1.5', + } -.. confval:: include_patterns + This requires that the extension declares its version + in the :code-py:`setup()` function. See :ref:`dev-extensions` for further details. - A list of glob-style patterns [1]_ that are used to find source files. They - are matched against the source file names relative to the source directory, - using slashes as directory separators on all platforms. The default is ``**``, - meaning that all files are recursively included from the source directory. - :confval:`exclude_patterns` has priority over :confval:`include_patterns`. + .. versionadded:: 1.3 - Example patterns: +.. confval:: manpages_url + :type: :code-py:`str` + :default: :code-py:`''` + + A URL to cross-reference :rst:role:`manpage` roles. + If this is defined to ``https://manpages.debian.org/{path}``, + the :literal:`:manpage:`man(1)` role will link to + . + The patterns available are: + + ``page`` + The manual page (``man``) + ``section`` + The manual section (``1``) + ``path`` + The original manual page and section specified (``man(1)``) - - ``'**'`` -- all files in the source directory and subdirectories, recursively - - ``'library/xml'`` -- just the ``library/xml`` directory - - ``'library/xml*'`` -- all files and directories starting with ``library/xml`` - - ``'**/doc'`` -- all ``doc`` directories (this might be useful if - documentation is co-located with source files) + This also supports manpages specified as ``man.1``. - .. versionadded:: 5.1 + .. code-block:: python -.. confval:: templates_path + # To use manpages.debian.org: + manpages_url = 'https://manpages.debian.org/{path}' + # To use man7.org: + manpages_url = 'https://man7.org/linux/man-pages/man{section}/{page}.{section}.html' + # To use linux.die.net: + manpages_url = 'https://linux.die.net/man/{section}/{page}' + # To use helpmanual.io: + manpages_url = 'https://helpmanual.io/man{section}/{page}' - 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. + .. versionadded:: 1.7 - .. versionchanged:: 1.3 - As these files are not meant to be built, they are automatically added to - :confval:`exclude_patterns`. +.. confval:: today + today_fmt -.. confval:: template_bridge + These values determine how to format the current date, + used as the replacement for the :code-rst:`|today|` + :ref:`default substitution `. - A string with the fully-qualified name of a callable (or simply a class) - that returns an instance of :class:`~sphinx.application.TemplateBridge`. - This instance is then used to render HTML documents, and possibly the output - of other builders (currently the changes builder). (Note that the template - bridge must be made theme-aware if HTML themes are to be used.) + * If you set :confval:`today` to a non-empty value, it is used. + * Otherwise, the current time is formatted using :func:`time.strftime` and + the format given in :confval:`today_fmt`. -.. confval:: rst_epilog + The default for :confval:`today` is :code-py:`''`, + and the default for :confval:`today_fmt` is :code-py:`'%b %d, %Y'` + (or, if translation is enabled with :confval:`language`, + an equivalent format for the selected locale). - .. index:: pair: global; substitutions - A string of reStructuredText that will be included at the end of every source - file that is read. This is a possible place to add substitutions that should - be available in every file (another being :confval:`rst_prolog`). An - example:: +Options for figure numbering +---------------------------- - rst_epilog = """ - .. |psf| replace:: Python Software Foundation - """ +.. confval:: numfig + :type: :code-py:`bool` + :default: :code-py:`False` - .. versionadded:: 0.6 + If :code-py:`True`, figures, tables and code-blocks are automatically numbered + if they have a caption. + The :rst:role:`numref` role is enabled. + Obeyed so far only by HTML and LaTeX builders. -.. confval:: rst_prolog + .. note:: - .. index:: pair: global; substitutions + The LaTeX builder always assigns numbers whether this option is enabled + or not. - A string of reStructuredText that will be included at the beginning of every - source file that is read. This is a possible place to add substitutions that - should be available in every file (another being :confval:`rst_epilog`). An - example:: + .. versionadded:: 1.3 - rst_prolog = """ - .. |psf| replace:: Python Software Foundation - """ +.. confval:: numfig_format + :type: :code-py:`dict[str, str]` + :default: :code-py:`{}` - .. versionadded:: 1.0 + A dictionary mapping :code-py:`'figure'`, :code-py:`'table'`, + :code-py:`'code-block'` and :code-py:`'section'` to strings + that are used for format of figure numbers. + The marker ``%s`` will be replaced with the figure number. -.. confval:: primary_domain + The defaults are: - .. index:: default; domain - primary; domain + .. code-block:: python - The name of the default :doc:`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 :rst:dir:`default-domain` directive) will have the domain - name explicitly prepended when named (e.g., when the default domain is C, - Python functions will be named "Python function", not just "function"). + numfig_format = { + 'code-block': 'Listing %s', + 'figure': 'Fig. %s', + 'section': 'Section', + 'table': 'Table %s', + } - .. versionadded:: 1.0 + .. versionadded:: 1.3 -.. confval:: default_role +.. confval:: numfig_secnum_depth + :type: :code-py:`int` + :default: :code-py:`1` + + * If set to :code-py:`0`, figures, tables, and code-blocks + are continuously numbered starting at ``1``. + * If :code-py:`1`, the numbering will be ``x.1``, ``x.2``, ... + with ``x`` 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 via + the ``:numbered:`` option of the :rst:dir:`toctree` directive. + * If :code-py:`2`, the numbering will be ``x.y.1``, ``x.y.2``, ... + with ``x`` representing the section number and ``y`` the sub-section number. + If located directly under a section, there will be no ``y.`` 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. - .. index:: default; role + .. versionadded:: 1.3 - 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. + .. versionchanged:: 1.7 + The LaTeX builder obeys this setting + if :confval:`numfig` is set to :code-py:`True`. - The default role can always be set within individual documents using the - standard reST :dudir:`default-role` directive. - .. versionadded:: 0.4 +Options for highlighting +------------------------ -.. confval:: keep_warnings +.. confval:: highlight_language + :type: :code-py:`str` + :default: :code-py:`'default'` - 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 language to highlight source code in. + The default is :code-py:`'default'`, + which suppresses warnings if highlighting as Python code fails. - The default is ``False``, the pre-0.5 behavior was to always keep them. + The value should be a valid Pygments lexer name, see + :ref:`code-examples` for more details. .. versionadded:: 0.5 -.. confval:: show_warning_types - - If ``True``, the type of each warning is added as a suffix to the warning message, - e.g., ``WARNING: [...] [index]`` or ``WARNING: [...] [toc.circular]``. - The default is ``False``. + .. versionchanged:: 1.4 + The default is now :code-py:`'default'`. - .. versionadded:: 7.3.0 +.. confval:: highlight_options + :type: :code-py:`dict[str, dict[str, Any]]` + :default: :code-py:`{}` -.. confval:: suppress_warnings + A dictionary that maps Pygments lexer names to their options. + These are lexer-specific; for the options understood by each, + see the `Pygments documentation `_. - A list of warning types to suppress arbitrary warning messages. + Example: - Sphinx core supports following warning types: + .. code-block:: python - * ``app.add_node`` - * ``app.add_directive`` - * ``app.add_role`` - * ``app.add_generic_role`` - * ``app.add_source_parser`` - * ``config.cache`` - * ``download.not_readable`` - * ``epub.unknown_project_files`` - * ``epub.duplicated_toc_entry`` - * ``i18n.inconsistent_references`` - * ``index`` - * ``image.not_readable`` - * ``ref.term`` - * ``ref.ref`` - * ``ref.numref`` - * ``ref.keyword`` - * ``ref.option`` - * ``ref.citation`` - * ``ref.footnote`` - * ``ref.doc`` - * ``ref.python`` - * ``misc.highlighting_failure`` - * ``toc.circular`` - * ``toc.excluded`` - * ``toc.not_readable`` - * ``toc.secnum`` - * ``toc.no_title`` + highlight_options = { + 'default': {'stripall': True}, + 'php': {'startinline': True}, + } - Extensions can also define their own warning types. - Those defined by the first-party ``sphinx.ext`` extensions are: + .. versionadded:: 1.3 + .. versionchanged:: 3.5 - * ``autodoc`` - * ``autodoc.import_object`` - * ``autosectionlabel.`` - * ``autosummary`` - * ``intersphinx.external`` + Allow configuring highlight options for multiple lexers. - You can choose from these types. You can also give only the first - component to exclude all warnings attached to it. +.. confval:: pygments_style + :type: :code-py:`str` + :default: :code-py:`'sphinx'` - .. versionadded:: 1.4 + The style name to use for Pygments highlighting of source code. + If not set, either the theme's default style + or :code-py:`'sphinx'` is selected for HTML output. - .. versionchanged:: 1.5 + .. versionchanged:: 0.3 + If the value is a fully-qualified name of a custom Pygments style class, + this is then used as custom style. - Added ``misc.highlighting_failure`` - .. versionchanged:: 1.5.1 +Options for HTTP requests +------------------------- - Added ``epub.unknown_project_files`` +.. confval:: tls_verify + :type: :code-py:`bool` + :default: :code-py:`True` - .. versionchanged:: 1.6 + If True, Sphinx verifies server certificates. - Added ``ref.footnote`` + .. versionadded:: 1.5 - .. versionchanged:: 2.1 +.. confval:: tls_cacerts + :type: :code-py:`str | dict[str, str]` + :default: :code-py:`''` - Added ``autosectionlabel.`` + A path to a certification file of CA or + a path to directory which contains the certificates. + This also allows a dictionary mapping + hostnames to the certificate file path. + The certificates are used to verify server certifications. - .. versionchanged:: 3.3.0 + .. versionadded:: 1.5 - Added ``epub.duplicated_toc_entry`` + .. tip:: - .. versionchanged:: 4.3 + Sphinx uses requests_ as a HTTP library internally. + If :confval:`!tls_cacerts` is not set, + Sphinx falls back to requests' default behaviour. + See :ref:`requests:verification` for further details. - Added ``toc.excluded`` and ``toc.not_readable`` + .. _requests: https://requests.readthedocs.io/ - .. versionadded:: 4.5 +.. confval:: user_agent + :type: :code-py:`str` + :default: :code-py:`'Mozilla/5.0 (X11; Linux x86_64; rv:100.0) Gecko/20100101 \ + Firefox/100.0 Sphinx/X.Y.Z'` - Added ``i18n.inconsistent_references`` + Set the User-Agent used by Sphinx for HTTP requests. - .. versionadded:: 7.1 + .. versionadded:: 2.3 - Added ``index`` warning type. - .. versionadded:: 7.3 +.. _intl-options: - Added ``config.cache`` warning type. +Options for internationalisation +-------------------------------- -.. confval:: needs_sphinx +These options influence Sphinx's *Native Language Support*. +See the documentation on :ref:`intl` for details. - 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. +.. confval:: language + :type: :code-py:`str` + :default: :code-py:`'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 paragraphs + from your documents with the translation sets obtained + from :confval:`locale_dirs`. + Sphinx will search language-specific figures named by + :confval:`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. - .. versionadded:: 1.0 + .. versionadded:: 0.5 .. versionchanged:: 1.4 - also accepts micro version string - -.. confval:: needs_extensions - - This value can be a dictionary specifying version requirements for - extensions in :confval:`extensions`, e.g. ``needs_extensions = - {'sphinxcontrib.something': '1.5'}``. The version strings should be in the - form ``major.minor``. Requirements do not have to be specified for all - extensions, only for those you want to check. - - This requires that the extension specifies its version to Sphinx (see - :ref:`dev-extensions` for how to do that). - - .. versionadded:: 1.3 - -.. confval:: manpages_url - - A URL to cross-reference :rst:role:`manpage` roles. If this is - defined to ``https://manpages.debian.org/{path}``, the - :literal:`:manpage:`man(1)`` role will link to - . The patterns available are: - - * ``page`` - the manual page (``man``) - * ``section`` - the manual section (``1``) - * ``path`` - the original manual page and section specified (``man(1)``) - - This also supports manpages specified as ``man.1``. - - .. note:: This currently affects only HTML writers but could be - expanded in the future. - - .. versionadded:: 1.7 - -.. confval:: nitpicky - - If true, Sphinx will warn about *all* references where the target cannot be - found. Default is ``False``. You can activate this mode temporarily using - the :option:`-n ` command-line switch. - - .. versionadded:: 1.0 - -.. confval:: nitpick_ignore - - A set or list of ``(type, target)`` tuples (by default empty) that should be - ignored when generating warnings in "nitpicky mode". Note that ``type`` - should include the domain name if present. Example entries would be - ``('py:func', 'int')`` or ``('envvar', 'LD_LIBRARY_PATH')``. - - .. versionadded:: 1.1 - .. versionchanged:: 6.2 - Changed allowable container types to a set, list, or tuple - -.. confval:: nitpick_ignore_regex - - An extended version of :confval:`nitpick_ignore`, which instead interprets - the ``type`` and ``target`` strings as regular expressions. Note, that the - regular expression must match the whole string (as if the ``^`` and ``$`` - markers were inserted). - - For example, ``(r'py:.*', r'foo.*bar\.B.*')`` will ignore nitpicky warnings - for all python entities that start with ``'foo'`` and have ``'bar.B'`` in - them, such as ``('py:const', 'foo_package.bar.BAZ_VALUE')`` or - ``('py:class', 'food.bar.Barman')``. + Support figure substitution - .. versionadded:: 4.1 - .. versionchanged:: 6.2 - Changed allowable container types to a set, list, or tuple + .. versionchanged:: 5.0 + The default is now :code-py:`'en'` (previously :code-py:`None`). -.. confval:: numfig + Currently supported languages by Sphinx are: - If true, figures, tables and code-blocks are automatically numbered if they - have a caption. The :rst:role:`numref` role is enabled. - Obeyed so far only by HTML and LaTeX builders. Default is ``False``. + * ``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 + +.. confval:: locale_dirs + :type: :code-py:`list[str]` + :default: :code-py:`['locale']` + + Directories in which to search for additional message catalogs + (see :confval:`language`), relative to the source directory. + The directories on this path are searched by the :mod:`gettext` module. + + Internal messages are fetched from a text domain of ``sphinx``; + so if you add the directory :file:`./locale` to this setting, + the message catalogs + (compiled from ``.po`` format using :program:`msgfmt`) + must be in :file:`./locale/{language}/LC_MESSAGES/sphinx.mo`. + The text domain of individual documents + depends on :confval:`gettext_compact`. .. note:: + The :option:`-v option to sphinx-build ` + is useful to check the :confval:`!locale_dirs` setting is working as expected. + If the message catalog directory not found, debug messages are emmitted. - The LaTeX builder always assigns numbers whether this option is enabled - or not. + .. versionadded:: 0.5 - .. versionadded:: 1.3 + .. versionchanged:: 1.5 + Use ``locales`` directory as a default value -.. confval:: numfig_format +.. confval:: gettext_allow_fuzzy_translations + :type: :code-py:`bool` + :default: :code-py:`False` - 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. + If True, "fuzzy" messages in the message catalogs are used for translation. - Default is to use ``'Fig. %s'`` for ``'figure'``, ``'Table %s'`` for - ``'table'``, ``'Listing %s'`` for ``'code-block'`` and ``'Section %s'`` for - ``'section'``. + .. versionadded:: 4.3 + +.. confval:: gettext_compact + :type: :code-py:`bool | str` + :default: :code-py:`True` + + * If :code-py:`True`, a document's text domain is + its docname if it is a top-level project file + and its very base directory otherwise. + * If :code-py:`False`, a document's text domain is + the docname, in full. + * If set to a string, every document's text domain is + set to this string, making all documents use single text domain. + + With :code-py:`gettext_compact = True`, the document + :file:`markup/code.rst` ends up in the ``markup`` text domain. + With this option set to :code-py:`False`, it is ``markup/code``. + With this option set to :code-py:`'sample'`, it is ``sample``. + + .. versionadded:: 1.1 + + .. versionchanged:: 3.3 + Allow string values. + +.. confval:: gettext_uuid + :type: :code-py:`bool` + :default: :code-py:`False` + + If :code-py:`True`, Sphinx generates UUID information + for version tracking in message catalogs. + It is used to: + + * Add a UUID line for each *msgid* 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 running + :command:`pip install levenshtein`. + + .. _Levenshtein: https://pypi.org/project/Levenshtein/ .. versionadded:: 1.3 -.. confval:: numfig_secnum_depth +.. confval:: gettext_location + :type: :code-py:`bool` + :default: :code-py:`True` - - if set to ``0``, figures, tables and code-blocks are continuously numbered - starting at ``1``. - - if ``1`` (default) numbers will be ``x.1``, ``x.2``, ... with ``x`` - the section number (top level sectioning; no ``x.`` if no section). - This naturally applies only if section numbering has been activated via - the ``:numbered:`` option of the :rst:dir:`toctree` directive. - - ``2`` means that numbers will be ``x.y.1``, ``x.y.2``, ... if located in - a sub-section (but still ``x.1``, ``x.2``, ... if located directly under a - section and ``1``, ``2``, ... if not in any top level section.) - - etc... + If :code-py:`True`, Sphinx generates location information + for messages in message catalogs. .. versionadded:: 1.3 - .. versionchanged:: 1.7 - The LaTeX builder obeys this setting (if :confval:`numfig` is set to - ``True``). +.. confval:: gettext_auto_build + :type: :code-py:`bool` + :default: :code-py:`True` -.. confval:: smartquotes + If :code-py:`True`, Sphinx builds a ``.mo`` file + for each translation catalog file. - 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``. + .. versionadded:: 1.3 - __ https://docutils.sourceforge.io/docs/user/smartquotes.html - __ https://daringfireball.net/projects/smartypants/ +.. confval:: gettext_additional_targets + :type: :code-py:`set[str] | Sequence[str]` + :default: :code-py:`[]` - .. versionadded:: 1.6.6 - It replaces deprecated :confval:`html_use_smartypants`. - It applies by default to all builders except ``man`` and ``text`` - (see :confval:`smartquotes_excludes`.) + Enable ``gettext`` translation for certain element types. + Example: - A `docutils.conf`__ file located in the configuration directory (or a - global :file:`~/.docutils` file) is obeyed unconditionally if it - *deactivates* smart quotes via the corresponding `Docutils option`__. But - if it *activates* them, then :confval:`smartquotes` does prevail. + .. code-block:: python - __ https://docutils.sourceforge.io/docs/user/config.html - __ https://docutils.sourceforge.io/docs/user/config.html#smart-quotes + gettext_additional_targets = {'literal-block', 'image'} -.. confval:: smartquotes_action + The following element types are supported: - This string customizes the Smart Quotes transform. See the file - :file:`smartquotes.py` at the `Docutils repository`__ for details. The - default ``'qDe'`` educates normal **q**\ uote characters ``"``, ``'``, - em- and en-**D**\ ashes ``---``, ``--``, and **e**\ llipses ``...``. + * :code-py:`'index'` -- index terms + * :code-py:`'literal-block'` -- literal blocks + (``::`` annotation and ``code-block`` directive) + * :code-py:`'doctest-block'` -- doctest block + * :code-py:`'raw'` -- raw content + * :code-py:`'image'` -- image/figure uri - .. versionadded:: 1.6.6 + .. versionadded:: 1.3 + .. versionchanged:: 4.0 + The alt text for images is translated by default. + .. versionchanged:: 7.4 + Permit and prefer a set type. - __ https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/ +.. confval:: figure_language_filename + :type: :code-py:`str` + :default: :code-py:`'{root}.{language}{ext}'` -.. confval:: smartquotes_excludes + The filename format for language-specific figures. + The available format tokens are: - This is a ``dict`` whose default is:: + * ``{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 path + or 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 :code-rst:`.. image:: images/filename.png`, + using an image at :file:`images/filename.png`, + will use the language-specific figure filename + :file:`images/filename.en.png`. + + If :confval:`!figure_language_filename` is set as below, + the language-specific figure filename will be + :file:`images/en/filename.png` instead. - {'languages': ['ja'], 'builders': ['man', 'text']} + .. code-block:: python - Each entry gives a sufficient condition to ignore the - :confval:`smartquotes` setting and deactivate the Smart Quotes transform. - Accepted keys are as above ``'builders'`` or ``'languages'``. - The values are lists. + figure_language_filename = '{path}{language}/{basename}{ext}' - .. note:: Currently, in case of invocation of :program:`make` with multiple - targets, the first target name is the only one which is tested against - the ``'builders'`` entry and it decides for all. Also, a ``make text`` - following ``make html`` needs to be issued in the form ``make text - O="-E"`` to force re-parsing of source files, as the cached ones are - already transformed. On the other hand the issue does not arise with - direct usage of :program:`sphinx-build` as it caches - (in its default usage) the parsed source files in per builder locations. + .. versionadded:: 1.4 - .. hint:: An alternative way to effectively deactivate (or customize) the - smart quotes for a given builder, for example ``latex``, is to use - ``make`` this way: + .. versionchanged:: 1.5 + Added ``{path}`` and ``{basename}`` tokens. - .. code-block:: console + .. versionchanged:: 3.2 + Added ``{docpath}`` token. + +.. confval:: translation_progress_classes + :type: :code-py:`bool | 'translated' | 'untranslated'` + :default: :code-py:`False` - make latex O="-D smartquotes_action=" + 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. - This can follow some ``make html`` with no problem, in contrast to the - situation from the prior note. + :code-py:`True` + Add ``translated`` and ``untranslated`` classes + to all nodes with translatable content. + :code-py:`'translated'` + Only add the ``translated`` class. + :code-py:`'untranslated'` + Only add the ``untranslated`` class. + :code-py:`False` + Do not add any classes to indicate translation progress. - .. versionadded:: 1.6.6 + .. versionadded:: 7.1 -.. confval:: user_agent - A User-Agent of Sphinx. It is used for a header on HTTP access (ex. - linkcheck, intersphinx and so on). Default is ``"Sphinx/X.Y.Z - requests/X.Y.Z python/X.Y.Z"``. +Options for markup +------------------ - .. versionadded:: 2.3 +.. confval:: default_role + :type: :code-py:`str` + :default: :code-py:`None` -.. confval:: tls_verify + .. index:: default; role - If true, Sphinx verifies server certifications. Default is ``True``. + The name of a reStructuredText role (builtin or Sphinx extension) + to use as the default role, that is, for text marked up ```like this```. + This can be set to :code-py:`'py:obj'` to make ```filter``` + a cross-reference to the Python function "filter". - .. versionadded:: 1.5 + The default role can always be set within individual documents using + the standard reStructuredText :dudir:`default-role` directive. -.. confval:: tls_cacerts + .. versionadded:: 0.4 - 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. +.. confval:: keep_warnings + :type: :code-py:`bool` + :default: :code-py:`False` - .. versionadded:: 1.5 + Keep warnings as "system message" paragraphs in the rendered documents. + Warnings are always written to the standard error stream + when :program:`sphinx-build` is run, regardless of this setting. - .. tip:: Sphinx uses requests_ as a HTTP library internally. - Therefore, Sphinx refers a certification file on the - directory pointed ``REQUESTS_CA_BUNDLE`` environment - variable if ``tls_cacerts`` not set. + .. versionadded:: 0.5 - .. _requests: https://requests.readthedocs.io/en/master/ +.. confval:: option_emphasise_placeholders + :type: :code-py:`bool` + :default: :code-py:`False` -.. confval:: today - today_fmt + When enabled, emphasise placeholders in :rst:dir:`option` directives. + To display literal braces, escape with a backslash (``\{``). + For example, ``option_emphasise_placeholders=True`` + and ``.. option:: -foption={TYPE}`` would render with ``TYPE`` emphasised. - These values determine how to format the current date, used as the - replacement for ``|today|``. + .. versionadded:: 5.1 - * If you set :confval:`today` to a non-empty value, it is used. - * Otherwise, the current time is formatted using :func:`time.strftime` and - the format given in :confval:`today_fmt`. +.. confval:: primary_domain + :type: :code-py:`str` + :default: :code-py:`'py'` - The default is now :confval:`today` and a :confval:`today_fmt` of ``'%b %d, - %Y'`` (or, if translation is enabled with :confval:`language`, an equivalent - format for the selected locale). + .. index:: pair: default; domain -.. confval:: highlight_language + The name of the default :doc:`domain `. + Can also be :code-py:`None` to disable a default domain. + The default is :code-py:`'py'`, for the Python domain. + + Those objects in other domain + (whether the domain name is given explicitly, + or selected by a :rst:dir:`default-domain` directive) + will have the domain name explicitly prepended when named + (e.g., when the default domain is C, + Python functions will be named "Python function", not just "function"). + Example: - The default language to highlight source code in. The default is - ``'default'``. It is similar to ``'python3'``; it is mostly a superset of - ``'python'`` but it fallbacks to ``'none'`` without warning if failed. - ``'python3'`` and other languages will emit warning if failed. + .. code-block:: python - The value should be a valid Pygments lexer name, see - :ref:`code-examples` for more details. + primary_domain = 'cpp' - .. versionadded:: 0.5 + .. versionadded:: 1.0 - .. versionchanged:: 1.4 - The default is now ``'default'``. If you prefer Python 2 only - highlighting, you can set it back to ``'python'``. +.. confval:: rst_epilog + :type: :code-py:`str` + :default: :code-py:`''` -.. confval:: highlight_options + .. index:: pair: global; substitutions - A dictionary that maps language names to options for the lexer modules of - Pygments. These are lexer-specific; for the options understood by each, - see the `Pygments documentation `_. + A string of reStructuredText that will be included + at the end of every source file that is read. + This is a possible place to add substitutions that + should be available in every file (another being :confval:`rst_prolog`). + Example: - Example:: + .. code-block:: python - highlight_options = { - 'default': {'stripall': True}, - 'php': {'startinline': True}, - } + rst_epilog = """ + .. |psf| replace:: Python Software Foundation + """ - A single dictionary of options are also allowed. Then it is recognized - as options to the lexer specified by :confval:`highlight_language`:: + .. versionadded:: 0.6 - # configuration for the ``highlight_language`` - highlight_options = {'stripall': True} +.. confval:: rst_prolog + :type: :code-py:`str` + :default: :code-py:`''` - .. versionadded:: 1.3 - .. versionchanged:: 3.5 + .. index:: pair: global; substitutions - Allow to configure highlight options for multiple languages + A string of reStructuredText that will be included + at the beginning of every source file that is read. + This is a possible place to add substitutions that + should be available in every file (another being :confval:`rst_epilog`). + Example: -.. confval:: pygments_style + .. code-block:: python - 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. + rst_prolog = """ + .. |psf| replace:: Python Software Foundation + """ - .. versionchanged:: 0.3 - If the value is a fully-qualified name of a custom Pygments style class, - this is then used as custom style. + .. versionadded:: 1.0 -.. confval:: maximum_signature_line_length +.. confval:: show_authors + :type: :code-py:`bool` + :default: :code-py:`False` - If a signature's length in characters exceeds the number set, each - parameter within the signature will be displayed on an individual logical - line. + A boolean that decides whether :rst:dir:`codeauthor` and + :rst:dir:`sectionauthor` directives produce any output in the built files. - When ``None`` (the default), there is no maximum length and the entire - signature will be displayed on a single logical line. +.. confval:: trim_footnote_reference_space + :type: :code-py:`bool` + :default: :code-py:`False` - A 'logical line' is similar to a hard line break---builders or themes may - choose to 'soft wrap' a single logical line, and this setting does not affect - that behaviour. + Trim spaces before footnote references that are + necessary for the reStructuredText parser to recognise the footnote, + but do not look too nice in the output. - Domains may provide options to suppress any hard wrapping on an individual - object directive, such as seen in the C, C++, and Python domains (e.g. - :rst:dir:`py:function:single-line-parameter-list`). + .. versionadded:: 0.6 - .. versionadded:: 7.1 -.. confval:: add_function_parentheses +.. _math-options: - 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``. +Options for Maths +----------------- -.. confval:: add_module_names +These options control maths markup and notation. - A boolean that decides whether module names are prepended to all - :term:`object` names (for object types where a "module" of some kind is - defined), e.g. for :rst:dir:`py:function` directives. Default is ``True``. +.. confval:: math_eqref_format + :type: :code-py:`str` + :default: :code-py:`'({number})'` -.. confval:: toc_object_entries + A string used for formatting the labels of references to equations. + The ``{number}`` place-holder stands for the equation number. - Create table of contents entries for domain objects (e.g. functions, classes, - attributes, etc.). Default is ``True``. + Example: ``'Eq.{number}'`` gets rendered as, for example, ``Eq.10``. -.. confval:: toc_object_entries_show_parents + .. versionadded:: 1.7 - A string that determines how domain objects (e.g. functions, classes, - attributes, etc.) are displayed in their table of contents entry. +.. confval:: math_number_all + :type: :code-py:`bool` + :default: :code-py:`False` - Use ``domain`` to allow the domain to determine the appropriate number of - parents to show. For example, the Python domain would show ``Class.method()`` - and ``function()``, leaving out the ``module.`` level of parents. - This is the default setting. + Force all displayed equations to be numbered. + Example: - Use ``hide`` to only show the name of the element without any parents - (i.e. ``method()``). + .. code-block:: python - Use ``all`` to show the fully-qualified name for the object - (i.e. ``module.Class.method()``), displaying all parents. + math_number_all = True - .. versionadded:: 5.2 + .. versionadded:: 1.4 -.. confval:: show_authors +.. confval:: math_numfig + :type: :code-py:`bool` + :default: :code-py:`True` - A boolean that decides whether :rst:dir:`codeauthor` and - :rst:dir:`sectionauthor` directives produce any output in the built files. + If :code-py:`True`, displayed math equations are numbered across pages + when :confval:`numfig` is enabled. + The :confval:`numfig_secnum_depth` setting is respected. + The :rst:role:`eq`, not :rst:role:`numref`, role + must be used to reference equation numbers. -.. confval:: modindex_common_prefix + .. versionadded:: 1.7 - A list of prefixes that are ignored for sorting the Python module index - (e.g., if this is set to ``['foo.']``, then ``foo.bar`` is shown under ``B``, - not ``F``). This can be handy if you document a project that consists of a - single package. Works only for the HTML builder currently. Default is - ``[]``. - .. versionadded:: 0.6 +Options for the nitpicky mode +----------------------------- -.. confval:: trim_footnote_reference_space +.. confval:: nitpicky + :type: :code-py:`bool` + :default: :code-py:`False` - 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. + Enables nitpicky mode if :code-py:`True`. + In nitpicky mode, Sphinx will warn about *all* references + where the target cannot be found. + This is recommended for new projects as it ensures that all references + are to valid targets. - .. versionadded:: 0.6 + You can activate this mode temporarily using + the :option:`--nitpicky ` command-line option. + See :confval:`nitpick_ignore` for a way to mark missing references + as "known missing". -.. confval:: trim_doctest_flags + .. code-block:: python - If true, doctest flags (comments looking like ``# doctest: FLAG, ...``) at - the ends of lines and ```` markers are removed for all code - blocks showing interactive Python sessions (i.e. doctests). Default is - ``True``. See the extension :mod:`~sphinx.ext.doctest` for more - possibilities of including doctests. + nitpicky = True .. versionadded:: 1.0 - .. versionchanged:: 1.1 - Now also removes ````. + +.. confval:: nitpick_ignore + :type: :code-py:`set[tuple[str, str]] | Sequence[tuple[str, str]]` + :default: :code-py:`()` + + A set or list of :code-py:`(warning_type, target)` tuples + that should be ignored when generating warnings + in :confval:`"nitpicky mode" `. + Note that ``warning_type`` should include the domain name if present. + Example: + + .. code-block:: python + + nitpick_ignore = { + ('py:func', 'int'), + ('envvar', 'LD_LIBRARY_PATH'), + } + + .. versionadded:: 1.1 + .. versionchanged:: 6.2 + Changed allowable container types to a set, list, or tuple + +.. confval:: nitpick_ignore_regex + :type: :code-py:`set[tuple[str, str]] | Sequence[tuple[str, str]]` + :default: :code-py:`()` + + An extended version of :confval:`nitpick_ignore`, + which instead interprets the ``warning_type`` and ``target`` strings + as regular expressions. + Note that the regular expression must match the whole string + (as if the ``^`` and ``$`` markers were inserted). + + For example, ``(r'py:.*', r'foo.*bar\.B.*')`` will ignore nitpicky warnings + for all python entities that start with ``'foo'`` + and have ``'bar.B'`` in them, + such as :code-py:`('py:const', 'foo_package.bar.BAZ_VALUE')` + or :code-py:`('py:class', 'food.bar.Barman')`. + + .. versionadded:: 4.1 + .. versionchanged:: 6.2 + Changed allowable container types to a set, list, or tuple + + +Options for object signatures +----------------------------- + +.. confval:: add_function_parentheses + :type: :code-py:`bool` + :default: :code-py:`True` + + 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. + +.. confval:: maximum_signature_line_length + :type: :code-py:`int | None` + :default: :code-py:`None` + + If a signature's length in characters exceeds the number set, + each parameter within the signature will be displayed on + an individual logical line. + + When :code-py:`None`, there is no maximum length and the entire + signature will be displayed on a single logical line. + + A 'logical line' is similar to a hard line break---builders or themes + may choose to 'soft wrap' a single logical line, + and this setting does not affect that behaviour. + + Domains may provide options to suppress any hard wrapping + on an individual object directive, + such as seen in the C, C++, and Python domains + (e.g. :rst:dir:`py:function:single-line-parameter-list`). + + .. versionadded:: 7.1 .. confval:: strip_signature_backslash + :type: :code-py:`bool` + :default: :code-py:`False` - 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. + :code-py:`True` will reinstate that behaviour. .. versionadded:: 3.0 -.. confval:: option_emphasise_placeholders +.. confval:: toc_object_entries + :type: :code-py:`bool` + :default: :code-py:`True` + + Create table of contents entries for domain objects + (e.g. functions, classes, attributes, etc.). + + .. versionadded:: 5.2 + +.. confval:: toc_object_entries_show_parents + :type: :code-py:`'domain' | 'hide' | 'all'` + :default: :code-py:`'domain'` + + A string that determines how domain objects + (functions, classes, attributes, etc.) + are displayed in their table of contents entry. + + Use :code-py:`'domain'` to allow the domain to determine + the appropriate number of parents to show. + For example, the Python domain would show :code-py:`Class.method()` + and :code-py:`function()`, + leaving out the :code-py:`module.` level of parents. + + Use :code-py:`'hide'` to only show the name of the element + without any parents (i.e. :code-py:`method()`). + + Use :code-py:`'all'` to show the fully-qualified name for the object + (i.e. :code-py:`module.Class.method()`), displaying all parents. + + .. versionadded:: 5.2 - Default is ``False``. - When enabled, emphasise placeholders in :rst:dir:`option` directives. - To display literal braces, escape with a backslash (``\{``). For example, - ``option_emphasise_placeholders=True`` and ``.. option:: -foption={TYPE}`` would - render with ``TYPE`` emphasised. + +Options for source files +------------------------ + +.. confval:: exclude_patterns + :type: :code-py:`Sequence[str]` + :default: :code-py:`()` + + A list of `glob-style patterns`_ that should be excluded when looking for + source files. + They are matched against the source file names + relative to the source directory, + using slashes as directory separators on all platforms. + :confval:`exclude_patterns` has priority over :confval:`include_patterns`. + + Example patterns: + + * :code-py:`'library/xml.rst'` -- ignores the ``library/xml.rst`` file + * :code-py:`'library/xml'` -- ignores the ``library/xml`` directory + * :code-py:`'library/xml*'` -- ignores all files and directories starting with + :code-py:`library/xml` + * :code-py:`'**/.git'` -- ignores all ``.git`` directories + * :code-py:`'Thumbs.db'` -- ignores all ``Thumbs.db`` files + + :confval:`exclude_patterns` is also consulted when looking for static files + in :confval:`html_static_path` and :confval:`html_extra_path`. + + .. versionadded:: 1.0 + +.. confval:: include_patterns + :type: :code-py:`Sequence[str]` + :default: :code-py:`('**',)` + + A list of `glob-style patterns`_ that are used to find source files. + They are matched against the source file + names relative to the source directory, + using slashes as directory separators on all platforms. + By default, all files are recursively included from the source directory. + :confval:`exclude_patterns` has priority over :confval:`include_patterns`. + + Example patterns: + + * :code-py:`'**'` -- all files in the source directory and subdirectories, + recursively + * :code-py:`'library/xml'` -- just the ``library/xml`` directory + * :code-py:`'library/xml*'` -- all files and directories starting with + ``library/xml`` + * :code-py:`'**/doc'` -- all ``doc`` directories (this might be useful if + documentation is co-located with source files) .. versionadded:: 5.1 -.. _intl-options: +.. confval:: master_doc + root_doc + :type: :code-py:`str` + :default: :code-py:`'index'` + + Sphinx builds a tree of documents based on the :rst:dir:`toctree` directives + contained within the source files. + This sets the name of the document containing the master ``toctree`` directive, + and hence the root of the entire tree. + Example: -Options for internationalization --------------------------------- + .. code-block:: python -These options influence Sphinx's *Native Language Support*. See the -documentation on :ref:`intl` for details. + master_doc = 'contents' -.. confval:: language + .. versionchanged:: 2.0 + Default is :code-py:`'index'` (previously :code-py:`'contents'`). - The code for the language the docs are written in. Any text automatically - generated by Sphinx will be in that language. Also, Sphinx will try to - substitute individual paragraphs from your documents with the translation - sets obtained from :confval:`locale_dirs`. Sphinx will search - language-specific figures named by :confval:`figure_language_filename` - (e.g. the German version of ``myfigure.png`` will be ``myfigure.de.png`` - by default setting) and substitute them for original figures. In the LaTeX - builder, a suitable language will be selected as an option for the *Babel* - package. Default is ``'en'``. + .. versionadded:: 4.0 + The :confval:`!root_doc` alias. + +.. confval:: source_encoding + :type: :code-py:`str` + :default: :code-py:`'utf-8-sig'` + + The file encoding of all source files. + The recommended encoding is ``'utf-8-sig'``. .. versionadded:: 0.5 - .. versionchanged:: 1.4 +.. confval:: source_suffix + :type: :code-py:`dict[str, str] | Sequence[str] | str` + :default: :code-py:`{'.rst': 'restructuredtext'}` - Support figure substitution + A dictionary mapping the file extensions (suffixes) + of source files to their file types. + Sphinx considers all files files with suffixes in :code-py:`source_suffix` + to be source files. + Example: - .. versionchanged:: 5.0 + .. code-block:: python - Currently supported languages by Sphinx are: + source_suffix = { + '.rst': 'restructuredtext', + '.txt': 'restructuredtext', + '.md': 'markdown', + } - * ``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 + By default, Sphinx only supports the :code-py:`'restructuredtext'` file type. + Further file types can be added with extensions that register different + source file parsers, such as `MyST-Parser`_. + Refer to the extension's documentation to see which file types it supports. -.. confval:: locale_dirs + .. _MyST-Parser: https://myst-parser.readthedocs.io/ - .. versionadded:: 0.5 + If the value is a string or sequence of strings, + Sphinx will consider that they are all :code-py:`'restructuredtext'` files. - Directories in which to search for additional message catalogs (see - :confval:`language`), relative to the source directory. The directories on - this path are searched by the standard :mod:`gettext` module. + .. note:: File extensions must begin with a dot (``'.'``). - Internal messages are fetched from a text domain of ``sphinx``; so if you - add the directory :file:`./locale` to this setting, the message catalogs - (compiled from ``.po`` format using :program:`msgfmt`) must be in - :file:`./locale/{language}/LC_MESSAGES/sphinx.mo`. The text domain of - individual documents depends on :confval:`gettext_compact`. + .. versionchanged:: 1.3 + Support a list of file extensions. - The default is ``['locales']``. + .. versionchanged:: 1.8 + Change to a map of file extensions to file types. - .. note:: The :option:`-v option for sphinx-build command ` - is useful to check the locale_dirs config works as expected. It - emits debug messages if message catalog directory not found. - .. versionchanged:: 1.5 - Use ``locales`` directory as a default value +Options for smart quotes +------------------------ -.. confval:: gettext_allow_fuzzy_translations +.. confval:: smartquotes + :type: :code-py:`bool` + :default: :code-py:`True` - If true, "fuzzy" messages in the message catalogs are used for translation. - The default is ``False``. + If :code-py:`True`, the `Smart Quotes transform`__ + will be used to convert quotation marks and dashes + to typographically correct entities. - .. versionadded:: 4.3 + __ https://docutils.sourceforge.io/docs/user/smartquotes.html -.. confval:: gettext_compact + .. versionadded:: 1.6.6 + Replaces the now-removed :confval:`!html_use_smartypants`. + It applies by default to all builders except ``man`` and ``text`` + (see :confval:`smartquotes_excludes`.) - .. versionadded:: 1.1 + .. note:: - If true, a document's text domain is its docname if it is a top-level - project file and its very base directory otherwise. + A `docutils.conf`__ file located in the :term:`configuration directory` + (or a global :file:`~/.docutils` file) is obeyed unconditionally if it + *deactivates* smart quotes via the corresponding `Docutils option`__. + But if it *activates* them, then :confval:`smartquotes` does prevail. - If set to string, all document's text domain is this string, making all - documents use single text domain. + __ https://docutils.sourceforge.io/docs/user/config.html + __ https://docutils.sourceforge.io/docs/user/config.html#smart-quotes - By default, the document ``markup/code.rst`` ends up in the ``markup`` text - domain. With this option set to ``False``, it is ``markup/code``. +.. confval:: smartquotes_action + :type: :code-py:`str` + :default: :code-py:`'qDe'` + + Customise the Smart Quotes transform. + See below for the permitted codes. + The default :code-py:`'qDe'` educates + normal **q**\ uote characters ``"``, ``'``, + em- and en-**D**\ ashes ``---``, ``--``, + and **e**\ llipses ``...``.. + + :code-py:`'q'` + Convert quotation marks + :code-py:`'b'` + Convert backtick quotation marks + (:literal:`\`\`double''` only) + :code-py:`'B'` + Convert backtick quotation marks + (:literal:`\`\`double''` and :literal:`\`single'`) + :code-py:`'d'` + Convert dashes + (convert ``--`` to em-dashes and ``---`` to en-dashes) + :code-py:`'D'` + Convert dashes (old school) + (convert ``--`` to en-dashes and ``---`` to em-dashes) + :code-py:`'i'` + Convert dashes (inverted old school) + (convert ``--`` to em-dashes and ``---`` to en-dashes) + :code-py:`'e'` + Convert ellipses ``...`` + :code-py:`'w'` + Convert ``'"'`` entities to ``'"'`` - .. versionchanged:: 3.3 - The string value is now accepted. + .. versionadded:: 1.6.6 -.. confval:: gettext_uuid +.. confval:: smartquotes_excludes + :type: :code-py:`dict[str, list[str]]` + :default: :code-py:`{'languages': ['ja'], 'builders': ['man', 'text']}` - If true, Sphinx generates uuid information for version tracking in message - catalogs. It is used for: + Control when the Smart Quotes transform is disabled. + Permitted keys are :code-py:`'builders'` and :code-py:`'languages'`, and + The values are lists of strings. - * Add uid line for each msgids in .pot files. - * Calculate similarity between new msgids and previously saved old msgids. - This calculation takes a long time. + Each entry gives a sufficient condition to ignore the + :confval:`smartquotes` setting and deactivate the Smart Quotes transform. + Example: - If you want to accelerate the calculation, you can use - ``python-levenshtein`` 3rd-party package written in C by using - :command:`pip install python-levenshtein`. + .. code-block:: python - The default is ``False``. + smartquotes_excludes = { + 'languages': ['ja'], + 'builders': ['man', 'text'], + } - .. versionadded:: 1.3 + .. note:: -.. confval:: gettext_location + Currently, in case of invocation of :program:`make` with multiple + targets, the first target name is the only one which is tested against + the :code-py:`'builders'` entry and it decides for all. + Also, a ``make text`` following ``make html`` needs to be issued + in the form ``make text SPHINXOPTS="-E"`` to force re-parsing + of source files, as the cached ones are already transformed. + On the other hand the issue does not arise with + direct usage of :program:`sphinx-build` as it caches + (in its default usage) the parsed source files in per builder locations. - If true, Sphinx generates location information for messages in message - catalogs. + .. hint:: - The default is ``True``. + An alternative way to effectively deactivate (or customise) the + smart quotes for a given builder, for example ``latex``, + is to use ``make`` this way: - .. versionadded:: 1.3 + .. code-block:: console -.. confval:: gettext_auto_build + make latex SPHINXOPTS="-D smartquotes_action=" - If true, Sphinx builds mo file for each translation catalog files. + This can follow some ``make html`` with no problem, in contrast to the + situation from the prior note. - The default is ``True``. + .. versionadded:: 1.6.6 - .. versionadded:: 1.3 -.. confval:: gettext_additional_targets +Options for templating +---------------------- - To specify names to enable gettext extracting and translation applying for - i18n additionally. You can specify below names: +.. confval:: template_bridge + :type: :code-py:`str` + :default: :code-py:`''` - :index: index terms - :literal-block: literal blocks (``::`` annotation and ``code-block`` directive) - :doctest-block: doctest block - :raw: raw content - :image: image/figure uri + A string with the fully-qualified name of a callable (or simply a class) + that returns an instance of :class:`~sphinx.application.TemplateBridge`. + This instance is then used to render HTML documents, + and possibly the output of other builders (currently the changes builder). + (Note that the template bridge must be made theme-aware + if HTML themes are to be used.) + Example: - For example: ``gettext_additional_targets = ['literal-block', 'image']``. + .. code-block:: python - The default is ``[]``. + template_bridge = 'module.CustomTemplateBridge' - .. versionadded:: 1.3 - .. versionchanged:: 4.0 +.. confval:: templates_path + :type: :code-py:`Sequence[str]` + :default: :code-py:`()` + + A list of paths that contain extra templates + (or templates that overwrite builtin/theme-specific templates). + Relative paths are taken as relative to the :term:`configuration directory`. + Example: + + .. code-block:: python - The alt text for image is translated by default. + templates_path = ['.templates'] -.. confval:: figure_language_filename + .. versionchanged:: 1.3 + As these files are not meant to be built, + they are automatically excluded when discovering source files. + + +Options for warning control +--------------------------- + +.. confval:: show_warning_types + :type: :code-py:`bool` + :default: :code-py:`False` + + Add the type of each warning as a suffix to the warning message. + For example, ``WARNING: [...] [index]`` or ``WARNING: [...] [toc.circular]``. + This setting can be useful for determining which warnings types to include + in a :confval:`suppress_warnings` list. + + .. versionadded:: 7.3.0 + +.. confval:: suppress_warnings + :type: :code-py:`Sequence[str]` + :default: :code-py:`()` + + A list of warning codes to suppress arbitrary warning messages. + + By default, Sphinx supports the following warning codes: + + * ``app.add_node`` + * ``app.add_directive`` + * ``app.add_role`` + * ``app.add_generic_role`` + * ``app.add_source_parser`` + * ``config.cache`` + * ``download.not_readable`` + * ``epub.unknown_project_files`` + * ``epub.duplicated_toc_entry`` + * ``i18n.inconsistent_references`` + * ``index`` + * ``image.not_readable`` + * ``ref.term`` + * ``ref.ref`` + * ``ref.numref`` + * ``ref.keyword`` + * ``ref.option`` + * ``ref.citation`` + * ``ref.footnote`` + * ``ref.doc`` + * ``ref.python`` + * ``misc.highlighting_failure`` + * ``toc.circular`` + * ``toc.excluded`` + * ``toc.no_title`` + * ``toc.not_readable`` + * ``toc.secnum`` - 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: + Extensions can also define their own warning types. + Those defined by the first-party ``sphinx.ext`` extensions are: - * ``{root}`` - the filename, including any path component, without the file - extension, e.g. ``dirname/filename`` - * ``{path}`` - the directory path component of the filename, with a trailing - slash if non-empty, e.g. ``dirname/`` - * ``{docpath}`` - the directory path component for the current document, with - a trailing slash if non-empty. - * ``{basename}`` - the filename without the directory path or file extension - components, e.g. ``filename`` - * ``{ext}`` - the file extension, e.g. ``.png`` - * ``{language}`` - the translation language, e.g. ``en`` + * ``autodoc`` + * ``autodoc.import_object`` + * ``autosectionlabel.`` + * ``autosummary`` + * ``intersphinx.external`` - For example, setting this to ``{path}{language}/{basename}{ext}`` will - expand to ``dirname/en/filename.png`` instead. + You can choose from these types. You can also give only the first + component to exclude all warnings attached to it. .. versionadded:: 1.4 .. versionchanged:: 1.5 - Added ``{path}`` and ``{basename}`` tokens. - - .. versionchanged:: 3.2 - Added ``{docpath}`` token. - -.. confval:: translation_progress_classes - - Control which, if any, classes are added to indicate translation progress. - This setting would likely only be used by translators of documentation, - in order to quickly indicate translated and untranslated content. - - * ``True``: add ``translated`` and ``untranslated`` classes - to all nodes with translatable content. - * ``translated``: only add the ``translated`` class. - * ``untranslated``: only add the ``untranslated`` class. - * ``False``: do not add any classes to indicate translation progress. - - Defaults to ``False``. - - .. versionadded:: 7.1 + Added ``misc.highlighting_failure`` -.. _math-options: + .. versionchanged:: 1.5.1 + Added ``epub.unknown_project_files`` -Options for Math ----------------- + .. versionchanged:: 1.6 + Added ``ref.footnote`` -These options influence Math notations. + .. versionchanged:: 2.1 + Added ``autosectionlabel.`` -.. confval:: math_number_all + .. versionchanged:: 3.3.0 + Added ``epub.duplicated_toc_entry`` - Set this option to ``True`` if you want all displayed math to be numbered. - The default is ``False``. + .. versionchanged:: 4.3 + Added ``toc.excluded`` and ``toc.not_readable`` -.. confval:: math_eqref_format + .. versionadded:: 4.5 + Added ``i18n.inconsistent_references`` - A string used for formatting the labels of references to equations. - The ``{number}`` place-holder stands for the equation number. + .. versionadded:: 7.1 + Added ``index``. - Example: ``'Eq.{number}'`` gets rendered as, for example, ``Eq.10``. + .. versionadded:: 7.3 + Added ``config.cache``. -.. confval:: math_numfig + .. versionadded:: 7.3 + Added ``toc.no_title``. - If ``True``, displayed math equations are numbered across pages when - :confval:`numfig` is enabled. The :confval:`numfig_secnum_depth` setting - is respected. The :rst:role:`eq`, not :rst:role:`numref`, role - must be used to reference equation numbers. Default is ``True``. - .. versionadded:: 1.7 +Builder options +=============== .. _html-options: @@ -1073,186 +1418,243 @@ These options influence Math notations. Options for HTML output ----------------------- -These options influence HTML as well as HTML Help output, and other builders -that use Sphinx's HTMLWriter class. +These options influence HTML output. +Various other builders are derived from the HTML output, +and also make use of these options. .. confval:: html_theme + :type: :code-py:`str` + :default: :code-py:`'alabaster'` - The "theme" that the HTML output should use. See the :doc:`section about - theming `. The default is ``'alabaster'``. + The theme for HTML output. + See the :doc:`HTML theming section `. .. versionadded:: 0.6 + .. versionchanged:: 1.3 + The default theme is now :code-py:`'alabaster'`. .. confval:: html_theme_options + :type: :code-py:`dict[str, Any]` + :default: :code-py:`{}` - A dictionary of options that influence the look and feel of the selected - theme. These are theme-specific. For the options understood by the builtin - themes, see :ref:`this section `. + A dictionary of options that influence the + look and feel of the selected theme. + These are theme-specific. + The options understood by the :ref:`builtin themes + ` are described :ref:`here `. .. versionadded:: 0.6 .. confval:: html_theme_path + :type: :code-py:`list[str]` + :default: :code-py:`[]` - 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. + A list of paths that contain custom themes, + either as subdirectories or as zip files. + Relative paths are taken as relative to the :term:`configuration directory`. .. versionadded:: 0.6 .. confval:: html_style + :type: :code-py:`Sequence[str] | str` + :default: :code-py:`()` - The style sheet to use for HTML pages. A file of that name must exist - either in Sphinx's :file:`static/` path, or in one of the custom paths given - in :confval:`html_static_path`. Default is the stylesheet given by the - selected theme. If you only want to add or override a few things compared - to the theme's stylesheet, use CSS ``@import`` to import the theme's - stylesheet. + Stylesheets to use for HTML pages. + The stylesheet given by the selected theme is used by default + A file of that name must exist either in Sphinx's :file:`static/` path + or in one of the custom paths given in :confval:`html_static_path`. + If you only want to add or override a few things from the theme, + use CSS ``@import`` to import the theme's stylesheet. + + .. versionchanged:: 5.1 + The value can be a iterable of strings. .. confval:: html_title + :type: :code-py:`str` + :default: :samp:`'{project} {release} documentation'` The "title" for HTML documentation generated with Sphinx's own templates. - This is appended to the ```` tag of individual pages, and used in the - navigation bar as the "topmost" element. It defaults to :samp:`'{<project>} - v{<revision>} documentation'`. + This is appended to the ``<title>`` tag of individual pages, + and used in the navigation bar as the "topmost" element. .. confval:: html_short_title + :type: :code-py:`str` + :default: The value of **html_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 - :confval:`html_title`. + A shorter "title" for HTML documentation. + This is used for links in the header and in the HTML Help documentation. .. versionadded:: 0.4 .. confval:: html_baseurl + :type: :code-py:`str` + :default: :code-py:`''` - The base URL which points to the root of the HTML documentation. It is used - to indicate the location of document using `The Canonical Link Relation`_. - Default: ``''``. - - .. _The Canonical Link Relation: https://datatracker.ietf.org/doc/html/rfc6596 + The base URL which points to the root of the HTML documentation. + It is used to indicate the location of document using + :rfc:`the Canonical Link Relation <6596>`. .. versionadded:: 1.8 .. confval:: html_codeblock_linenos_style + :type: :code-py:`'inline' | 'table'` + :default: :code-py:`'inline'` The style of line numbers for code-blocks. - * ``'table'`` -- display line numbers using ``<table>`` tag - * ``'inline'`` -- display line numbers using ``<span>`` tag (default) + :code-py:`'table'` + Display line numbers using ``<table>`` tag + :code-py:`'inline'` + Display line numbers using ``<span>`` tag .. versionadded:: 3.2 .. versionchanged:: 4.0 - - It defaults to ``'inline'``. - + It defaults to :code-py:`'inline'`. .. deprecated:: 4.0 .. confval:: html_context + :type: :code-py:`dict[str, Any]` + :default: :code-py:`{}` - A dictionary of values to pass into the template engine's context for all - pages. Single values can also be put in this dictionary using the - :option:`-A <sphinx-build -A>` command-line option of ``sphinx-build``. + 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 + :program:`sphinx-build`'s :option:`--html-define + <sphinx-build --html-define>` command-line option. .. versionadded:: 0.5 .. confval:: html_logo + :type: :code-py:`str` + :default: :code-py:`''` - If given, this must be the name of an image file (path relative to the - :term:`configuration directory`) that is the logo of the docs, or URL that - points an image file for the logo. It is placed at the top of the sidebar; - its width should therefore not exceed 200 pixels. Default: ``None``. + If given, this must be the name of an image file + (path relative to the :term:`configuration 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. .. versionadded:: 0.4.1 - The image file will be copied to the ``_static`` directory of the output - HTML, but only if the file does not already exist there. - + The image file will be copied to the ``_static`` directory, + but only if the file does not already exist there. .. versionchanged:: 4.0 - Also accepts the URL for the logo file. + Also accepts a URL. .. confval:: html_favicon + :type: :code-py:`str` + :default: :code-py:`''` + + If given, this must be the name of an image file + (path relative to the :term:`configuration directory`) + that is the favicon_ 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 in + the PNG, SVG, GIF, or ICO file formats. - If given, this must be the name of an image file (path relative to the - :term:`configuration directory`) that is the favicon of the docs, or URL that - points an image file for the favicon. Modern browsers use this as the icon - for tabs, windows and bookmarks. It should be a Windows-style icon file - (``.ico``), which is 16x16 or 32x32 pixels large. Default: ``None``. + .. _favicon: https://developer.mozilla.org/en-US/ + docs/Web/HTML/Attributes/rel#icon + + Example: + + .. code-block:: python + + html_favicon = 'static/favicon.png' .. versionadded:: 0.4 - The image file will be copied to the ``_static`` directory of the output - HTML, but only if the file does not already exist there. + The image file will be copied to the ``_static``, + but only if the file does not already exist there. .. versionchanged:: 4.0 Also accepts the URL for the favicon. .. confval:: html_css_files + :type: :code-py:`Sequence[str | tuple[str, dict[str, str]]]` + :default: :code-py:`[]` + + A list of CSS files. + The entry must be a *filename* string + or a tuple containing the *filename* string and the *attributes* dictionary. + The *filename* must be relative to the :confval:`html_static_path`, + or a full URI with scheme like :code-py:`'https://example.org/style.css'`. + The *attributes* dictionary is used for the ``<link>`` tag's attributes. - A list of CSS files. The entry must be a *filename* string or a tuple - containing the *filename* string and the *attributes* dictionary. The - *filename* must be relative to the :confval:`html_static_path`, or a full URI - with scheme like ``https://example.org/style.css``. The *attributes* is used - for attributes of ``<link>`` tag. It defaults to an empty list. + Example: - Example:: + .. code-block:: python - html_css_files = ['custom.css', - 'https://example.com/css/custom.css', - ('print.css', {'media': 'print'})] + html_css_files = [ + 'custom.css', + 'https://example.com/css/custom.css', + ('print.css', {'media': 'print'}), + ] - As a special attribute, *priority* can be set as an integer to load the CSS - file at an earlier or lazier step. For more information, refer - :meth:`.Sphinx.add_css_file()`. + The special attribute *priority* can be set as an integer + to load the CSS file at an earlier or later step. + For more information, refer to :meth:`.Sphinx.add_css_file()`. .. versionadded:: 1.8 .. versionchanged:: 3.5 - - Support priority attribute + Support the *priority* attribute .. confval:: html_js_files + :type: :code-py:`Sequence[str | tuple[str, dict[str, str]]]` + :default: :code-py:`[]` - A list of JavaScript *filename*. The entry must be a *filename* string or a - tuple containing the *filename* string and the *attributes* dictionary. The - *filename* must be relative to the :confval:`html_static_path`, or a full - URI with scheme like ``https://example.org/script.js``. The *attributes* is - used for attributes of ``<script>`` tag. It defaults to an empty list. + A list of JavaScript files. + The entry must be a *filename* string + or a tuple containing the *filename* string and the *attributes* dictionary. + The *filename* must be relative to the :confval:`html_static_path`, + or a full URI with scheme like :code-py:`'https://example.org/script.js'`. + The *attributes* dictionary is used for the ``<script>`` tag's attributes. + + Example: - Example:: + .. code-block:: python - html_js_files = ['script.js', - 'https://example.com/scripts/custom.js', - ('custom.js', {'async': 'async'})] + html_js_files = [ + 'script.js', + 'https://example.com/scripts/custom.js', + ('custom.js', {'async': 'async'}), + ] - As a special attribute, *priority* can be set as an integer to load the - JavaScript file at an earlier or lazier step. For more information, refer - :meth:`.Sphinx.add_js_file()`. + As a special attribute, *priority* can be set as an integer + to load the JavaScript file at an earlier or later step. + For more information, refer to :meth:`.Sphinx.add_js_file()`. .. versionadded:: 1.8 .. versionchanged:: 3.5 - - Support priority attribute + Support the *priority* attribute .. confval:: html_static_path + :type: :code-py:`list[str]` + :default: :code-py:`[]` - A list of paths that contain custom static files (such as style - sheets or script files). Relative paths are taken as relative to - the configuration directory. They are copied to the output's - :file:`_static` directory after the theme's static files, so a file - named :file:`default.css` will overwrite the theme's - :file:`default.css`. + A list of paths that contain custom static files + (such as style sheets or script files). + Relative paths are taken as relative to the :term:`configuration directory`. + They are copied to the output's :file:`_static` directory + after the theme's static files, + so a file named :file:`default.css` will overwrite + the theme's :file:`default.css`. - As these files are not meant to be built, they are automatically excluded - from source files. + As these files are not meant to be built, + they are automatically excluded from source files. .. note:: - For security reasons, dotfiles under ``html_static_path`` will - not be copied. If you would like to copy them intentionally, please - add each filepath to this setting:: + For security reasons, dotfiles under :confval:`!html_static_path` + will not be copied. + If you would like to copy them intentionally, + explicitly add each file to this setting: + + .. code-block:: python - html_static_path = ['_static', '_static/.htaccess'] + html_static_path = ['_static', '_static/.htaccess'] - Another way to do that, you can also use - :confval:`html_extra_path`. It allows to copy dotfiles under - the directories. + An alternative approach is to use :confval:`html_extra_path`, + which allows copying dotfiles under the directories. .. versionchanged:: 0.4 The paths in :confval:`html_static_path` can now contain subdirectories. @@ -1265,244 +1667,298 @@ that use Sphinx's HTMLWriter class. files. .. confval:: html_extra_path + :type: :code-py:`list[str]` + :default: :code-py:`[]` A list of paths that contain extra files not directly related to - the documentation, such as :file:`robots.txt` or :file:`.htaccess`. - Relative paths are taken as relative to the configuration - directory. They are copied to the output directory. They will - overwrite any existing file of the same name. + the documentation, + such as :file:`robots.txt` or :file:`.htaccess`. + Relative paths are taken as relative to the :term:`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. + As these files are not meant to be built, + they are automatically excluded from source files. .. versionadded:: 1.2 .. versionchanged:: 1.4 - The dotfiles in the extra directory will be copied to the output - directory. And it refers :confval:`exclude_patterns` on copying extra + The dotfiles in the extra directory will be copied + to the output directory. + And it refers :confval:`exclude_patterns` on copying extra files and directories, and ignores if path matches to patterns. .. confval:: html_last_updated_fmt + :type: :code-py:`str` + :default: :code-py:`'%b %d, %Y'` - If this is not None, a 'Last updated on:' timestamp is inserted - at every page bottom, using the given :func:`~time.strftime` format. - The empty string is equivalent to ``'%b %d, %Y'`` (or a - locale-dependent equivalent). - -.. confval:: html_use_smartypants - - If true, quotes and dashes are converted to typographically correct - entities. Default: ``True``. - - .. deprecated:: 1.6 - To disable smart quotes, use rather :confval:`smartquotes`. + If set, a 'Last updated on:' timestamp is inserted into the page footer + using the given :func:`~time.strftime` format. + The empty string is equivalent to :code-py:`'%b %d, %Y'` + (or a locale-dependent equivalent). .. confval:: html_permalinks + :type: :code-py:`bool` + :default: :code-py:`True` Add link anchors for each heading and description environment. - Default: ``True``. .. versionadded:: 3.5 .. confval:: html_permalinks_icon + :type: :code-py:`str` + :default: :code-py:`'¶'` (the paragraph sign) Text for link anchors for each heading and description environment. - HTML entities and Unicode are allowed. Default: a paragraph sign; ``¶`` + HTML entities and Unicode are allowed. .. versionadded:: 3.5 .. confval:: html_sidebars + :type: :code-py:`dict[str, Sequence[str]]` + :default: :code-py:`{}` - 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.) + A dictionary defining custom sidebar templates, + mapping document names to template names. - The values can be either lists or single strings. + The keys can contain `glob-style patterns`_, + 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.) - * If a value is a list, it specifies the complete list of sidebar templates - to include. If all or some of the default sidebars are to be included, - they must be put into this list as well. - - The default sidebars (for documents that don't match any pattern) are - defined by theme itself. Builtin themes are using these templates by - default: ``['localtoc.html', 'relations.html', 'sourcelink.html', - 'searchbox.html']``. - - * If a value is a single string, it specifies a custom sidebar to be added - between the ``'sourcelink.html'`` and ``'searchbox.html'`` entries. This - is for compatibility with Sphinx versions before 1.0. - - .. deprecated:: 1.7 + Each value must be a list of strings which specifies + the complete list of sidebar templates to include. + If all or some of the default sidebars are to be included, + they must be put into this list as well. - a single string value for ``html_sidebars`` will be removed in 2.0 + The default sidebars (for documents that don't match any pattern) are + defined by theme itself. + The builtin themes use these templates by default: + :code-py:`'localtoc.html'`, :code-py:`'relations.html'`, + :code-py:`'sourcelink.html'`, and :code-py:`'searchbox.html'`. - Builtin sidebar templates that can be rendered are: + The bundled first-party sidebar templates that can be rendered are: * **localtoc.html** -- a fine-grained table of contents of the current document * **globaltoc.html** -- a coarse-grained table of contents for the whole documentation set, collapsed * **relations.html** -- two links to the previous and next documents - * **sourcelink.html** -- a link to the source of the current document, if - enabled in :confval:`html_show_sourcelink` + * **sourcelink.html** -- a link to the source of the current document, + if enabled in :confval:`html_show_sourcelink` * **searchbox.html** -- the "quick search" box - Example:: + Example: + + .. code-block:: python html_sidebars = { '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'], - 'using/windows': ['windowssidebar.html', 'searchbox.html'], + 'using/windows': ['windows-sidebar.html', 'searchbox.html'], } - This will render the custom template ``windowssidebar.html`` and the quick + This will render the custom template ``windows-sidebar.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). + Note that this value only has no effect if + the chosen theme does not possess a sidebar, + like the builtin **scrolls** and **haiku** themes. + .. versionadded:: 1.0 The ability to use globbing keys and to specify multiple sidebars. - Note that this value only has no effect if the chosen theme does not possess - a sidebar, like the builtin **scrolls** and **haiku** themes. + .. deprecated:: 1.7 + A single string value for :confval:`!html_sidebars` will be removed. + + .. versionchanged:: 2.0 + :confval:`!html_sidebars` must be a list of strings, + and no longer accepts a single string value. .. confval:: html_additional_pages + :type: :code-py:`dict[str, str]` + :default: :code-py:`{}` + + Additional templates that should be rendered to HTML pages, + must be a dictionary that maps document names to template names. - Additional templates that should be rendered to HTML pages, must be a - dictionary that maps document names to template names. + Example: - Example:: + .. code-block:: python html_additional_pages = { - 'download': 'customdownload.html', + 'download': 'custom-download.html.jinja', } - This will render the template ``customdownload.html`` as the page - ``download.html``. + This will render the template :file:`custom-download.html.jinja` + as the page :file:`download.html`. .. confval:: html_domain_indices + :type: :code-py:`bool | Sequence[str]` + :default: :code-py:`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. Default is - ``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 bool or a list of index names that should be generated. + 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: + + .. code-block:: python + + html_domain_indices = { + 'py-modindex', + } + .. versionadded:: 1.0 + .. versionchanged:: 7.4 + Permit and prefer a set type. .. confval:: html_use_index + :type: :code-py:`bool` + :default: :code-py:`True` - If true, add an index to the HTML documents. Default is ``True``. + Controls if an index is added to the HTML documents. .. versionadded:: 0.4 .. confval:: html_split_index + :type: :code-py:`bool` + :default: :code-py:`False` - 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``. + Generates two versions of the index: + once as a single page with all the entries, + and once as one page per starting letter. .. versionadded:: 0.4 .. confval:: html_copy_source + :type: :code-py:`bool` + :default: :code-py:`True` - If true, the reST sources are included in the HTML build as - :file:`_sources/{name}`. The default is ``True``. + If True, the reStructuredText sources are included in the HTML build as + :file:`_sources/{docname}`. .. confval:: html_show_sourcelink + :type: :code-py:`bool` + :default: :code-py:`True` - If true (and :confval:`html_copy_source` is true as well), links to the - reST sources will be added to the sidebar. The default is ``True``. + If True (and :confval:`html_copy_source` is true as well), + links to the reStructuredText sources will be added to the sidebar. .. versionadded:: 0.6 .. confval:: html_sourcelink_suffix + :type: :code-py:`str` + :default: :code-py:`'.txt'` - Suffix to be appended to source links (see :confval:`html_show_sourcelink`), - unless they have this suffix already. Default is ``'.txt'``. + The suffix to append to source links + (see :confval:`html_show_sourcelink`), + unless files they have this suffix already. .. versionadded:: 1.5 .. confval:: html_use_opensearch + :type: :code-py:`str` + :default: :code-py:`''` If nonempty, an `OpenSearch <https://github.com/dewitt/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 ``''``. + 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. :code-py:`'https://docs.python.org'`. + + .. versionadded:: 0.2 .. confval:: html_file_suffix + :type: :code-py:`str` + :default: :code-py:`'.html'` - This is the file name suffix for generated HTML files, if set to a :obj:`str` - value. If left to the default ``None``, the suffix will be ``".html"``. + The file name suffix (file extension) for generated HTML files. .. versionadded:: 0.4 .. confval:: html_link_suffix + :type: :code-py:`str` + :default: The value of **html_file_suffix** - Suffix for generated links to HTML files. The default is whatever - :confval:`html_file_suffix` is set to; it can be set differently (e.g. to - support different web server setups). + The suffix for generated links to HTML files. + Intended to support more esoteric server setups. .. versionadded:: 0.6 .. confval:: html_show_copyright + :type: :code-py:`bool` + :default: :code-py:`True` - If true, "(C) Copyright ..." is shown in the HTML footer. Default is - ``True``. + If True, "© Copyright ..." is shown in the HTML footer, + with the value or values from :confval:`copyright`. .. versionadded:: 1.0 .. confval:: html_show_search_summary + :type: :code-py:`bool` + :default: :code-py:`True` - If true, the text around the keyword is shown as summary of each search result. - Default is ``True``. + Show a summary of the search result, i.e., the text around the keyword. .. versionadded:: 4.5 .. confval:: html_show_sphinx + :type: :code-py:`bool` + :default: :code-py:`True` + + Add "Created using Sphinx_" to the HTML footer. - If true, "Created using Sphinx" is shown in the HTML footer. Default is - ``True``. + .. _Sphinx: https://www.sphinx-doc.org/ .. versionadded:: 0.4 .. confval:: html_output_encoding + :type: :code-py:`str` + :default: :code-py:`'utf-8'` - 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. + Encoding of HTML output files. + This encoding name must both be a valid Python encoding name + and a valid HTML ``charset`` value. .. versionadded:: 1.0 .. confval:: html_compact_lists + :type: :code-py:`bool` + :default: :code-py:`True` - If true, a list all whose items consist of a single paragraph and/or a + 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``. + ``<p>`` element for any of its items. This is standard docutils behaviour. + Default: :code-py:`True`. .. versionadded:: 1.0 .. confval:: html_secnumber_suffix + :type: :code-py:`str` + :default: :code-py:`'. '` - Suffix for section numbers. Default: ``". "``. Set to ``" "`` to suppress - the final dot on section numbers. + Suffix for section numbers in HTML output. + Set to :code-py:`' '` to suppress the final dot on section numbers. .. versionadded:: 1.0 .. confval:: html_search_language + :type: :code-py:`str` + :default: The value of **language** - Language to be used for generating the HTML full-text search index. This - defaults to the global language selected with :confval:`language`. If there - is no support for this language, ``"en"`` is used which selects the English - language. + Language to be used for generating the HTML full-text search index. + This defaults to the global language selected with :confval:`language`. + English (:code-py:`'en'`) is used as a fall-back option + if there is no support for this language. - Support is present for these languages: + Support exists for the following languages: * ``da`` -- Danish * ``nl`` -- Dutch @@ -1522,98 +1978,101 @@ that use Sphinx's HTMLWriter class. * ``tr`` -- Turkish * ``zh`` -- Chinese - .. admonition:: Accelerating build speed + .. tip:: Accelerating build speed Each language (except Japanese) provides its own stemming algorithm. - Sphinx uses a Python implementation by default. You can use a C - implementation to accelerate building the index file. + 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 running + :command:`pip install PyStemmer`. - * `PorterStemmer <https://pypi.org/project/PorterStemmer/>`_ (``en``) - * `PyStemmer <https://pypi.org/project/PyStemmer/>`_ (all languages) + .. _PyStemmer: https://pypi.org/project/PyStemmer/ .. versionadded:: 1.1 - With support for ``en`` and ``ja``. + Support English (``en``) and Japanese (``ja``). .. versionchanged:: 1.3 Added additional languages. .. confval:: html_search_options + :type: :code-py:`dict[str, str]` + :default: :code-py:`{}` - A dictionary with options for the search language support, empty by default. + A dictionary with options for the search language support. The meaning of these options depends on the language selected. - - The English support has no options. - - The Japanese support has these options: - - :type: - _`type` is dotted module path string to specify Splitter implementation - which should be derived from :class:`!sphinx.search.ja.BaseSplitter`. If - not specified or ``None`` is specified, - ``'sphinx.search.ja.DefaultSplitter'`` will be used. - - You can choose from these modules: - - :'sphinx.search.ja.DefaultSplitter': - TinySegmenter algorithm. This is default splitter. - :'sphinx.search.ja.MecabSplitter': - MeCab binding. To use this splitter, 'mecab' python binding or dynamic - link library ('libmecab.so' for linux, 'libmecab.dll' for windows) is - required. - :'sphinx.search.ja.JanomeSplitter': - Janome binding. To use this splitter, - `Janome <https://pypi.org/project/Janome/>`_ is required. - - .. deprecated:: 1.6 - ``'mecab'``, ``'janome'`` and ``'default'`` is deprecated. - To keep compatibility, ``'mecab'``, ``'janome'`` and ``'default'`` are - also acceptable. - - Other option values depend on splitter value which you choose. - - Options for ``'mecab'``: - :dic_enc: - _`dic_enc option` is the encoding for the MeCab algorithm. - :dict: - _`dict option` is the dictionary to use for the MeCab algorithm. - :lib: - _`lib option` is the library name for finding the MeCab library via - ctypes if the Python binding is not installed. - - For example:: - - html_search_options = { - 'type': 'mecab', - 'dic_enc': 'utf-8', - 'dict': '/path/to/mecab.dic', - 'lib': '/path/to/libmecab.so', - } - - Options for ``'janome'``: - :user_dic: - _`user_dic option` is the user dictionary file path for Janome. - :user_dic_enc: - _`user_dic_enc option` is the encoding for the user dictionary file - specified by ``user_dic`` option. Default is 'utf8'. + Currently, only Japanese and Chinese support options. + + :Japanese: + ``type`` -- the type of the splitter to use. + The other options depend on the splitter used. + + :code-py:`'sphinx.search.ja.DefaultSplitter'` + The TinySegmenter algorithm, used by default. + :code-py:`'sphinx.search.ja.MecabSplitter'`: + The MeCab binding + To use this splitter, the 'mecab' python binding + or dynamic link library + ('libmecab.so' for Linux, 'libmecab.dll' for Windows) is required. + :code-py:`'sphinx.search.ja.JanomeSplitter'`: + The Janome binding. + To use this splitter, + `Janome <https://pypi.org/project/Janome/>`_ is required. + + + .. deprecated:: 1.6 + ``'mecab'``, ``'janome'`` and ``'default'`` is deprecated. + To keep compatibility, + ``'mecab'``, ``'janome'`` and ``'default'`` are also acceptable. + + Options for :code-py:`'mecab'`: + :dic_enc: + _`dic_enc option` is the encoding for the MeCab algorithm. + :dict: + _`dict option` is the dictionary to use for the MeCab algorithm. + :lib: + _`lib option` is the library name for finding the MeCab library + via ``ctypes`` if the Python binding is not installed. + + For example: + + .. code-block:: python + + html_search_options = { + 'type': 'mecab', + 'dic_enc': 'utf-8', + 'dict': '/path/to/mecab .dic', + 'lib': '/path/to/libmecab.so', + } + + Options for :code-py:`'janome'`: + :user_dic: + _`user_dic option` is the user dictionary file path for Janome. + :user_dic_enc: + _`user_dic_enc option` is the encoding for + the user dictionary file specified by ``user_dic`` option. + Default is 'utf8'. + + :Chinese: + ``dict`` + The ``jieba`` dictionary path for using a custom dictionary. .. versionadded:: 1.1 .. versionchanged:: 1.4 - html_search_options for Japanese is re-organized and any custom splitter - can be used by `type`_ settings. - - The Chinese support has these options: - - * ``dict`` -- the ``jieba`` dictionary path if want to use - custom dictionary. + Allow any custom splitter in the *type* setting for Japanese. .. confval:: html_search_scorer + :type: :code-py:`str` + :default: :code-py:`''` - The name of a JavaScript file (relative to the configuration directory) that - implements a search results scorer. If empty, the default will be used. + The name of a JavaScript file + (relative to the :term:`configuration 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 the ``score()`` function for more granular control. + and may optionally define the :code-js:`score()` function + for more granular control. .. code-block:: javascript @@ -1651,54 +2110,59 @@ that use Sphinx's HTMLWriter class. .. versionadded:: 1.2 .. confval:: html_scaled_image_link + :type: :code-py:`bool` + :default: :code-py:`True` + + Link images that have been resized with a + scale option (*scale*, *width*, or *height*) + to their original full-resolution image. + This will not overwrite any link given by the *target* option + on the the :dudir:`image` directive, if present. - If true, image itself links to the original image if it doesn't have - 'target' option or scale related options: 'scale', 'width', 'height'. - The default is ``True``. + .. tip:: - Document authors can disable this feature manually with giving - ``no-scaled-link`` class to the image: + To disable this feature on a per-image basis, + add the ``no-scaled-link`` class to the image directive: - .. code-block:: rst + .. code-block:: rst - .. image:: sphinx.png - :scale: 50% - :class: no-scaled-link + .. image:: sphinx.png + :scale: 50% + :class: no-scaled-link .. versionadded:: 1.3 .. versionchanged:: 3.0 - - It is disabled for images having ``no-scaled-link`` class + Images with the ``no-scaled-link`` class will not be linked. .. confval:: html_math_renderer + :type: :code-py:`str` + :default: :code-py:`'mathjax'` - The name of math_renderer extension for HTML output. The default is - ``'mathjax'``. + The maths renderer to use for HTML output. + The bundled renders are *mathjax* and *imgmath*. + You must also load the relevant extension in :confval:`extensions`. .. versionadded:: 1.8 -.. confval:: html_experimental_html5_writer - - Output is processed with HTML5 writer. Default is ``False``. - - .. versionadded:: 1.6 - - .. deprecated:: 2.0 - -.. confval:: html4_writer - - Output is processed with HTML4 writer. Default is ``False``. Options for Single HTML output ------------------------------- +These options influence Single HTML output. +This builder derives from the HTML builder, +so the HTML options also apply where appropriate. + .. confval:: singlehtml_sidebars + :type: :code-py:`dict[str, Sequence[str]]` + :default: The value of **html_sidebars** - Custom sidebar templates, must be a dictionary that maps document names to - template names. And it only allows a key named ``'index'``. All other keys - are ignored. For more information, refer to :confval:`html_sidebars`. By - default, it is same as :confval:`html_sidebars`. + A dictionary defining custom sidebar templates, + mapping document names to template names. + + This has the same effect as :confval:`html_sidebars`, + but the only permitted key is :code-py:`'index'`, + and all other keys are ignored. .. _htmlhelp-options: @@ -1706,20 +2170,31 @@ Options for Single HTML output 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. + .. confval:: htmlhelp_basename + :type: :code-py:`str` + :default: :code-py:`'{project}doc'` - Output file base name for HTML help builder. Default is ``'pydoc'``. + Output file base name for HTML help builder. + The default is the :confval:`project name <project>` + with spaces removed and ``doc`` appended. .. confval:: htmlhelp_file_suffix + :type: :code-py:`str` + :default: :code-py:`'.html'` - This is the file name suffix for generated HTML help files. The - default is ``".html"``. + This is the file name suffix for generated HTML help files. .. versionadded:: 2.0 .. confval:: htmlhelp_link_suffix + :type: :code-py:`str` + :default: The value of **htmlhelp_file_suffix** - Suffix for generated links to HTML files. The default is ``".html"``. + Suffix for generated links to HTML files. .. versionadded:: 2.0 @@ -1731,26 +2206,35 @@ Options for Apple Help output .. versionadded:: 1.3 -These options influence the Apple Help output. This builder derives from the -HTML builder, so the HTML options also apply where appropriate. +These options influence Apple Help output. +This builder derives from the HTML builder, +so the HTML options also apply where appropriate. .. note:: - Apple Help output will only work on Mac OS X 10.6 and higher, as it - requires the :program:`hiutil` and :program:`codesign` command line tools, - neither of which are Open Source. + Apple Help output will only work on Mac OS X 10.6 and higher, + as it requires the :program:`hiutil` and :program:`codesign` + command-line tools, neither of which are Open Source. You can disable the use of these tools using - :confval:`applehelp_disable_external_tools`, but the result will not be a - valid help book until the indexer is run over the ``.lproj`` folders within - the bundle. + :confval:`applehelp_disable_external_tools`, + but the result will not be a valid help book + until the indexer is run over the ``.lproj`` directories within the bundle. + + .. TODO: Is this warning still relevant as of 2024-07? + Needs updating by someone with a Mac. .. confval:: applehelp_bundle_name + :type: :code-py:`str` + :default: The value of **project** - The basename for the Apple Help Book. Defaults to the :confval:`project` - name. + The basename for the Apple Help Book. + The default is the :confval:`project name <project>` + with spaces removed. .. confval:: applehelp_bundle_id + :type: :code-py:`str` + :default: :code-py:`None` The bundle ID for the help book bundle. @@ -1758,388 +2242,509 @@ HTML builder, so the HTML options also apply where appropriate. You *must* set this value in order to generate Apple Help. -.. confval:: applehelp_dev_region +.. confval:: applehelp_bundle_version + :type: :code-py:`str` + :default: :code-py:`'1'` - The development region. Defaults to ``'en-us'``, which is Apple’s - recommended setting. + The bundle version, as a string. -.. confval:: applehelp_bundle_version +.. confval:: applehelp_dev_region + :type: :code-py:`str` + :default: :code-py:`'en-us'` - The bundle version (as a string). Defaults to ``'1'``. + The development region. + Defaults to Apple’s recommended setting, :code-py:`'en-us'`. .. confval:: applehelp_icon + :type: :code-py:`str` + :default: :code-py:`None` - 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. + Path to the help bundle icon file or :code-py:`None` for no icon. + According to Apple's documentation, + this should be a 16-by-16 pixel version of the application's icon + with a transparent background, saved as a PNG file. .. confval:: applehelp_kb_product + :type: :code-py:`str` + :default: :samp:`'{project}-{release}'` - The product tag for use with :confval:`applehelp_kb_url`. Defaults to - :samp:`'{<project>}-{<release>}'`. + The product tag for use with :confval:`applehelp_kb_url`. .. confval:: applehelp_kb_url + :type: :code-py:`str` + :default: :code-py:`None` The URL for your knowledgebase server, e.g. ``https://example.com/kbsearch.py?p='product'&q='query'&l='lang'``. - Help Viewer will replace the values ``'product'``, ``'query'`` and - ``'lang'`` at runtime with the contents of :confval:`applehelp_kb_product`, - the text entered by the user in the search box and the user's system - language respectively. + At runtime, Help Viewer will replace + ``'product'`` with the contents of :confval:`applehelp_kb_product`, + ``'query'`` with the text entered by the user in the search box, + and ``'lang'`` with the user's system language. - Defaults to ``None`` for no remote search. + Set this to to :code-py:`None` to disable remote search. .. confval:: applehelp_remote_url + :type: :code-py:`str` + :default: :code-py:`None` - 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. + The URL for remote content. + You can place a copy of your Help Book's ``Resources`` directory + 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``. + For example, 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. + Set this to to :code-py:`None` for no remote content. .. confval:: applehelp_index_anchors + :type: :code-py:`bool` + :default: :code-py:`False` - 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. + Tell the help indexer to index anchors in the generated HTML. + This can be useful for jumping to a particular topic + using the ``AHLookupAnchor`` function + or the ``openHelpAnchor:inBook:`` method in your code. + It also allows you to use ``help:anchor`` URLs; + see the Apple documentation for more information on this topic. .. confval:: applehelp_min_term_length + :type: :code-py:`str` + :default: :code-py:`None` - Controls the minimum term length for the help indexer. Defaults to - ``None``, which means the default will be used. + Controls the minimum term length for the help indexer. + If :code-py:`None`, use the default length. .. confval:: applehelp_stopwords + :type: :code-py:`str` + :default: The value of **language** - 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. + Either a language specification (to use the built-in stopwords), + or the path to a stopwords plist, + or :code-py:`None` if you do not want to use stopwords. The default stopwords plist can be found at - ``/usr/share/hiutil/Stopwords.plist`` and contains, at time of writing, - stopwords for the following languages: - - ========= ==== - Language Code - ========= ==== - English en - German de - Spanish es - French fr - Swedish sv - Hungarian hu - Italian it - ========= ==== - - Defaults to :confval:`language`, or if that is not set, to ``'en'``. + ``/usr/share/hiutil/Stopwords.plist`` + and contains, at time of writing, stopwords for the following languages: -.. confval:: applehelp_locale + * German (``de``) + * English (``en``) + * Spanish (``es``) + * French (``fr``) + * Hungarian (``hu``) + * Italian (``it``) + * Swedish (``sv``) - 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. +.. confval:: applehelp_locale + :type: :code-py:`str` + :default: The value of **language** - Defaults to :confval:`language`, or if that is not set, to ``'en'``. + Specifies the locale to generate help for. + This is used to determine the name of the ``.lproj`` directory + inside the Help Book’s ``Resources``, + and is passed to the help indexer. .. confval:: applehelp_title + :type: :code-py:`str` + :default: :samp:`'{project} Help'` - Specifies the help book title. Defaults to :samp:`'{<project>} Help'`. + Specifies the help book title. .. confval:: applehelp_codesign_identity + :type: :code-py:`str` + :default: The value of **CODE_SIGN_IDENTITY** - Specifies the identity to use for code signing, or ``None`` if code signing - is not to be performed. + Specifies the identity to use for code signing. + Use :code-py:`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. + Defaults to the value of the :envvar:`!CODE_SIGN_IDENTITY` + environment variable, which is set by Xcode for script build phases, + or :code-py:`None` if that variable is not set. .. confval:: applehelp_codesign_flags + :type: :code-py:`list[str]` + :default: The value of **OTHER_CODE_SIGN_FLAGS** A *list* of additional arguments to pass to :program:`codesign` when signing the help book. - Defaults to a list based on the value of the environment variable - ``OTHER_CODE_SIGN_FLAGS``, which is set by Xcode for script build phases, + Defaults to a list based on the value of the :envvar:`!OTHER_CODE_SIGN_FLAGS` + environment variable, which is set by Xcode for script build phases, or the empty list if that variable is not set. -.. confval:: applehelp_indexer_path +.. confval:: applehelp_codesign_path + :type: :code-py:`str` + :default: :code-py:`'/usr/bin/codesign'` - The path to the :program:`hiutil` program. Defaults to - ``'/usr/bin/hiutil'``. + The path to the :program:`codesign` program. -.. confval:: applehelp_codesign_path +.. confval:: applehelp_indexer_path + :type: :code-py:`str` + :default: :code-py:`'/usr/bin/hiutil'` - The path to the :program:`codesign` program. Defaults to - ``'/usr/bin/codesign'``. + The path to the :program:`hiutil` program. .. confval:: applehelp_disable_external_tools + :type: :code-py:`bool` + :default: :code-py:`False` - If ``True``, the builder will not run the indexer or the code signing tool, + 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-Mac OS X platform and then complete the final steps on OS X - for some reason. - - Defaults to ``False``. + This is mainly useful for testing, + or where you want to run the Sphinx build on a non-macOS platform + and then complete the final steps on a Mac for some reason. .. _epub-options: -Options for epub output +Options for EPUB output ----------------------- -These options influence the epub output. As this builder derives from the HTML -builder, the HTML options also apply where appropriate. The actual values for -some of the options is not really important, they just have to be entered into -the `Dublin Core metadata <https://dublincore.org/>`_. +These options influence EPUB output. +This builder derives from the HTML builder, +so the HTML options also apply where appropriate. + +.. note:: + The actual value for some of these options is not important, + but they are required for the `Dublin Core metadata`_. + + .. _Dublin Core metadata: https://dublincore.org/ .. confval:: epub_basename + :type: :code-py:`str` + :default: The value of **project** - The basename for the epub file. It defaults to the :confval:`project` name. + The basename for the EPUB file. .. confval:: epub_theme + :type: :code-py:`str` + :default: :code-py:`'epub'` - 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. + The HTML theme for the EPUB output. Since the default themes are not + optimised for small screen space, using the same theme for HTML and EPUB + output is usually not wise. + This defaults to :code-py:`'epub'`, + a theme designed to save visual space. .. confval:: epub_theme_options + :type: :code-py:`dict[str, Any]` + :default: :code-py:`{}` - A dictionary of options that influence the look and feel of the selected - theme. These are theme-specific. For the options understood by the builtin - themes, see :ref:`this section <builtin-themes>`. + A dictionary of options that influence the + look and feel of the selected theme. + These are theme-specific. + The options understood by the :ref:`builtin themes + <builtin-themes>` are described :ref:`here <builtin-themes>`. .. versionadded:: 1.2 .. confval:: epub_title + :type: :code-py:`str` + :default: The value of **project** - The title of the document. It defaults to the :confval:`html_title` option - but can be set independently for epub creation. It defaults to the - :confval:`project` option. + The title of the document. .. versionchanged:: 2.0 - It defaults to the ``project`` option. + It defaults to the :confval:`!project` option + (previously :confval:`!html_title`). .. confval:: epub_description + :type: :code-py:`str` + :default: :code-py:`'unknown'` - The description of the document. The default value is ``'unknown'``. + The description of the document. .. versionadded:: 1.4 .. versionchanged:: 1.5 - Renamed from ``epub3_description`` + Renamed from :confval:`!epub3_description` .. confval:: epub_author + :type: :code-py:`str` + :default: The value of **author** - The author of the document. This is put in the Dublin Core metadata. It - defaults to the :confval:`author` option. + The author of the document. + This is put in the Dublin Core metadata. .. confval:: epub_contributor + :type: :code-py:`str` + :default: :code-py:`'unknown'` - 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'``. + The name of a person, organisation, etc. that played a secondary role + in the creation of the content of an EPUB Publication. .. versionadded:: 1.4 .. versionchanged:: 1.5 - Renamed from ``epub3_contributor`` + Renamed from :confval:`!epub3_contributor` .. confval:: epub_language + :type: :code-py:`str` + :default: The value of **language** - The language of the document. This is put in the Dublin Core metadata. The - default is the :confval:`language` option or ``'en'`` if unset. + The language of the document. + This is put in the Dublin Core metadata. .. confval:: epub_publisher + :type: :code-py:`str` + :default: The value of **author** - The publisher of the document. This is put in the Dublin Core metadata. - You may use any sensible string, e.g. the project homepage. The defaults to - the :confval:`author` option. + The publisher of the document. + This is put in the Dublin Core metadata. + You may use any sensible string, e.g. the project homepage. .. confval:: epub_copyright + :type: :code-py:`str` + :default: The value of **copyright** - The copyright of the document. It defaults to the :confval:`copyright` - option but can be set independently for epub creation. + The copyright of the document. .. confval:: epub_identifier + :type: :code-py:`str` + :default: :code-py:`'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. The default value is - ``'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. .. confval:: epub_scheme + :type: :code-py:`str` + :default: :code-py:`'unknown'` - The publication scheme for the :confval:`epub_identifier`. This is put in - the Dublin Core metadata. For published books the scheme is ``'ISBN'``. If - you use the project homepage, ``'URL'`` seems reasonable. The default value - is ``'unknown'``. + The publication scheme for the :confval:`epub_identifier`. + This is put in the Dublin Core metadata. + For published books the scheme is ``'ISBN'``. + If you use the project homepage, ``'URL'`` seems reasonable. .. confval:: epub_uid + :type: :code-py:`str` + :default: :code-py:`'unknown'` + + 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. - A unique identifier for the document. This is put in the Dublin Core - metadata. You may use a - `XML's Name format <https://www.w3.org/TR/REC-xml/#NT-NameStartChar>`_ - string. You can't use hyphen, period, numbers as a first character. The - default value is ``'unknown'``. + .. _XML's Name format: https://www.w3.org/TR/REC-xml/#NT-NameStartChar .. confval:: epub_cover + :type: :code-py:`tuple[str, str]` + :default: :code-py:`()` - The cover page information. This is a tuple containing the filenames of - the cover image and the html template. The rendered html cover page is - inserted as the first item in the spine in :file:`content.opf`. If the - template filename is empty, no html cover page is created. No cover at all - is created if the tuple is empty. Examples:: + The cover page information. + This is a tuple containing the filenames of the cover image + and the html template. + The rendered html cover page is inserted as the first item + in the spine in :file:`content.opf`. + If the template filename is empty, no html cover page is created. + No cover at all is created if the tuple is empty. + + Examples: + + .. code-block:: python epub_cover = ('_static/cover.png', 'epub-cover.html') epub_cover = ('_static/cover.png', '') epub_cover = () - The default value is ``()``. - .. versionadded:: 1.1 .. confval:: epub_css_files + :type: :code-py:`Sequence[str | tuple[str, dict[str, str]]]` + :default: :code-py:`[]` - A list of CSS files. The entry must be a *filename* string or a tuple - containing the *filename* string and the *attributes* dictionary. For more - information, see :confval:`html_css_files`. + A list of CSS files. + The entry must be a *filename* string + or a tuple containing the *filename* string and the *attributes* dictionary. + The *filename* must be relative to the :confval:`html_static_path`, + or a full URI with scheme like :code-py:`'https://example.org/style.css'`. + The *attributes* dictionary is used for the ``<link>`` tag's attributes. + For more information, see :confval:`html_css_files`. .. versionadded:: 1.8 .. confval:: epub_guide + :type: :code-py:`Sequence[tuple[str, str, str]]` + :default: :code-py:`()` + + Meta data for the guide element of :file:`content.opf`. + This is a sequence of tuples containing + the *type*, the *uri* and the *title* of the optional guide information. + See `the OPF documentation <https://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. - Meta data for the guide element of :file:`content.opf`. This is a - sequence of tuples containing the *type*, the *uri* and the *title* of - the optional guide information. See the OPF documentation - at `<https://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:: + Example: + + .. code-block:: python - epub_guide = (('cover', 'cover.html', 'Cover Page'),) + epub_guide = ( + ('cover', 'cover.html', 'Cover Page'), + ) - The default value is ``()``. + The default value is :code-py:`()`. .. confval:: epub_pre_files + :type: :code-py:`Sequence[tuple[str, str]]` + :default: :code-py:`()` + + Additional files that should be inserted before the text generated by Sphinx. + It is a list of tuples containing the file name and the title. + If the title is empty, no entry is added to :file:`toc.ncx`. - Additional files that should be inserted before the text generated by - Sphinx. It is a list of tuples containing the file name and the title. - If the title is empty, no entry is added to :file:`toc.ncx`. Example:: + Example: + + .. code-block:: python epub_pre_files = [ ('index.html', 'Welcome'), ] - The default value is ``[]``. - .. confval:: epub_post_files + :type: :code-py:`Sequence[tuple[str, str]]` + :default: :code-py:`()` Additional files that should be inserted after the text generated by Sphinx. - It is a list of tuples containing the file name and the title. This option - can be used to add an appendix. If the title is empty, no entry is added - to :file:`toc.ncx`. The default value is ``[]``. + It is a list of tuples containing the file name and the title. + This option can be used to add an appendix. + If the title is empty, no entry is added to :file:`toc.ncx`. + + Example: + + .. code-block:: python + + epub_post_files = [ + ('appendix.xhtml', 'Appendix'), + ] .. confval:: epub_exclude_files + :type: :code-py:`Sequence[str]` + :default: :code-py:`[]` - 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 ``[]``. + A sequence of files that are generated/copied in the build directory + but should not be included in the EPUB file. .. confval:: epub_tocdepth + :type: :code-py:`int` + :default: :code-py:`3` - The depth of the table of contents in the file :file:`toc.ncx`. It should - be an integer greater than zero. The default value is 3. Note: A deeply - nested table of contents may be difficult to navigate. + The depth of the table of contents in the file :file:`toc.ncx`. + It should be an integer greater than zero. + + .. tip:: + A deeply nested table of contents may be difficult to navigate. .. confval:: epub_tocdup + :type: :code-py:`bool` + :default: :code-py:`True` - 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``. + 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. .. confval:: epub_tocscope + :type: :code-py:`'default' | 'includehidden'` + :default: :code-py:`'default'` - This setting control the scope of the epub table of contents. The setting - can have the following values: + This setting control the scope of the EPUB table of contents. + The setting can have the following values: - * ``'default'`` -- include all toc entries that are not hidden (default) - * ``'includehidden'`` -- include all toc entries + :code-py:`'default'` + Include all ToC entries that are not hidden + :code-py:`'includehidden'` + Include all ToC entries .. versionadded:: 1.2 .. confval:: epub_fix_images + :type: :code-py:`bool` + :default: :code-py:`False` - 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 + 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 the automatic conversion may lose information. + You need the Python Image Library (Pillow_) installed to use this option. + + .. _Pillow: https://pypi.org/project/Pillow/ .. versionadded:: 1.2 .. confval:: epub_max_image_width + :type: :code-py:`int` + :default: :code-py:`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. - 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. + .. _Pillow: https://pypi.org/project/Pillow/ .. versionadded:: 1.2 .. confval:: epub_show_urls + :type: :code-py:`'footnote' | 'no' | 'inline'` + :default: :code-py:`'footnote'` - 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: + Control how to display URL addresses. + This is very useful for readers that have no other means + to display the linked URL. + The setting can have the following values: - * ``'inline'`` -- display URLs inline in parentheses (default) - * ``'footnote'`` -- display URLs in footnotes - * ``'no'`` -- do not display URLs + :code-py:`'inline'` + Display URLs inline in parentheses. + :code-py:`'footnote'` + Display URLs in footnotes. + :code-py:`'no'` + Do not display URLs. - The display of inline URLs can be customized by adding CSS rules for the - class ``link-target``. + The display of inline URLs can be customised by adding CSS rules + for the class ``link-target``. .. versionadded:: 1.2 .. confval:: epub_use_index + :type: :code-py:`bool` + :default: The value of **html_use_index** - If true, add an index to the epub document. It defaults to the - :confval:`html_use_index` option but can be set independently for epub - creation. + Add an index to the EPUB document. .. versionadded:: 1.2 .. confval:: epub_writing_mode + :type: :code-py:`'horizontal' | 'vertical'` + :default: :code-py:`'horizontal'` - It specifies writing direction. It can accept ``'horizontal'`` (default) and - ``'vertical'`` + It specifies writing direction. + It can accept :code-py:`'horizontal'` and :code-py:`'vertical'` .. list-table:: + :align: left :header-rows: 1 :stub-columns: 1 - - * ``epub_writing_mode`` - * ``'horizontal'`` - * ``'vertical'`` - - * writing-mode [#]_ - * ``horizontal-tb`` - * ``vertical-rl`` - - * page progression - * left to right - * right to left - - * iBook's Scroll Theme support - * scroll-axis is vertical. - * scroll-axis is horizontal. + * - ``epub_writing_mode`` + - ``'horizontal'`` + - ``'vertical'`` + * - writing-mode_ + - ``horizontal-tb`` + - ``vertical-rl`` + * - page progression + - left to right + - right to left + * - iBook's Scroll Theme support + - scroll-axis is vertical. + - scroll-axis is horizontal. - .. [#] https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode + .. _writing-mode: https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode .. _latex-options: @@ -2150,241 +2755,295 @@ Options for LaTeX output These options influence LaTeX output. .. confval:: latex_engine + :type: :code-py:`'pdflatex' | 'xelatex' | 'lualatex' | 'platex' | 'uplatex'` + :default: :code-py:`'pdflatex'` + + The LaTeX engine to build the documentation. + The setting can have the following values: + + * :code-py:`'pdflatex'` -- PDFLaTeX (default) + * :code-py:`'xelatex'` -- XeLaTeX + * :code-py:`'lualatex'` -- LuaLaTeX + * :code-py:`'platex'` -- pLaTeX + * :code-py:`'uplatex'` -- upLaTeX + (default if :confval:`language` is :code-py:`'ja'`) + + .. caution:: + ``'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 coverage + is often easier than trying to make ``'pdflatex'`` work + with the extra Unicode characters. + Since Sphinx 2.0, the default typeface is GNU FreeFont, + which has good coverage of Latin, Cyrillic, and Greek glyphs. - The LaTeX engine to build the docs. The setting can have the following - values: - - * ``'pdflatex'`` -- PDFLaTeX (default) - * ``'xelatex'`` -- XeLaTeX - * ``'lualatex'`` -- LuaLaTeX - * ``'platex'`` -- pLaTeX - * ``'uplatex'`` -- upLaTeX (default if :confval:`language` is ``'ja'``) + .. note:: - ``'pdflatex'``\ 's support for Unicode characters is limited. + Sphinx 2.0 adds support to ``'pdflatex'`` in Latin language document of + occasional Cyrillic or Greek letters or words. + This is not automatic, see the discussion + of the ``'fontenc'`` key in :confval:`latex_elements` . .. note:: - 2.0 adds to ``'pdflatex'`` support in Latin language document of - occasional Cyrillic or Greek letters or words. This is not automatic, - see the discussion of the :confval:`latex_elements` ``'fontenc'`` key. - - If your project uses Unicode characters, setting the engine to - ``'xelatex'`` or ``'lualatex'`` and making sure to use an OpenType font - with wide-enough glyph coverage is often easier than trying to make - ``'pdflatex'`` work with the extra Unicode characters. Since Sphinx 2.0 - the default is the GNU FreeFont which covers well Latin, Cyrillic and - Greek. + Contrarily to :ref:`MathJaX math rendering in HTML output <math-support>`, + LaTeX requires some extra configuration to support Unicode literals in + :rst:dir:`math`: + the only comprehensive solution (as far as we know) is to + use ``'xelatex'`` or ``'lualatex'`` *and* to add + ``r'\usepackage{unicode-math}'`` + (e.g. via the :confval:`latex_elements` ``'preamble'`` key). + You may prefer ``r'\usepackage[math-style=literal]{unicode-math}'`` + to keep a Unicode literal such as ``α`` (U+03B1) as-is in output, + rather than being rendered as :math:`\alpha`. .. versionchanged:: 2.1.0 - - Use ``xelatex`` (and LaTeX package ``xeCJK``) by default for Chinese - documents. + Use ``xelatex`` (and LaTeX package ``xeCJK``) + by default for Chinese documents. .. versionchanged:: 2.2.1 - Use ``xelatex`` by default for Greek documents. .. versionchanged:: 2.3 - Add ``uplatex`` support. .. versionchanged:: 4.0 - - ``uplatex`` becomes the default setting of Japanese documents. - - Contrarily to :ref:`MathJaX math rendering in HTML output <math-support>`, - LaTeX requires some extra configuration to support Unicode literals in - :rst:dir:`math`: the only comprehensive solution (as far as we know) is to - use ``'xelatex'`` or ``'lualatex'`` *and* to add - ``r'\usepackage{unicode-math}'`` (e.g. via the :confval:`latex_elements` - ``'preamble'`` key). You may prefer - ``r'\usepackage[math-style=literal]{unicode-math}'`` to keep a Unicode - literal such as ``α`` (U+03B1) for example as is in output, rather than - being rendered as :math:`\alpha`. + Use ``uplatex`` by default for Japanese documents. .. confval:: latex_documents + :type: :code-py:`Sequence[tuple[str, str, str, str, str, bool]]` + :default: The default LaTeX documents - This value determines how to group the document tree into LaTeX source files. + This value determines how to group the document tree + into LaTeX source files. It must be a list of tuples ``(startdocname, targetname, title, author, - theme, toctree_only)``, where the items are: + theme, toctree_only)``, + where the items are: *startdocname* - String that specifies the :term:`document name` of the LaTeX file's master - document. All documents referenced by the *startdoc* document in TOC trees - will be included in the LaTeX file. (If you want to use the default root - document for your LaTeX build, provide your :confval:`root_doc` here.) + String that specifies the :term:`document name` of + the LaTeX file's master document. + All documents referenced by the *startdoc* document in + ToC trees will be included in the LaTeX file. + (If you want to use the default master document for your LaTeX build, + provide your :confval:`master_doc` here.) *targetname* - File name of the LaTeX file in the output directory. + File name of the LaTeX file in the output directory. *title* - LaTeX document title. Can be empty to use the title of the *startdoc* - document. This is inserted as LaTeX markup, so special characters like a - backslash or ampersand must be represented by the proper LaTeX commands if - they are to be inserted literally. + LaTeX document title. + Can be empty to use the title of the *startdoc* document. + This is inserted as LaTeX markup, + so special characters like a backslash or ampersand + must be represented by the proper LaTeX commands + if they are to be inserted literally. *author* - Author for the LaTeX document. The same LaTeX markup caveat as for *title* - applies. Use ``\\and`` to separate multiple authors, as in: - ``'John \\and Sarah'`` (backslashes must be Python-escaped to reach LaTeX). + Author for the LaTeX document. + The same LaTeX markup caveat as for *title* applies. + Use ``\\and`` to separate multiple authors, as in: ``'John \\and Sarah'`` + (backslashes must be Python-escaped to reach LaTeX). *theme* - LaTeX theme. See :confval:`latex_theme`. + LaTeX theme. + See :confval:`latex_theme`. *toctree_only* - Must be ``True`` or ``False``. If true, the *startdoc* document itself is - not included in the output, only the documents referenced by it via TOC - trees. With this option, you can put extra stuff in the master document - that shows up in the HTML, but not the LaTeX output. + Must be :code-py:`True` or :code-py:`False`. + If True, the *startdoc* document itself is not included in the output, + only the documents referenced by it via ToC trees. + With this option, you can put extra stuff in the master document + that shows up in the HTML, but not the LaTeX output. + + .. versionadded:: 0.3 + The 6th item ``toctree_only``. + Tuples with 5 items are still accepted. .. versionadded:: 1.2 In the past including your own document class required you to prepend the - document class name with the string "sphinx". This is not necessary - anymore. - - .. versionadded:: 0.3 - The 6th item ``toctree_only``. Tuples with 5 items are still accepted. + document class name with the string "sphinx". + This is not necessary anymore. .. confval:: latex_logo + :type: :code-py:`str` + :default: :code-py:`''` - If given, this must be the name of an image file (relative to the - configuration directory) that is the logo of the docs. It is placed at the - top of the title page. Default: ``None``. + If given, this must be the name of an image file + (path relative to the :term:`configuration directory`) + that is the logo of the documentation. + It is placed at the top of the title page. .. confval:: latex_toplevel_sectioning + :type: :code-py:`'part' | 'chapter' | 'section'` + :default: :code-py:`None` - This value determines the topmost sectioning unit. It should be chosen from - ``'part'``, ``'chapter'`` or ``'section'``. The default is ``None``; - the topmost - sectioning unit is switched by documentclass: ``section`` is used if - documentclass will be ``howto``, otherwise ``chapter`` will be used. + This value determines the topmost sectioning unit. + By default, the topmost sectioning unit is switched by documentclass: + ``section`` is used if documentclass will be ``howto``, + otherwise ``chapter`` is used be used. - Note that if LaTeX uses ``\part`` command, then the numbering of sectioning - units one level deep gets off-sync with HTML numbering, because LaTeX - numbers continuously ``\chapter`` (or ``\section`` for ``howto``.) + Note that if LaTeX uses :code-tex:`\\part` command, + then the numbering of sectioning units one level deep gets off-sync + with HTML numbering, + because LaTeX numbers :code-tex:`\\chapter` continuously + (or :code-tex:`\\section` for ``howto``). .. versionadded:: 1.4 .. confval:: latex_appendices + :type: :code-py:`Sequence[str]` + :default: :code-py:`()` A list of document names to append as an appendix to all manuals. + This is ignored if :confval:`latex_theme` is set to :code-py:`'howto'`. .. confval:: latex_domain_indices + :type: :code-py:`bool | Sequence[str]` + :default: :code-py:`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. - 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 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: - This value can be a bool or a list of index names that should be generated, - like for :confval:`html_domain_indices`. + .. code-block:: python + + latex_domain_indices = { + 'py-modindex', + } .. versionadded:: 1.0 + .. versionchanged:: 7.4 + Permit and prefer a set type. .. confval:: latex_show_pagerefs + :type: :code-py:`bool` + :default: :code-py:`False` - If true, add page references after internal references. This is very useful - for printed copies of the manual. Default is ``False``. + Add page references after internal references. + This is very useful for printed copies of the manual. .. versionadded:: 1.0 .. confval:: latex_show_urls + :type: :code-py:`'no' | 'footnote' | 'inline'` + :default: :code-py:`'no'` - Control whether to display URL addresses. This is very useful for printed - copies of the manual. The setting can have the following values: + 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 (default) - * ``'footnote'`` -- display URLs in footnotes - * ``'inline'`` -- display URLs inline in parentheses + :code-py:`'no'` + Do not display URLs + :code-py:`'footnote'` + Display URLs in footnotes + :code-py:`'inline'` + Display URLs inline in parentheses .. versionadded:: 1.0 .. versionchanged:: 1.1 - This value is now a string; previously it was a boolean value, and a true - value selected the ``'inline'`` display. For backwards compatibility, - ``True`` is still accepted. + This value is now a string; previously it was a boolean value, + and a true value selected the :code-py:`'inline'` display. + For backwards compatibility, :code-py:`True` is still accepted. .. confval:: latex_use_latex_multicolumn - - The default is ``False``: it means that Sphinx's own macros are used for - merged cells from grid tables. They allow general contents (literal blocks, - lists, blockquotes, ...) but may have problems if the - :rst:dir:`tabularcolumns` directive was used to inject LaTeX mark-up of the - type ``>{..}``, ``<{..}``, ``@{..}`` as column specification. - - Setting to ``True`` means to use LaTeX's standard ``\multicolumn``; this is - incompatible with literal blocks in the horizontally merged cell, and also - with multiple paragraphs in such cell if the table is rendered using - ``tabulary``. + :type: :code-py:`bool` + :default: :code-py:`False` + + Use standard LaTeX's :code-tex:`\\multicolumn` for merged cells in tables. + + :code-py:`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 the :rst:dir:`tabularcolumns` directive + was used to inject LaTeX mark-up of the type + ``>{..}``, ``<{..}``, ``@{..}`` as column specification. + :code-py:`True` + Use LaTeX's standard :code-tex:`\\multicolumn`; + this is incompatible with literal blocks in horizontally merged cells, + and also with multiple paragraphs in such cells + if the table is rendered using ``tabulary``. .. versionadded:: 1.6 .. confval:: latex_table_style - - A list of styling classes (strings). Currently supported: - - - ``'booktabs'``: no vertical lines, and only 2 or 3 horizontal lines (the - latter if there is a header), using the booktabs_ package. - - - ``'borderless'``: no lines whatsoever. - - - ``'colorrows'``: the table rows are rendered with alternating background - colours. The interface to customize them is via :ref:`dedicated keys - <tablecolors>` of :ref:`latexsphinxsetup`. - - .. important:: - - With the ``'colorrows'`` style, the ``\rowcolors`` LaTeX command - becomes a no-op (this command has limitations and has never correctly - supported all types of tables Sphinx produces in LaTeX). Please - update your project to use instead - the :ref:`latex table color configuration <tablecolors>` keys. - - Default: ``['booktabs', 'colorrows']`` - - .. versionadded:: 5.3.0 - - .. versionchanged:: 6.0.0 - - Modify default from ``[]`` to ``['booktabs', 'colorrows']``. - - Each table can override the global style via ``:class:`` option, or - ``.. rst-class::`` for no-directive tables (cf. :ref:`table-directives`). - Currently recognized classes are ``booktabs``, ``borderless``, - ``standard``, ``colorrows``, ``nocolorrows``. The latter two can be - combined with any of the first three. The ``standard`` class produces - tables with both horizontal and vertical lines (as has been the default so - far with Sphinx). - - A single-row multi-column merged cell will obey the row colour, if it is - set. See also ``TableMergeColor{Header,Odd,Even}`` in the - :ref:`latexsphinxsetup` section. + :type: :code-py:`list[str]` + :default: :code-py:`['booktabs', 'colorrows']` + + A list of styling classes (strings). + Currently supported: + + :code-py:`'booktabs'` + No vertical lines, and only 2 or 3 horizontal lines + (the latter if there is a header), + using the booktabs_ package. + + :code-py:`'borderless'` + No lines whatsoever. + + :code-py:`'colorrows'` + The table rows are rendered with alternating background colours. + The interface to customise them is via + :ref:`dedicated keys <tablecolors>` of :ref:`latexsphinxsetup`. + + .. important:: + + With the :code-py:`'colorrows'` style, + the :code-tex:`\\rowcolors` LaTeX command becomes a no-op + (this command has limitations and has never correctly + supported all types of tables Sphinx produces in LaTeX). + Please update your project to use the + :ref:`latex table color configuration <tablecolors>` keys instead. + + Each table can override the global style via ``:class:`` option, + or ``.. rst-class::`` for no-directive tables (cf. :ref:`table-directives`). + Currently recognised classes are ``booktabs``, ``borderless``, + ``standard``, ``colorrows``, ``nocolorrows``. + The latter two can be combined with any of the first three. + The ``standard`` class produces tables with + both horizontal and vertical lines + (as has been the default so far with Sphinx). + + A single-row multi-column merged cell will obey the row colour, + if it is set. + See also ``TableMergeColor{Header,Odd,Even}`` + in the :ref:`latexsphinxsetup` section. .. note:: - - It is hard-coded in LaTeX that a single cell will obey the row colour - even if there is a column colour set via ``\columncolor`` from a - column specification (see :rst:dir:`tabularcolumns`). Sphinx provides - ``\sphinxnorowcolor`` which can be used like this: + * It is hard-coded in LaTeX that a single cell will obey the row colour + even if there is a column colour set via :code-tex:`\\columncolor` + from a column specification (see :rst:dir:`tabularcolumns`). + Sphinx provides :code-tex:`\\sphinxnorowcolor` which can be used + in a table column specification like this: .. code-block:: latex >{\columncolor{blue}\sphinxnorowcolor} - in a table column specification. - - - Sphinx also provides ``\sphinxcolorblend`` which however requires the - xcolor_ package. Here is an example: + * Sphinx also provides :code-tex:`\\sphinxcolorblend`, + which however requires the xcolor_ package. + Here is an example: .. code-block:: latex >{\sphinxcolorblend{!95!red}} - It means that in this column, the row colours will be slightly tinted - by red; refer to xcolor_ documentation for more on the syntax of its - ``\blendcolors`` command (a ``\blendcolors`` in place of - ``\sphinxcolorblend`` would modify colours of the cell *contents*, not - of the cell *background colour panel*...). You can find an example of - usage in the :ref:`dev-deprecated-apis` section of this document in - PDF format. + It means that in this column, + the row colours will be slightly tinted by red; + refer to xcolor_ documentation for more on the syntax of its + :code-tex:`\\blendcolors` command + (a :code-tex:`\\blendcolors` in place of :code-tex:`\\sphinxcolorblend` + would modify colours of the cell *contents*, + not of the cell *background colour panel*...). + You can find an example of usage in the :ref:`dev-deprecated-apis` + section of this document in PDF format. .. hint:: @@ -2392,19 +3051,21 @@ These options influence LaTeX output. cells of a given column use ``>{\noindent\color{<color>}}``, possibly in addition to the above. - - Multi-row merged cells, whether single column or multi-column + * Multi-row merged cells, whether single column or multi-column currently ignore any set column, row, or cell colour. - - It is possible for a simple cell to set a custom colour via the - :dudir:`raw` directive and the ``\cellcolor`` LaTeX command used - anywhere in the cell contents. This currently is without effect - in a merged cell, whatever its kind. + * It is possible for a simple cell to set a custom colour via the + :dudir:`raw` directive and + the :code-tex:`\\cellcolor` LaTeX command used + anywhere in the cell contents. + This currently is without effect in a merged cell, whatever its kind. .. hint:: - In a document not using ``'booktabs'`` globally, it is possible to style - an individual table via the ``booktabs`` class, but it will be necessary - to add ``r'\usepackage{booktabs}'`` to the LaTeX preamble. + In a document not using ``'booktabs'`` globally, + it is possible to style an individual table via the ``booktabs`` class, + but it will be necessary to add ``r'\usepackage{booktabs}'`` + to the LaTeX preamble. On the other hand one can use ``colorrows`` class for individual tables with no extra package (as Sphinx since 5.3.0 always loads colortbl_). @@ -2413,113 +3074,140 @@ These options influence LaTeX output. .. _colortbl: https://ctan.org/pkg/colortbl .. _xcolor: https://ctan.org/pkg/xcolor + .. versionadded:: 5.3.0 + + .. versionchanged:: 6.0.0 + + Modify default from :code-py:`[]` to :code-py:`['booktabs', 'colorrows']`. + .. confval:: latex_use_xindy + :type: :code-py:`bool` + :default: :code-py:`True if latex_engine in {'xelatex', 'lualatex'} else False` - If ``True``, the PDF build from the LaTeX files created by Sphinx - will use :program:`xindy` (doc__) rather than :program:`makeindex` - for preparing the index of general terms (from :rst:dir:`index` - usage). This means that words with UTF-8 characters will get + Use Xindy_ to prepare the index of general terms. + By default, the LaTeX builder uses :program:`makeindex` + for preparing the index of general terms . + This means that words with UTF-8 characters will be ordered correctly for the :confval:`language`. - __ https://xindy.sourceforge.net/ + .. _Xindy: https://xindy.sourceforge.net/ - - This option is ignored if :confval:`latex_engine` is ``'platex'`` - (Japanese documents; :program:`mendex` replaces :program:`makeindex` - then). + * This option is ignored if :confval:`latex_engine` is :code-py:`'platex'` + (Japanese documents; + :program:`mendex` replaces :program:`makeindex` then). - - The default is ``True`` for ``'xelatex'`` or ``'lualatex'`` as - :program:`makeindex`, if any indexed term starts with a non-ascii - character, creates ``.ind`` files containing invalid bytes for - UTF-8 encoding. With ``'lualatex'`` this then breaks the PDF - build. + * The default is :code-py:`True` + for :code-py:`'xelatex'` or :code-py:`'lualatex'` as + :program:`makeindex` creates ``.ind`` files containing invalid bytes + for the UTF-8 encoding if any indexed term starts with + a non-ASCII character. + With :code-py:`'lualatex'` this then breaks the PDF build. - - The default is ``False`` for ``'pdflatex'`` but ``True`` is - recommended for non-English documents as soon as some indexed - terms use non-ascii characters from the language script. + * The default is :code-py:`False` for :code-py:`'pdflatex'`, + but :code-py:`True` is recommended for non-English documents as soon + as some indexed terms use non-ASCII characters from the language script. - Sphinx adds to :program:`xindy` base distribution some dedicated support - for using ``'pdflatex'`` engine with Cyrillic scripts. And whether with - ``'pdflatex'`` or Unicode engines, Cyrillic documents handle correctly the - indexing of Latin names, even with diacritics. + Sphinx adds some dedicated support to the :program:`xindy` base distribution + for using :code-py:`'pdflatex'` engine with Cyrillic scripts. + With both :code-py:`'pdflatex'` and Unicode engines, + Cyrillic documents handle the indexing of Latin names correctly, + even with diacritics. .. versionadded:: 1.8 .. confval:: latex_elements + :type: :code-py:`dict[str, str]` + :default: :code-py:`{}` .. versionadded:: 0.5 - Its :ref:`documentation <latex_elements_confval>` has moved to :doc:`/latex`. + :ref:`See the full documentation for latex_elements <latex_elements_confval>`. .. confval:: latex_docclass + :type: :code-py:`dict[str, str]` + :default: :code-py:`{}` - A dictionary mapping ``'howto'`` and ``'manual'`` to names of real document - classes that will be used as the base for the two Sphinx classes. Default - is to use ``'article'`` for ``'howto'`` and ``'report'`` for ``'manual'``. + A dictionary mapping :code-py:`'howto'` and :code-py:`'manual'` + to names of real document classes that will be used as the base + for the two Sphinx classes. + Default is to use :code-py:`'article'` for :code-py:`'howto'` + and :code-py:`'report'` for :code-py:`'manual'`. .. versionadded:: 1.0 .. versionchanged:: 1.5 - - In Japanese docs (:confval:`language` is ``'ja'``), by default - ``'jreport'`` is used for ``'howto'`` and ``'jsbook'`` for ``'manual'``. + In Japanese documentation (:confval:`language` is :code-py:`'ja'`), + by default :code-py:`'jreport'` is used for :code-py:`'howto'` + and :code-py:`'jsbook'` for :code-py:`'manual'`. .. confval:: latex_additional_files + :type: :code-py:`Sequence[str]` + :default: :code-py:`()` - A list of file names, relative to the configuration directory, to copy to - the build directory when building LaTeX output. This is useful to copy - files that Sphinx doesn't copy automatically, e.g. if they are referenced in - custom LaTeX added in ``latex_elements``. Image files that are referenced - in source files (e.g. via ``.. image::``) are copied automatically. + A list of file names, relative to the :term:`configuration directory`, + to copy to the build directory when building LaTeX output. + This is useful to copy files that Sphinx doesn't copy automatically, + e.g. if they are referenced in custom LaTeX added in ``latex_elements``. + Image files that are referenced in source files (e.g. via ``.. image::``) + are copied automatically. You have to make sure yourself that the filenames don't collide with those of any automatically copied files. .. attention:: - - Filenames with extension ``.tex`` will automatically be handed over to - the PDF build process triggered by :option:`sphinx-build -M` - ``latexpdf`` or by :program:`make latexpdf`. If the file was added only - to be ``\input{}`` from a modified preamble, you must add a further - suffix such as ``.txt`` to the filename and adjust accordingly the - ``\input{}`` command added to the LaTeX document preamble. + Filenames with the ``.tex`` extension will be automatically + handed over to the PDF build process triggered by + :option:`sphinx-build -M latexpdf <sphinx-build -M>` + or by :program:`make latexpdf`. + If the file was added only to be :code-tex:`\\input{}` + from a modified preamble, + you must add a further suffix such as ``.txt`` to the filename + and adjust the :code-tex:`\\input{}` macro accordingly. .. versionadded:: 0.6 .. versionchanged:: 1.2 - This overrides the files which is provided from Sphinx such as - ``sphinx.sty``. + This overrides the files provided from Sphinx such as ``sphinx.sty``. .. confval:: latex_theme + :type: :code-py:`str` + :default: :code-py:`'manual'` - The "theme" that the LaTeX output should use. It is a collection of settings - for LaTeX output (ex. document class, top level sectioning unit and so on). + 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). - As a built-in LaTeX themes, ``manual`` and ``howto`` are bundled. + The bundled first-party LaTeX themes are *manual* and *howto*: ``manual`` - A LaTeX theme for writing a manual. It imports the ``report`` document - class (Japanese documents use ``jsbook``). + A LaTeX theme for writing a manual. + It imports the ``report`` document class + (Japanese documents use ``jsbook``). ``howto`` - A LaTeX theme for writing an article. It imports the ``article`` document - class (Japanese documents use ``jreport`` rather). :confval:`latex_appendices` - is available only for this theme. - - It defaults to ``'manual'``. + A LaTeX theme for writing an article. + It imports the ``article`` document class + (Japanese documents use ``jreport``). + :confval:`latex_appendices` is only available for this theme. .. versionadded:: 3.0 .. confval:: latex_theme_options + :type: :code-py:`dict[str, Any]` + :default: :code-py:`{}` - A dictionary of options that influence the look and feel of the selected - theme. + A dictionary of options that influence the + look and feel of the selected theme. + These are theme-specific. .. versionadded:: 3.1 .. confval:: latex_theme_path + :type: :code-py:`list[str]` + :default: :code-py:`[]` - A list of paths that contain custom LaTeX themes as subdirectories. Relative - paths are taken as relative to the configuration directory. + A list of paths that contain custom LaTeX themes as subdirectories. + Relative paths are taken as relative to the :term:`configuration directory`. .. versionadded:: 3.0 @@ -2531,42 +3219,47 @@ Options for text output These options influence text output. -.. confval:: text_newlines - - Determines which end-of-line character(s) are used in text output. - - * ``'unix'``: use Unix-style line endings (``\n``) - * ``'windows'``: use Windows-style line endings (``\r\n``) - * ``'native'``: use the line ending style of the platform the documentation - is built on +.. confval:: text_add_secnumbers + :type: :code-py:`bool` + :default: :code-py:`True` - Default: ``'unix'``. + Include section numbers in text output. - .. versionadded:: 1.1 + .. versionadded:: 1.7 -.. confval:: text_sectionchars +.. confval:: text_newlines + :type: :code-py:`'unix' | 'windows' | 'native'` + :default: :code-py:`'unix'` - 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. + Determines which end-of-line character(s) are used in text output. - The default is ``'*=-~"+`'``. + :code-py:`'unix'` + Use Unix-style line endings (``\n``). + :code-py:`'windows'` + Use Windows-style line endings (``\r\n``). + :code-py:`'native'` + Use the line ending style of the platform the documentation is built on. .. versionadded:: 1.1 -.. confval:: text_add_secnumbers +.. confval:: text_secnumber_suffix + :type: :code-py:`str` + :default: :code-py:`'. '` - A boolean that decides whether section numbers are included in text output. - Default is ``True``. + Suffix for section numbers in text output. + Set to :code-py:`' '` to suppress the final dot on section numbers. .. versionadded:: 1.7 -.. confval:: text_secnumber_suffix +.. confval:: text_sectionchars + :type: :code-py:`str` + :default: :code-py:`'*=-~"+\`'` - Suffix for section numbers in text output. Default: ``". "``. Set to - ``" "`` to suppress the final dot on section numbers. + 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. - .. versionadded:: 1.7 + .. versionadded:: 1.1 .. _man-options: @@ -2577,57 +3270,68 @@ Options for manual page output These options influence manual page output. .. confval:: man_pages + :type: :code-py:`Sequence[tuple[str, str, str, str, str]]` + :default: The default manual pages - This value determines how to group the document tree into manual pages. It - must be a list of tuples ``(startdocname, name, description, authors, - section)``, where the items are: + This value determines how to group the document tree + into manual pages. + It must be a list of tuples + ``(startdocname, name, description, authors, section)``, + where the items are: *startdocname* - String that specifies the :term:`document name` of the manual page's master - document. All documents referenced by the *startdoc* document in TOC trees - will be included in the manual file. (If you want to use the default - root document for your manual pages build, use your :confval:`root_doc` - here.) + String that specifies the :term:`document name` of + the manual page's master document. + All documents referenced by the *startdoc* document in + ToC trees will be included in the manual page. + (If you want to use the default master document for your manual pages build, + provide your :confval:`master_doc` here.) *name* - Name of the manual page. This should be a short string without spaces or - special characters. It is used to determine the file name as well as the + Name of the manual page. + This should be a short string without spaces or special characters. + It is used to determine the file name as well as the name of the manual page (in the NAME section). *description* - Description of the manual page. This is used in the NAME section. - Can be an empty string if you do not want to automatically generate - the NAME section. + Description of the manual page. + This is used in the NAME section. + Can be an empty string if you do not want to + automatically generate the NAME section. *authors* - A list of strings with authors, or a single string. Can be an empty - string or list if you do not want to automatically generate an AUTHORS - section in the manual page. + A list of strings with authors, or a single string. + Can be an empty string or list if you do not want to + automatically generate an AUTHORS section in the manual page. *section* - The manual page section. Used for the output file name as well as in the - manual page header. + The manual page section. + Used for the output file name as well as in the manual page header. .. versionadded:: 1.0 .. confval:: man_show_urls + :type: :code-py:`bool` + :default: :code-py:`False` - If true, add URL addresses after links. Default is ``False``. + Add URL addresses after links. .. versionadded:: 1.1 .. confval:: man_make_section_directory + :type: :code-py:`bool` + :default: :code-py:`True` - If true, make a section directory on build man page. Default is True. + Make a section directory on build man page. .. versionadded:: 3.3 - .. versionchanged:: 4.0 - The default is changed to ``False`` from ``True``. + .. versionchanged:: 4.0 + The default is now :code-py:`False` (previously :code-py:`True`). .. versionchanged:: 4.0.2 + Revert the change in the default. - The default is changed to ``True`` from ``False`` again. .. _texinfo-options: @@ -2637,266 +3341,275 @@ Options for Texinfo output These options influence Texinfo output. .. confval:: texinfo_documents + :type: :code-py:`Sequence[tuple[str, str, str, str, str, str, str, bool]]` + :default: The default Texinfo documents - This value determines how to group the document tree into Texinfo source - files. It must be a list of tuples ``(startdocname, targetname, title, - author, dir_entry, description, category, toctree_only)``, where the items - are: + This value determines how to group the document tree + into Texinfo source files. + It must be a list of tuples ``(startdocname, targetname, title, author, + dir_entry, description, category, toctree_only)``, + where the items are: *startdocname* - String that specifies the :term:`document name` of the the Texinfo file's - master document. All documents referenced by the *startdoc* document in - TOC trees will be included in the Texinfo file. (If you want to use the - default master document for your Texinfo build, provide your - :confval:`root_doc` here.) + String that specifies the :term:`document name` of + the Texinfo file's master document. + All documents referenced by the *startdoc* document in + ToC trees will be included in the Texinfo file. + (If you want to use the default master document for your Texinfo build, + provide your :confval:`master_doc` here.) *targetname* - File name (no extension) of the Texinfo file in the output directory. + File name (no extension) of the Texinfo file in the output directory. *title* - Texinfo document title. Can be empty to use the title of the *startdoc* - document. Inserted as Texinfo markup, so special characters like ``@`` and - ``{}`` will need to be escaped to be inserted literally. + Texinfo document title. + Can be empty to use the title of the *startdoc* + document. Inserted as Texinfo markup, + so special characters like ``@`` and ``{}`` will need to + be escaped to be inserted literally. *author* - Author for the Texinfo document. Inserted as Texinfo markup. Use ``@*`` - to separate multiple authors, as in: ``'John@*Sarah'``. + Author for the Texinfo document. + Inserted as Texinfo markup. + Use ``@*`` to separate multiple authors, as in: ``'John@*Sarah'``. *dir_entry* - The name that will appear in the top-level ``DIR`` menu file. + The name that will appear in the top-level ``DIR`` menu file. *description* - Descriptive text to appear in the top-level ``DIR`` menu file. + Descriptive text to appear in the top-level ``DIR`` menu file. *category* - Specifies the section which this entry will appear in the top-level - ``DIR`` menu file. + Specifies the section which this entry will appear in the top-level + ``DIR`` menu file. *toctree_only* - Must be ``True`` or ``False``. If true, the *startdoc* document itself is - not included in the output, only the documents referenced by it via TOC - trees. With this option, you can put extra stuff in the master document - that shows up in the HTML, but not the Texinfo output. + Must be :code-py:`True` or :code-py:`False`. + If True, the *startdoc* document itself is not included in the output, + only the documents referenced by it via ToC trees. + With this option, you can put extra stuff in the master document + that shows up in the HTML, but not the Texinfo output. .. versionadded:: 1.1 .. confval:: texinfo_appendices + :type: :code-py:`Sequence[str]` + :default: :code-py:`[]` A list of document names to append as an appendix to all manuals. .. versionadded:: 1.1 -.. confval:: texinfo_domain_indices - - If true, generate domain-specific indices in addition to the general index. - For e.g. the Python domain, this is the global module index. Default is - ``True``. +.. confval:: texinfo_cross_references + :type: :code-py:`bool` + :default: :code-py:`True` - This value can be a bool or a list of index names that should be generated, - like for :confval:`html_domain_indices`. + Generate inline references in a document. + Disabling inline references can make an info file more readable + with a stand-alone reader (``info``). - .. versionadded:: 1.1 + .. versionadded:: 4.4 -.. confval:: texinfo_show_urls +.. confval:: texinfo_domain_indices + :type: :code-py:`bool | Sequence[str]` + :default: :code-py:`True` - Control how to display URL addresses. + If True, generate domain-specific indices in addition to the general index. + For e.g. the Python domain, this is the global module index. - * ``'footnote'`` -- display URLs in footnotes (default) - * ``'no'`` -- do not display URLs - * ``'inline'`` -- display URLs inline in parentheses + 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'``. - .. versionadded:: 1.1 + Example: -.. confval:: texinfo_no_detailmenu + .. code-block:: python - If true, do not generate a ``@detailmenu`` in the "Top" node's menu - containing entries for each sub-node in the document. Default is ``False``. + texinfo_domain_indices = { + 'py-modindex', + } - .. versionadded:: 1.2 + .. versionadded:: 1.1 + .. versionchanged:: 7.4 + Permit and prefer a set type. .. confval:: texinfo_elements + :type: :code-py:`dict[str, Any]` + :default: :code-py:`{}` - A dictionary that contains Texinfo snippets that override those Sphinx - usually puts into the generated ``.texi`` files. + A dictionary that contains Texinfo snippets that override those that + Sphinx usually puts into the generated ``.texi`` files. * Keys that you may want to override include: ``'paragraphindent'`` - Number of spaces to indent the first line of each paragraph, default - ``2``. Specify ``0`` for no indentation. + Number of spaces to indent the first line of each paragraph, + default ``2``. + Specify ``0`` for no indentation. ``'exampleindent'`` Number of spaces to indent the lines for examples or literal blocks, - default ``4``. Specify ``0`` for no indentation. + default ``4``. + Specify ``0`` for no indentation. ``'preamble'`` Texinfo markup inserted near the beginning of the file. ``'copying'`` - Texinfo markup inserted within the ``@copying`` block and displayed - after the title. The default value consists of a simple title page - identifying the project. - - * Keys that are set by other options and therefore should not be overridden - are: - - ``'author'`` - ``'body'`` - ``'date'`` - ``'direntry'`` - ``'filename'`` - ``'project'`` - ``'release'`` - ``'title'`` + Texinfo markup inserted within the ``@copying`` block + and displayed after the title. + The default value consists of a simple title page identifying the project. + + * Keys that are set by other options + and therefore should not be overridden are + ``'author'``, ``'body'``, ``'date'``, ``'direntry'`` + ``'filename'``, ``'project'``, ``'release'``, and ``'title'``. + + .. versionadded:: 1.1 + +.. confval:: texinfo_no_detailmenu + :type: :code-py:`bool` + :default: :code-py:`False` + + Do not generate a ``@detailmenu`` in the "Top" node's menu + containing entries for each sub-node in the document. + + .. versionadded:: 1.2 + +.. confval:: texinfo_show_urls + :type: :code-py:`'footnote' | 'no' | 'inline'` + :default: :code-py:`'footnote'` - .. versionadded:: 1.1 + Control how to display URL addresses. + The setting can have the following values: -.. confval:: texinfo_cross_references + :code-py:`'footnote'` + Display URLs in footnotes. + :code-py:`'no'` + Do not display URLs. + :code-py:`'inline'` + Display URLs inline in parentheses. - If false, do not generate inline references in a document. That makes - an info file more readable with stand-alone reader (``info``). - Default is ``True``. + .. versionadded:: 1.1 - .. versionadded:: 4.4 .. _qthelp-options: Options for QtHelp output -------------------------- -These options influence qthelp output. As this builder derives from the HTML -builder, the HTML options also apply where appropriate. +These options influence qthelp output. +This builder derives from the HTML builder, +so the HTML options also apply where appropriate. .. confval:: qthelp_basename + :type: :code-py:`str` + :default: The value of **project** - The basename for the qthelp file. It defaults to the :confval:`project` - name. + The basename for the qthelp file. .. confval:: qthelp_namespace + :type: :code-py:`str` + :default: :code-py:`'org.sphinx.{project_name}.{project_version}'` - The namespace for the qthelp file. It defaults to - ``org.sphinx.<project_name>.<project_version>``. + The namespace for the qthelp file. .. confval:: qthelp_theme + :type: :code-py:`str` + :default: :code-py:`'nonav'` The HTML theme for the qthelp output. - This defaults to ``'nonav'``. .. confval:: qthelp_theme_options + :type: :code-py:`dict[str, Any]` + :default: :code-py:`{}` - A dictionary of options that influence the look and feel of the selected - theme. These are theme-specific. For the options understood by the builtin - themes, see :ref:`this section <builtin-themes>`. - - -Options for the linkcheck builder ---------------------------------- - -.. confval:: linkcheck_ignore - - A list of regular expressions that match URIs that should not be checked - when doing a ``linkcheck`` build. Example:: - - linkcheck_ignore = [r'https://localhost:\d+/'] + A dictionary of options that influence the + look and feel of the selected theme. + These are theme-specific. + The options understood by the :ref:`builtin themes + <builtin-themes>` are described :ref:`here <builtin-themes>`. - .. versionadded:: 1.1 -.. confval:: linkcheck_allowed_redirects +Options for XML output +---------------------- - A dictionary that maps a pattern of the source URI to a pattern of the canonical - URI. The linkcheck builder treats the redirected link as "working" when: +.. confval:: xml_pretty + :type: :code-py:`bool` + :default: :code-py:`True` - - the link in the document matches the source URI pattern, and - - the redirect location matches the canonical URI pattern. + Pretty-print the XML. - Example: + .. versionadded:: 1.2 - .. code-block:: python - linkcheck_allowed_redirects = { - # All HTTP redirections from the source URI to the canonical URI will be treated as "working". - r'https://sphinx-doc\.org/.*': r'https://sphinx-doc\.org/en/master/.*' - } +Options for the linkcheck builder +--------------------------------- - If set, linkcheck builder will emit a warning when disallowed redirection - found. It's useful to detect unexpected redirects under :option:`the - warn-is-error mode <sphinx-build -W>`. +Filtering +~~~~~~~~~ - .. versionadded:: 4.1 +These options control which links the *linkcheck* builder checks, +and which failures and redirects it ignores. -.. confval:: linkcheck_request_headers +.. confval:: linkcheck_allowed_redirects + :type: :code-py:`dict[str, str]` + :default: :code-py:`{}` - A dictionary that maps baseurls to HTTP request headers. + A dictionary that maps a pattern of the source URI + to a pattern of the canonical URI. + The *linkcheck* builder treats the redirected link as "working" when: - The key is a URL base string like ``"https://www.sphinx-doc.org/"``. To specify - headers for other hosts, ``"*"`` can be used. It matches all hosts only when - the URL does not match other settings. + * the link in the document matches the source URI pattern, and + * the redirect location matches the canonical URI pattern. - The value is a dictionary that maps header name to its value. + The *linkcheck* builder will emit a warning when + it finds redirected links that don't meet the rules above. + It can be useful to detect unexpected redirects when using + :option:`the fail-on-warnings mode <sphinx-build --fail-on-warning>`. Example: .. code-block:: python - linkcheck_request_headers = { - "https://www.sphinx-doc.org/": { - "Accept": "text/html", - "Accept-Encoding": "utf-8", - }, - "*": { - "Accept": "text/html,application/xhtml+xml", - } + linkcheck_allowed_redirects = { + # All HTTP redirections from the source URI to + # the canonical URI will be treated as "working". + r'https://sphinx-doc\.org/.*': r'https://sphinx-doc\.org/en/master/.*' } - .. versionadded:: 3.1 - -.. confval:: linkcheck_retries - - The number of times the linkcheck builder will attempt to check a URL before - declaring it broken. Defaults to 1 attempt. - - .. versionadded:: 1.4 - -.. confval:: linkcheck_timeout - - The duration, in seconds, that the linkcheck builder will wait for a - response after each hyperlink request. Defaults to 30 seconds. - - .. versionadded:: 1.1 - -.. confval:: linkcheck_workers - - The number of worker threads to use when checking links. Default is 5 - threads. - - .. versionadded:: 1.1 + .. versionadded:: 4.1 .. confval:: linkcheck_anchors + :type: :code-py:`bool` + :default: :code-py:`True` - If true, check the validity of ``#anchor``\ s in links. Since this requires - downloading the whole document, it's considerably slower when enabled. - Default is ``True``. + Check the validity of ``#anchor``\ s in links. + Since this requires downloading the whole document, + it is considerably slower when enabled. .. versionadded:: 1.2 .. confval:: linkcheck_anchors_ignore + :type: :code-py:`Sequence[str]` + :default: :code-py:`["^!"]` - A list of regular expressions that match anchors Sphinx should skip when - checking the validity of anchors in links. This allows skipping anchors that - a website's JavaScript adds to control dynamic pages or when triggering an - internal REST request. Default is ``["^!"]``. + A list of regular expressions that match anchors that the *linkcheck* builder + should skip when checking the validity of anchors in links. + For example, this allows skipping anchors added by a website's JavaScript. .. tip:: - Use :confval:`linkcheck_anchors_ignore_for_url` to check a URL, but skip verifying that the anchors exist. .. note:: + If you want to ignore anchors of a specific page or + of pages that match a specific pattern + (but still check occurrences of the same page(s) that don't have anchors), + use :confval:`linkcheck_ignore` instead, + for example as follows: - If you want to ignore anchors of a specific page or of pages that match a - specific pattern (but still check occurrences of the same page(s) that - don't have anchors), use :confval:`linkcheck_ignore` instead, for example - as follows:: + .. code-block:: python linkcheck_ignore = [ 'https://www.sphinx-doc.org/en/1.7/intro.html#', @@ -2905,33 +3618,78 @@ Options for the linkcheck builder .. versionadded:: 1.5 .. confval:: linkcheck_anchors_ignore_for_url + :type: :code-py:`Sequence[str]` + :default: :code-py:`()` A list or tuple of regular expressions matching URLs - for which Sphinx should not check the validity of anchors. + for which the *linkcheck* builder should not check the validity of anchors. This allows skipping anchor checks on a per-page basis while still checking the validity of the page itself. - Default is an empty tuple ``()``. .. versionadded:: 7.1 +.. confval:: linkcheck_exclude_documents + :type: :code-py:`Sequence[str]` + :default: :code-py:`()` + + A list of regular expressions that match documents in which + the *linkcheck* builder should not check the validity of links. + This can be used for permitting link decay + in legacy or historical sections of the documentation. + + Example: + + .. code-block:: python + + # ignore all links in documents located in a subdirectory named 'legacy' + linkcheck_exclude_documents = [r'.*/legacy/.*'] + + .. versionadded:: 4.4 + +.. confval:: linkcheck_ignore + :type: :code-py:`Sequence[str]` + :default: :code-py:`()` + + A list of regular expressions that match URIs that should not be checked + when doing a ``linkcheck`` build. + + Example: + + .. code-block:: python + + linkcheck_ignore = [r'https://localhost:\d+/'] + + .. versionadded:: 1.1 + +HTTP Requests +~~~~~~~~~~~~~ + +These options control how the *linkcheck* builder makes HTTP requests, +including how it handles redirects and authentication, +and the number of workers to use. + .. confval:: linkcheck_auth + :type: :code-py:`Sequence[tuple[str, Any]]` + :default: :code-py:`[]` Pass authentication information when doing a ``linkcheck`` build. - A list of ``(regex_pattern, auth_info)`` tuples where the items are: + A list of :code-py:`(regex_pattern, auth_info)` tuples where the items are: *regex_pattern* A regular expression that matches a URI. *auth_info* - Authentication information to use for that URI. The value can be anything - that is understood by the ``requests`` library (see :ref:`requests - Authentication <requests:authentication>` for details). + Authentication information to use for that URI. + The value can be anything that is understood by the ``requests`` library + (see :ref:`requests authentication <requests:authentication>` for details). - The ``linkcheck`` builder will use the first matching ``auth_info`` value - it can find in the :confval:`linkcheck_auth` list, so values earlier in the - list have higher priority. + The *linkcheck* builder will use the first matching ``auth_info`` value + it can find in the :confval:`!linkcheck_auth` list, + so values earlier in the list have higher priority. - Example:: + Example: + + .. code-block:: python linkcheck_auth = [ ('https://foo\.yourcompany\.com/.+', ('johndoe', 'secret')), @@ -2940,81 +3698,123 @@ Options for the linkcheck builder .. versionadded:: 2.3 -.. confval:: linkcheck_rate_limit_timeout +.. confval:: linkcheck_allow_unauthorized + :type: :code-py:`bool` + :default: :code-py:`True` + + When a webserver responds with an HTTP 401 (unauthorised) response, + the current default behaviour of the *linkcheck* builder is + to treat the link as "working". + To change that behaviour, set this option to :code-py:`False`. + + .. attention:: + The default value for this option will be changed in Sphinx 8.0; + from that version onwards, + HTTP 401 responses to checked hyperlinks will be treated + as "broken" by default. - The ``linkcheck`` builder may issue a large number of requests to the same - site over a short period of time. This setting controls the builder behavior - when servers indicate that requests are rate-limited. + .. xref RemovedInSphinx80Warning - If a server indicates when to retry (using the `Retry-After`_ header), - ``linkcheck`` always follows the server indication. + .. versionadded:: 7.3 +.. confval:: linkcheck_rate_limit_timeout + :type: :code-py:`int` + :default: :code-py:`300` + + The *linkcheck* builder may issue a large number of requests to the same + site over a short period of time. + This setting controls the builder behaviour + when servers indicate that requests are rate-limited, + by setting the maximum duration (in seconds) that the builder will + wait for between each attempt before recording a failure. + + The *linkcheck* builder always respects a server's direction + of when to retry (using the `Retry-After`_ header). Otherwise, ``linkcheck`` waits for a minute before to retry and keeps doubling the wait time between attempts until it succeeds or exceeds the - ``linkcheck_rate_limit_timeout``. By default, the timeout is 300 seconds. + :confval:`!linkcheck_rate_limit_timeout` (in seconds). Custom timeouts should be given as a number of seconds. .. _Retry-After: https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.3 .. versionadded:: 3.4 -.. confval:: linkcheck_exclude_documents +.. confval:: linkcheck_report_timeouts_as_broken + :type: :code-py:`bool` + :default: :code-py:`True` - A list of regular expressions that match documents in which Sphinx should - not check the validity of links. This can be used for permitting link decay - in legacy or historical sections of the documentation. + When an HTTP response is not received from a webserver before the configured + :confval:`linkcheck_timeout` expires, + the current default behaviour of the *linkcheck* builder is + to treat the link as 'broken'. + To report timeouts using a distinct report code of ``timeout``, + set :confval:`linkcheck_report_timeouts_as_broken` to :code-py:`False`. - Example:: + .. attention:: + From Sphinx 8.0 onwards, timeouts that occur while checking hyperlinks + will be reported using the new 'timeout' status code. - # ignore all links in documents located in a subfolder named 'legacy' - linkcheck_exclude_documents = [r'.*/legacy/.*'] + .. xref RemovedInSphinx80Warning - .. versionadded:: 4.4 + .. versionadded:: 7.3 -.. confval:: linkcheck_allow_unauthorized +.. confval:: linkcheck_request_headers + :type: :code-py:`dict[str, dict[str, str]]` + :default: :code-py:`{}` - When a webserver responds with an HTTP 401 (unauthorized) response, the - current default behaviour of Sphinx is to treat the link as "working". To - change that behaviour, set this option to ``False``. + A dictionary that maps URL (without paths) to HTTP request headers. - The default value for this option will be changed in Sphinx 8.0; from that - version onwards, HTTP 401 responses to checked hyperlinks will be treated - as "broken" by default. + The key is a URL base string like :code-py:`'https://www.sphinx-doc.org/'`. + To specify headers for other hosts, :code-py:`"*"` can be used. + It matches all hosts only when the URL does not match other settings. - .. versionadded:: 7.3 + The value is a dictionary that maps header name to its value. -.. confval:: linkcheck_report_timeouts_as_broken + Example: - When an HTTP response is not received from a webserver before the configured - :confval:`linkcheck_timeout` expires, - the current default behaviour of Sphinx is to treat the link as 'broken'. - To report timeouts using a distinct report code of ``timeout``, - set :confval:`linkcheck_report_timeouts_as_broken` to ``False``. + .. code-block:: python - From Sphinx 8.0 onwards, timeouts that occur while checking hyperlinks - will be reported using the new 'timeout' status code. + linkcheck_request_headers = { + "https://www.sphinx-doc.org/": { + "Accept": "text/html", + "Accept-Encoding": "utf-8", + }, + "*": { + "Accept": "text/html,application/xhtml+xml", + } + } - .. xref RemovedInSphinx80Warning + .. versionadded:: 3.1 - .. versionadded:: 7.3 +.. confval:: linkcheck_retries + :type: :code-py:`int` + :default: :code-py:`1` + The number of times the *linkcheck* builder + will attempt to check a URL before declaring it broken. -Options for the XML builder ---------------------------- + .. versionadded:: 1.4 -.. confval:: xml_pretty +.. confval:: linkcheck_timeout + :type: :code-py:`int` + :default: :code-py:`30` - If true, pretty-print the XML. Default is ``True``. + The duration, in seconds, that the *linkcheck* builder + will wait for a response after each hyperlink request. - .. versionadded:: 1.2 + .. versionadded:: 1.1 +.. confval:: linkcheck_workers + :type: :code-py:`int` + :default: :code-py:`5` + + The number of worker threads to use when checking links. + + .. versionadded:: 1.1 -.. rubric:: Footnotes -.. [1] A note on available globbing syntax: you can use the standard shell - constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that - these all don't match slashes. A double star ``**`` can be used to - match any sequence of characters *including* slashes. +Domain options +============== .. _c-config: @@ -3022,124 +3822,255 @@ Options for the XML builder Options for the C domain ------------------------ -.. confval:: c_id_attributes +.. confval:: c_extra_keywords + :type: :code-py:`Set[str] | Sequence[str]` + :default: :code-py:`['alignas', 'alignof', 'bool', + 'complex', 'imaginary', 'noreturn', + 'static_assert', 'thread_local']` - A list of strings that the parser additionally should accept as attributes. - This can for example be used when attributes have been ``#define`` d for - portability. + A list of identifiers to be recognised as keywords by the C parser. - .. versionadded:: 3.0 + .. versionadded:: 4.0.3 + .. versionchanged:: 7.4 + :confval:`!c_extra_keywords` can now be a set. -.. confval:: c_paren_attributes +.. confval:: c_id_attributes + :type: :code-py:`Sequence[str]` + :default: :code-py:`()` - A list of strings that the parser additionally should accept as attributes - with one argument. That is, if ``my_align_as`` is in the list, then - ``my_align_as(X)`` is parsed as an attribute for all strings ``X`` that have - balanced braces (``()``, ``[]``, and ``{}``). This can for example be used - when attributes have been ``#define`` d for portability. + A sequence of strings that the parser should additionally accept + as attributes. + For example, this can be used when :code-c:`#define` + has been used for attributes, for portability. - .. versionadded:: 3.0 + Example: -.. confval:: c_extra_keywords + .. code-block:: python - A list of identifiers to be recognized as keywords by the C parser. - It defaults to ``['alignas', 'alignof', 'bool', 'complex', 'imaginary', - 'noreturn', 'static_assert', 'thread_local']``. + c_id_attributes = [ + 'my_id_attribute', + ] - .. versionadded:: 4.0.3 + .. versionadded:: 3.0 + .. versionchanged:: 7.4 + :confval:`!c_id_attributes` can now be a tuple. .. confval:: c_maximum_signature_line_length + :type: :code-py:`int | None` + :default: :code-py:`None` + + If a signature's length in characters exceeds the number set, + each parameter within the signature will be displayed on + an individual logical line. + + When :code-py:`None`, there is no maximum length and the entire + signature will be displayed on a single logical line. - If a signature's length in characters exceeds the number set, each - parameter will be displayed on an individual logical line. This is a - domain-specific setting, overriding :confval:`maximum_signature_line_length`. + This is a domain-specific setting, + overriding :confval:`maximum_signature_line_length`. .. versionadded:: 7.1 +.. confval:: c_paren_attributes + :type: :code-py:`Sequence[str]` + :default: :code-py:`()` + + A sequence of strings that the parser should additionally accept + as attributes with one argument. + That is, if ``my_align_as`` is in the list, + then :code-c:`my_align_as(X)` is parsed as an attribute + for all strings ``X`` that have balanced braces + (:code-c:`()`, :code-c:`[]`, and :code-c:`{}`). + For example, this can be used when :code-c:`#define` + has been used for attributes, for portability. + + Example: + + .. code-block:: python + + c_paren_attributes = [ + 'my_align_as', + ] + + .. versionadded:: 3.0 + .. versionchanged:: 7.4 + :confval:`!c_paren_attributes` can now be a tuple. + + .. _cpp-config: Options for the C++ domain -------------------------- -.. confval:: cpp_index_common_prefix +.. confval:: cpp_id_attributes + :type: :code-py:`Sequence[str]` + :default: :code-py:`()` + + A sequence of strings that the parser should additionally accept + as attributes. + For example, this can be used when :code-cpp:`#define` + has been used for attributes, for portability. + + Example: + + .. code-block:: python - A list of prefixes that will be ignored when sorting C++ objects in the - global index. For example ``['awesome_lib::']``. + cpp_id_attributes = [ + 'my_id_attribute', + ] .. versionadded:: 1.5 + .. versionchanged:: 7.4 + :confval:`!cpp_id_attributes` can now be a tuple. -.. confval:: cpp_id_attributes +.. confval:: cpp_index_common_prefix + :type: :code-py:`Sequence[str]` + :default: :code-py:`()` + + A list of prefixes that will be ignored + when sorting C++ objects in the global index. + + Example: + + .. code-block:: python - A list of strings that the parser additionally should accept as attributes. - This can for example be used when attributes have been ``#define`` d for - portability. + cpp_index_common_prefix = [ + 'awesome_lib::', + ] .. versionadded:: 1.5 +.. confval:: cpp_maximum_signature_line_length + :type: :code-py:`int | None` + :default: :code-py:`None` + + If a signature's length in characters exceeds the number set, + each parameter within the signature will be displayed on + an individual logical line. + + When :code-py:`None`, there is no maximum length and the entire + signature will be displayed on a single logical line. + + This is a domain-specific setting, + overriding :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + .. confval:: cpp_paren_attributes + :type: :code-py:`Sequence[str]` + :default: :code-py:`()` + + A sequence of strings that the parser should additionally accept + as attributes with one argument. + That is, if ``my_align_as`` is in the list, + then :code-cpp:`my_align_as(X)` is parsed as an attribute + for all strings ``X`` that have balanced braces + (:code-cpp:`()`, :code-cpp:`[]`, and :code-cpp:`{}`). + For example, this can be used when :code-cpp:`#define` + has been used for attributes, for portability. + + Example: + + .. code-block:: python - A list of strings that the parser additionally should accept as attributes - with one argument. That is, if ``my_align_as`` is in the list, then - ``my_align_as(X)`` is parsed as an attribute for all strings ``X`` that have - balanced braces (``()``, ``[]``, and ``{}``). This can for example be used - when attributes have been ``#define`` d for portability. + cpp_paren_attributes = [ + 'my_align_as', + ] .. versionadded:: 1.5 + .. versionchanged:: 7.4 + :confval:`!cpp_paren_attributes` can now be a tuple. -.. confval:: cpp_maximum_signature_line_length - If a signature's length in characters exceeds the number set, each - parameter will be displayed on an individual logical line. This is a - domain-specific setting, overriding :confval:`maximum_signature_line_length`. +Options for the Javascript domain +--------------------------------- + +.. confval:: javascript_maximum_signature_line_length + :type: :code-py:`int | None` + :default: :code-py:`None` + + If a signature's length in characters exceeds the number set, + each parameter within the signature will be displayed on + an individual logical line. + + When :code-py:`None`, there is no maximum length and the entire + signature will be displayed on a single logical line. + + This is a domain-specific setting, + overriding :confval:`maximum_signature_line_length`. .. versionadded:: 7.1 + Options for the Python domain ----------------------------- +.. confval:: add_module_names + :type: :code-py:`bool` + :default: :code-py:`True` + + A boolean that decides whether module names are prepended + to all :term:`object` names + (for object types where a "module" of some kind is defined), + e.g. for :rst:dir:`py:function` directives. + +.. confval:: modindex_common_prefix + :type: :code-py:`list[str]` + :default: :code-py:`[]` + + A list of prefixes that are ignored for sorting the Python module index + (e.g., if this is set to :code-py:`['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. + + .. caution:: + Works only for the HTML builder currently. + + .. versionadded:: 0.6 + .. confval:: python_display_short_literal_types + :type: :code-py:`bool` + :default: :code-py:`False` This value controls how :py:data:`~typing.Literal` types are displayed. - The setting is a boolean, default ``False``. Examples ~~~~~~~~ The examples below use the following :rst:dir:`py:function` directive: - .. code:: reStructuredText + .. code-block:: reStructuredText .. py:function:: serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None - When ``False``, :py:data:`~typing.Literal` types display as per standard + When :code-py:`False`, :py:data:`~typing.Literal` types display as per standard Python syntax, i.e.: - .. code:: python + .. code-block:: python - serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None + serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None - When ``True``, :py:data:`~typing.Literal` types display with a short, + When :code-py:`True`, :py:data:`~typing.Literal` types display with a short, :PEP:`604`-inspired syntax, i.e.: - .. code:: python + .. code-block:: python - serve_food(item: "egg" | "spam" | "lobster thermidor") -> None + serve_food(item: "egg" | "spam" | "lobster thermidor") -> None .. versionadded:: 6.2 -.. confval:: python_use_unqualified_type_names - - If true, suppress the module name of the python reference if it can be - resolved. The default is ``False``. - - .. versionadded:: 4.0 - - .. note:: This configuration is still in experimental - .. confval:: python_maximum_signature_line_length + :type: :code-py:`int | None` + :default: :code-py:`None` If a signature's length in characters exceeds the number set, - each argument or type parameter will be displayed on an individual logical line. + each parameter within the signature will be displayed on + an individual logical line. + + When :code-py:`None`, there is no maximum length and the entire + signature will be displayed on a single logical line. + This is a domain-specific setting, overriding :confval:`maximum_signature_line_length`. @@ -3149,29 +4080,80 @@ Options for the Python domain for the latter, the signature length ignores the length of the type parameters list. - For instance, with ``python_maximum_signature_line_length = 20``, + For instance, with :code-py:`python_maximum_signature_line_length = 20`, only the list of type parameters will be wrapped while the arguments list will be rendered on a single line - .. code:: rst + .. code-block:: rst .. py:function:: add[T: VERY_LONG_SUPER_TYPE, U: VERY_LONG_SUPER_TYPE](a: T, b: U) .. versionadded:: 7.1 -Options for the Javascript domain ---------------------------------- +.. confval:: python_use_unqualified_type_names + :type: :code-py:`bool` + :default: :code-py:`False` -.. confval:: javascript_maximum_signature_line_length + Suppress the module name of the python reference if it can be resolved. + + .. versionadded:: 4.0 - If a signature's length in characters exceeds the number set, each - parameter will be displayed on an individual logical line. This is a - domain-specific setting, overriding :confval:`maximum_signature_line_length`. + .. caution:: + This feature is experimental. - .. versionadded:: 7.1 +.. confval:: trim_doctest_flags + :type: :code-py:`bool` + :default: :code-py:`True` -Example of configuration file ------------------------------ + Remove doctest flags (comments looking like :code-py:`# doctest: FLAG, ...`) + at the ends of lines and ``<BLANKLINE>`` markers for all code + blocks showing interactive Python sessions (i.e. doctests). + See the extension :mod:`~sphinx.ext.doctest` for more + possibilities of including doctests. + + .. versionadded:: 1.0 + .. versionchanged:: 1.1 + Now also removes ``<BLANKLINE>``. + + +Extension options +================= + +Extensions frequently have their own configuration options. +Those for Sphinx's first-party extensions are documented +in each :doc:`extension's page </usage/extensions/index>`. + + +Example configuration file +========================== + +.. code-block:: python + + # -- Project information ----------------------------------------------------- + # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + + project = 'Test Project' + copyright = '2000-2042, The Test Project Authors' + author = 'The Authors' + version = release = '4.16' + + # -- General configuration ------------------------------------------------ + # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + + exclude_patterns = [ + '_build', + 'Thumbs.db', + '.DS_Store', + ] + extensions = [] + language = 'en' + master_doc = 'index' + pygments_style = 'sphinx' + source_suffix = '.rst' + templates_path = ['_templates'] + + # -- Options for HTML output ---------------------------------------------- + # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -.. literalinclude:: /_static/conf.py.txt - :language: python + html_theme = 'alabaster' + html_static_path = ['_static'] diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index d216d37029a..5fc5d96ef9c 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/doc/usage/extensions/autodoc.rst @@ -745,7 +745,7 @@ There are also config values that you can set: * ``'fully-qualified'`` -- Show the module name and its name of typehints * ``'short'`` -- Suppress the leading module names of the typehints - (ex. ``io.StringIO`` -> ``StringIO``) (default) + (e.g. ``io.StringIO`` -> ``StringIO``) (default) .. versionadded:: 4.4 diff --git a/doc/usage/extensions/graphviz.rst b/doc/usage/extensions/graphviz.rst index 231bd369997..f2a807b0d1c 100644 --- a/doc/usage/extensions/graphviz.rst +++ b/doc/usage/extensions/graphviz.rst @@ -66,7 +66,7 @@ It adds these directives: .. rst:directive:option:: layout: layout type of the graph :type: text - The layout of the graph (ex. ``dot``, ``neato`` and so on). A path to the + The layout of the graph (e.g. ``dot``, ``neato`` and so on). A path to the graphviz commands are also allowed. By default, :confval:`graphviz_dot` is used. diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst index 73fb9c4ef7a..acf4acbcdc7 100644 --- a/doc/usage/restructuredtext/directives.rst +++ b/doc/usage/restructuredtext/directives.rst @@ -49,8 +49,8 @@ tables of contents. The ``toctree`` directive is the central element. indicate the depth of the tree; by default, all levels are included. [#]_ 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. + builders that output multiple files (e.g. HTML) treat it as a collection of + hyperlinks. On the other hand, the builders that output a single file (e.g. LaTeX, man page, etc.) replace it with the content of the documents on the TOC tree. @@ -1060,10 +1060,11 @@ Including content based on tags .. only:: html and draft - Undefined tags are false, defined tags (via the ``-t`` command-line option or - within :file:`conf.py`, see :ref:`here <conf-tags>`) are true. Boolean - expressions, also using parentheses (like ``(latex or html) and draft``) are - supported. + Undefined tags are false, defined tags are true + (tags can be defined via the :option:`--tag <sphinx-build --tag>` + command-line option or within :file:`conf.py`, see :ref:`here <conf-tags>`). + Boolean expressions (like ``(latex or html) and draft``) are supported + and may use parentheses. The *format* and the *name* of the current builder (``html``, ``latex`` or ``text``) are always set as a tag [#]_. To make the distinction between diff --git a/sphinx/builders/gettext.py b/sphinx/builders/gettext.py index 197dc0eac2e..a26b66e77d4 100644 --- a/sphinx/builders/gettext.py +++ b/sphinx/builders/gettext.py @@ -311,7 +311,7 @@ def setup(app: Sphinx) -> ExtensionMetadata: app.add_config_value('gettext_location', True, 'gettext') app.add_config_value('gettext_uuid', False, 'gettext') app.add_config_value('gettext_auto_build', True, 'env') - app.add_config_value('gettext_additional_targets', [], 'env') + app.add_config_value('gettext_additional_targets', [], 'env', types={set, list}) app.add_config_value('gettext_last_translator', 'FULL NAME <EMAIL@ADDRESS>', 'gettext') app.add_config_value('gettext_language_team', 'LANGUAGE <LL@li.org>', 'gettext') app.connect('config-inited', _gettext_compact_validator, priority=800) diff --git a/sphinx/builders/html/__init__.py b/sphinx/builders/html/__init__.py index a83b84eee01..34509600782 100644 --- a/sphinx/builders/html/__init__.py +++ b/sphinx/builders/html/__init__.py @@ -465,19 +465,22 @@ def prepare_writing(self, docnames: set[str]) -> None: # determine the additional indices to include self.domain_indices = [] # html_domain_indices can be False/True or a list of index names - indices_config = self.config.html_domain_indices - if indices_config: + if indices_config := self.config.html_domain_indices: + if not isinstance(indices_config, bool): + check_names = True + indices_config = frozenset(indices_config) + else: + check_names = False for domain_name in sorted(self.env.domains): domain: Domain = self.env.domains[domain_name] - for indexcls in domain.indices: - indexname = f'{domain.name}-{indexcls.name}' - if isinstance(indices_config, list): - if indexname not in indices_config: - continue - content, collapse = indexcls(domain).generate() + for index_cls in domain.indices: + index_name = f'{domain.name}-{index_cls.name}' + if check_names and index_name not in indices_config: + continue + content, collapse = index_cls(domain).generate() if content: self.domain_indices.append( - (indexname, indexcls, content, collapse)) + (index_name, index_cls, content, collapse)) # format the "last updated on" string, only once is enough since it # typically doesn't include the time of day @@ -1314,7 +1317,7 @@ def setup(app: Sphinx) -> ExtensionMetadata: app.add_config_value('html_last_updated_fmt', None, 'html', str) app.add_config_value('html_sidebars', {}, 'html') app.add_config_value('html_additional_pages', {}, 'html') - app.add_config_value('html_domain_indices', True, 'html', list) + app.add_config_value('html_domain_indices', True, 'html', types={set, list}) app.add_config_value('html_permalinks', True, 'html') app.add_config_value('html_permalinks_icon', '¶', 'html') app.add_config_value('html_use_index', True, 'html') diff --git a/sphinx/builders/latex/__init__.py b/sphinx/builders/latex/__init__.py index b40b754b918..f0f000b7388 100644 --- a/sphinx/builders/latex/__init__.py +++ b/sphinx/builders/latex/__init__.py @@ -539,7 +539,7 @@ def setup(app: Sphinx) -> ExtensionMetadata: app.add_config_value('latex_use_xindy', default_latex_use_xindy, '', bool) app.add_config_value('latex_toplevel_sectioning', None, '', ENUM(None, 'part', 'chapter', 'section')) - app.add_config_value('latex_domain_indices', True, '', list) + app.add_config_value('latex_domain_indices', True, '', types={set, list}) app.add_config_value('latex_show_urls', 'no', '') app.add_config_value('latex_show_pagerefs', False, '') app.add_config_value('latex_elements', {}, '') diff --git a/sphinx/builders/texinfo.py b/sphinx/builders/texinfo.py index 8d5a1aa6df0..ece5684fdb8 100644 --- a/sphinx/builders/texinfo.py +++ b/sphinx/builders/texinfo.py @@ -221,7 +221,7 @@ def setup(app: Sphinx) -> ExtensionMetadata: app.add_config_value('texinfo_documents', default_texinfo_documents, '') app.add_config_value('texinfo_appendices', [], '') app.add_config_value('texinfo_elements', {}, '') - app.add_config_value('texinfo_domain_indices', True, '', list) + app.add_config_value('texinfo_domain_indices', True, '', types={set, list}) app.add_config_value('texinfo_show_urls', 'footnote', '') app.add_config_value('texinfo_no_detailmenu', False, '') app.add_config_value('texinfo_cross_references', True, '') diff --git a/sphinx/config.py b/sphinx/config.py index 43781499588..15c585a0a54 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -196,11 +196,11 @@ class Config: config_values: dict[str, _Opt] = { # general options - 'project': _Opt('Python', 'env', ()), - 'author': _Opt('unknown', 'env', ()), + 'project': _Opt('Project name not set', 'env', ()), + 'author': _Opt('Author name not set', 'env', ()), 'project_copyright': _Opt('', 'html', frozenset((str, tuple, list))), 'copyright': _Opt( - lambda c: c.project_copyright, 'html', frozenset((str, tuple, list))), + lambda config: config.project_copyright, 'html', frozenset((str, tuple, list))), 'version': _Opt('', 'env', ()), 'release': _Opt('', 'env', ()), 'today': _Opt('', 'env', ()), @@ -326,34 +326,33 @@ def convert_overrides(self, name: str, value: str) -> Any: valid_types = opt.valid_types if valid_types == Any: return value - elif (type(default) is bool - or (not isinstance(valid_types, ENUM) - and len(valid_types) == 1 and bool in valid_types)): + if (type(default) is bool + or (not isinstance(valid_types, ENUM) + and len(valid_types) == 1 and bool in valid_types)): if isinstance(valid_types, ENUM) or len(valid_types) > 1: # if valid_types are given, and non-bool valid types exist, # return the value without coercing to a Boolean. return value # given falsy string from a command line option return value not in {'0', ''} - elif isinstance(default, dict): + if isinstance(default, dict): raise ValueError(__('cannot override dictionary config setting %r, ' 'ignoring (use %r to set individual elements)') % (name, f'{name}.key=value')) - elif isinstance(default, list): + if isinstance(default, list): return value.split(',') - elif isinstance(default, int): + if isinstance(default, int): try: return int(value) except ValueError as exc: raise ValueError(__('invalid number %r for config value %r, ignoring') % (value, name)) from exc - elif callable(default): + if callable(default): return value - elif default is not None and not isinstance(default, str): - raise ValueError(__('cannot override config setting %r with unsupported ' - 'type, ignoring') % name) - else: + if isinstance(default, str) or default is None: return value + raise ValueError(__('cannot override config setting %r with unsupported ' + 'type, ignoring') % name) @staticmethod def pre_init_values() -> None: @@ -385,13 +384,16 @@ def __repr__(self) -> str: values.append(f"{opt_name}={opt_value!r}") return self.__class__.__qualname__ + '(' + ', '.join(values) + ')' - def __setattr__(self, key: str, value: Any) -> None: - # if someone is still using 'master_doc', we need to update 'root_doc' - if key in ('master_doc', 'root_doc'): + def __setattr__(self, key: str, value: object) -> None: + # Ensure aliases update their counterpart. + if key == 'master_doc': super().__setattr__('root_doc', value) + elif key == 'root_doc': super().__setattr__('master_doc', value) - return - + elif key == 'copyright': + super().__setattr__('project_copyright', value) + elif key == 'project_copyright': + super().__setattr__('copyright', value) super().__setattr__(key, value) def __getattr__(self, name: str) -> Any: @@ -570,10 +572,10 @@ def convert_source_suffix(app: Sphinx, config: Config) -> None: # # The default filetype is determined on later step. # By default, it is considered as restructuredtext. - config.source_suffix = {source_suffix: None} + config.source_suffix = {source_suffix: 'restructuredtext'} elif isinstance(source_suffix, (list, tuple)): # if list, considers as all of them are default filetype - config.source_suffix = dict.fromkeys(source_suffix, None) + config.source_suffix = dict.fromkeys(source_suffix, 'restructuredtext') elif not isinstance(source_suffix, dict): logger.warning(__("The config value `source_suffix' expects " "a string, list of strings, or dictionary. " diff --git a/sphinx/domains/c/__init__.py b/sphinx/domains/c/__init__.py index 5323fbbc3a9..f3698246d64 100644 --- a/sphinx/domains/c/__init__.py +++ b/sphinx/domains/c/__init__.py @@ -835,9 +835,9 @@ def get_objects(self) -> Iterator[tuple[str, str, str, str, str, int]]: def setup(app: Sphinx) -> ExtensionMetadata: app.add_domain(CDomain) - app.add_config_value("c_id_attributes", [], 'env') - app.add_config_value("c_paren_attributes", [], 'env') - app.add_config_value("c_extra_keywords", _macroKeywords, 'env') + app.add_config_value("c_id_attributes", [], 'env', types={list, tuple}) + app.add_config_value("c_paren_attributes", [], 'env', types={list, tuple}) + app.add_config_value("c_extra_keywords", _macroKeywords, 'env', types={set, list}) app.add_config_value("c_maximum_signature_line_length", None, 'env', types={int, None}) app.add_post_transform(AliasTransform) diff --git a/sphinx/domains/cpp/__init__.py b/sphinx/domains/cpp/__init__.py index feafcb70f88..e35300dbb8a 100644 --- a/sphinx/domains/cpp/__init__.py +++ b/sphinx/domains/cpp/__init__.py @@ -1157,8 +1157,8 @@ def get_full_qualified_name(self, node: Element) -> str | None: def setup(app: Sphinx) -> ExtensionMetadata: app.add_domain(CPPDomain) app.add_config_value("cpp_index_common_prefix", [], 'env') - app.add_config_value("cpp_id_attributes", [], 'env') - app.add_config_value("cpp_paren_attributes", [], 'env') + app.add_config_value("cpp_id_attributes", [], 'env', types={list, tuple}) + app.add_config_value("cpp_paren_attributes", [], 'env', types={list, tuple}) app.add_config_value("cpp_maximum_signature_line_length", None, 'env', types={int, None}) app.add_post_transform(AliasTransform) diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 5a2c4678105..ad743b910cf 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -497,20 +497,23 @@ def generate(content: list[tuple[str, list[IndexEntry]]], collapsed: bool) -> No ret = [] # latex_domain_indices can be False/True or a list of index names - indices_config = self.config.latex_domain_indices - if indices_config: - for domain in self.builder.env.domains.values(): - for indexcls in domain.indices: - indexname = f'{domain.name}-{indexcls.name}' - if isinstance(indices_config, list): - if indexname not in indices_config: - continue - content, collapsed = indexcls(domain).generate( - self.builder.docnames) - if not content: + if indices_config := self.config.latex_domain_indices: + if not isinstance(indices_config, bool): + check_names = True + indices_config = frozenset(indices_config) + else: + check_names = False + for domain_name in sorted(self.builder.env.domains): + domain = self.builder.env.domains[domain_name] + for index_cls in domain.indices: + index_name = f'{domain.name}-{index_cls.name}' + if check_names and index_name not in indices_config: continue - ret.append(r'\renewcommand{\indexname}{%s}' % indexcls.localname + CR) - generate(content, collapsed) + content, collapsed = index_cls(domain).generate( + self.builder.docnames) + if content: + ret.append(r'\renewcommand{\indexname}{%s}' % index_cls.localname + CR) + generate(content, collapsed) return ''.join(ret) diff --git a/sphinx/writers/texinfo.py b/sphinx/writers/texinfo.py index 76644497bc0..3f9584f910d 100644 --- a/sphinx/writers/texinfo.py +++ b/sphinx/writers/texinfo.py @@ -476,20 +476,25 @@ def generate(content: list[tuple[str, list[IndexEntry]]], collapsed: bool) -> st ret.append('@end menu\n') return ''.join(ret) - indices_config = self.config.texinfo_domain_indices - if indices_config: - for domain in self.builder.env.domains.values(): - for indexcls in domain.indices: - indexname = f'{domain.name}-{indexcls.name}' - if isinstance(indices_config, list): - if indexname not in indices_config: - continue - content, collapsed = indexcls(domain).generate( - self.builder.docnames) - if not content: + if indices_config := self.config.texinfo_domain_indices: + if not isinstance(indices_config, bool): + check_names = True + indices_config = frozenset(indices_config) + else: + check_names = False + for domain_name in sorted(self.builder.env.domains): + domain = self.builder.env.domains[domain_name] + for index_cls in domain.indices: + index_name = f'{domain.name}-{index_cls.name}' + if check_names and index_name not in indices_config: continue - self.indices.append((indexcls.localname, - generate(content, collapsed))) + content, collapsed = index_cls(domain).generate( + self.builder.docnames) + if content: + self.indices.append(( + index_cls.localname, + generate(content, collapsed), + )) # only add the main Index if it's not empty domain = cast(IndexDomain, self.builder.env.get_domain('index')) for docname in self.builder.docnames: diff --git a/tests/roots/test-root/conf.py b/tests/roots/test-root/conf.py index a14ffaf97fe..25c723b8cca 100644 --- a/tests/roots/test-root/conf.py +++ b/tests/roots/test-root/conf.py @@ -17,7 +17,10 @@ templates_path = ['_templates'] -source_suffix = ['.txt', '.add', '.foo'] +source_suffix = { + '.txt': 'restructuredtext', + '.foo': 'foo', +} project = 'Sphinx <Tests>' copyright = '1234-6789, copyright text credits' @@ -68,7 +71,7 @@ shadowrule=1pt, shadowsep=10pt, shadowsize=10pt, - div.topic_border-width=2pt,% alias to shadowrule + div.topic_border-width=2pt,% alias to shadowrule div.topic_padding=6pt,% alias to shadowsep div.topic_box-shadow=5pt,% overrides/alias shadowsize % diff --git a/tests/test_application.py b/tests/test_application.py index 1fc49d61042..9326ba5ca2a 100644 --- a/tests/test_application.py +++ b/tests/test_application.py @@ -96,7 +96,7 @@ def test_add_source_parser(app, status, warning): # .rst; only in :confval:`source_suffix` assert '.rst' not in app.registry.get_source_parsers() - assert app.registry.source_suffix['.rst'] is None + assert app.registry.source_suffix['.rst'] == 'restructuredtext' # .test; configured by API assert app.registry.source_suffix['.test'] == 'test' diff --git a/tests/test_builders/test_build_dirhtml.py b/tests/test_builders/test_build_dirhtml.py index dc5ab86031d..93609e3fc75 100644 --- a/tests/test_builders/test_build_dirhtml.py +++ b/tests/test_builders/test_build_dirhtml.py @@ -28,13 +28,13 @@ def test_dirhtml(app, status, warning): invdata = InventoryFile.load(f, 'path/to', posixpath.join) assert 'index' in invdata.get('std:doc') - assert invdata['std:doc']['index'] == ('Python', '', 'path/to/', '-') + assert invdata['std:doc']['index'] == ('Project name not set', '', 'path/to/', '-') assert 'foo/index' in invdata.get('std:doc') - assert invdata['std:doc']['foo/index'] == ('Python', '', 'path/to/foo/', '-') + assert invdata['std:doc']['foo/index'] == ('Project name not set', '', 'path/to/foo/', '-') assert 'index' in invdata.get('std:label') - assert invdata['std:label']['index'] == ('Python', '', 'path/to/#index', '-') + assert invdata['std:label']['index'] == ('Project name not set', '', 'path/to/#index', '-') assert 'foo' in invdata.get('std:label') - assert invdata['std:label']['foo'] == ('Python', '', 'path/to/foo/#foo', 'foo/index') + assert invdata['std:label']['foo'] == ('Project name not set', '', 'path/to/foo/#foo', 'foo/index') diff --git a/tests/test_builders/test_build_epub.py b/tests/test_builders/test_build_epub.py index 461ff8cc619..691ffcce1be 100644 --- a/tests/test_builders/test_build_epub.py +++ b/tests/test_builders/test_build_epub.py @@ -67,7 +67,7 @@ def test_build_epub(app): # toc.ncx toc = EPUBElementTree.fromstring((app.outdir / 'toc.ncx').read_text(encoding='utf8')) - assert toc.find("./ncx:docTitle/ncx:text").text == 'Python' + assert toc.find("./ncx:docTitle/ncx:text").text == 'Project name not set' # toc.ncx / head meta = list(toc.find("./ncx:head")) @@ -91,11 +91,11 @@ def test_build_epub(app): # content.opf / metadata metadata = opf.find("./idpf:metadata") assert metadata.find("./dc:language").text == 'en' - assert metadata.find("./dc:title").text == 'Python' + assert metadata.find("./dc:title").text == 'Project name not set' assert metadata.find("./dc:description").text == 'unknown' - assert metadata.find("./dc:creator").text == 'unknown' + assert metadata.find("./dc:creator").text == 'Author name not set' assert metadata.find("./dc:contributor").text == 'unknown' - assert metadata.find("./dc:publisher").text == 'unknown' + assert metadata.find("./dc:publisher").text == 'Author name not set' assert metadata.find("./dc:rights").text is None assert metadata.find("./idpf:meta[@property='ibooks:version']").text is None assert metadata.find("./idpf:meta[@property='ibooks:specified-fonts']").text == 'true' @@ -171,7 +171,7 @@ def test_nested_toc(app): # toc.ncx toc = EPUBElementTree.fromstring((app.outdir / 'toc.ncx').read_bytes()) - assert toc.find("./ncx:docTitle/ncx:text").text == 'Python' + assert toc.find("./ncx:docTitle/ncx:text").text == 'Project name not set' # toc.ncx / navPoint def navinfo(elem): diff --git a/tests/test_builders/test_build_html.py b/tests/test_builders/test_build_html.py index 13f0a7b04e6..529f6b10db9 100644 --- a/tests/test_builders/test_build_html.py +++ b/tests/test_builders/test_build_html.py @@ -131,24 +131,24 @@ def test_html_inventory(app): 'py-modindex', 'genindex', 'search'} - assert invdata['std:label']['modindex'] == ('Python', + assert invdata['std:label']['modindex'] == ('Project name not set', '', 'https://www.google.com/py-modindex.html', 'Module Index') - assert invdata['std:label']['py-modindex'] == ('Python', + assert invdata['std:label']['py-modindex'] == ('Project name not set', '', 'https://www.google.com/py-modindex.html', 'Python Module Index') - assert invdata['std:label']['genindex'] == ('Python', + assert invdata['std:label']['genindex'] == ('Project name not set', '', 'https://www.google.com/genindex.html', 'Index') - assert invdata['std:label']['search'] == ('Python', + assert invdata['std:label']['search'] == ('Project name not set', '', 'https://www.google.com/search.html', 'Search Page') assert set(invdata['std:doc'].keys()) == {'index'} - assert invdata['std:doc']['index'] == ('Python', + assert invdata['std:doc']['index'] == ('Project name not set', '', 'https://www.google.com/index.html', 'The basic Sphinx documentation for testing') @@ -223,7 +223,7 @@ def test_html_sidebar(app, status, warning): result = (app.outdir / 'index.html').read_text(encoding='utf8') assert ('<div class="sphinxsidebar" role="navigation" ' 'aria-label="Main">' in result) - assert '<h1 class="logo"><a href="#">Python</a></h1>' in result + assert '<h1 class="logo"><a href="#">Project name not set</a></h1>' in result assert '<h3>Navigation</h3>' in result assert '<h3>Related Topics</h3>' in result assert '<h3 id="searchlabel">Quick search</h3>' in result diff --git a/tests/test_builders/test_build_html_image.py b/tests/test_builders/test_build_html_image.py index 365b0110ff0..860beb6b765 100644 --- a/tests/test_builders/test_build_html_image.py +++ b/tests/test_builders/test_build_html_image.py @@ -29,7 +29,7 @@ def test_html_remote_logo(app, status, warning): app.build(force_all=True) result = (app.outdir / 'index.html').read_text(encoding='utf8') - assert ('<img class="logo" src="https://www.python.org/static/img/python-logo.png" alt="Logo of Python"/>' in result) + assert ('<img class="logo" src="https://www.python.org/static/img/python-logo.png" alt="Logo of Project name not set"/>' in result) assert ('<link rel="icon" href="https://www.python.org/static/favicon.ico"/>' in result) assert not (app.outdir / 'python-logo.png').exists() @@ -39,7 +39,7 @@ def test_html_local_logo(app, status, warning): app.build(force_all=True) result = (app.outdir / 'index.html').read_text(encoding='utf8') - assert ('<img class="logo" src="_static/img.png" alt="Logo of Python"/>' in result) + assert ('<img class="logo" src="_static/img.png" alt="Logo of Project name not set"/>' in result) assert (app.outdir / '_static/img.png').exists() diff --git a/tests/test_builders/test_build_latex.py b/tests/test_builders/test_build_latex.py index 88c83560b87..a34d69e1f48 100644 --- a/tests/test_builders/test_build_latex.py +++ b/tests/test_builders/test_build_latex.py @@ -41,7 +41,7 @@ def kpsetest(*filenames): # compile latex document with app.config.latex_engine -def compile_latex_document(app, filename='python.tex', docclass='manual'): +def compile_latex_document(app, filename='projectnamenotset.tex', docclass='manual'): # now, try to run latex over it try: with chdir(app.outdir): @@ -255,7 +255,7 @@ def test_latex_basic_howto_ja(app, status, warning): @pytest.mark.sphinx('latex', testroot='latex-theme') def test_latex_theme(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) assert r'\def\sphinxdocclass{book}' in result assert r'\documentclass[a4paper,12pt,english]{sphinxbook}' in result @@ -266,7 +266,7 @@ def test_latex_theme(app, status, warning): 'pointsize': '9pt'}}) def test_latex_theme_papersize(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) assert r'\def\sphinxdocclass{book}' in result assert r'\documentclass[b5paper,9pt,english]{sphinxbook}' in result @@ -277,7 +277,7 @@ def test_latex_theme_papersize(app, status, warning): 'pointsize': '9pt'}}) def test_latex_theme_options(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) assert r'\def\sphinxdocclass{book}' in result assert r'\documentclass[b5paper,9pt,english]{sphinxbook}' in result @@ -330,7 +330,7 @@ def test_latex_release(app, status, warning): confoverrides={'numfig': True}) def test_numref(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -372,7 +372,7 @@ def test_numref(app, status, warning): 'section': 'SECTION-%s'}}) def test_numref_with_prefix1(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -420,7 +420,7 @@ def test_numref_with_prefix1(app, status, warning): 'section': 'SECTION_%s_'}}) def test_numref_with_prefix2(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -460,7 +460,7 @@ def test_numref_with_prefix2(app, status, warning): confoverrides={'numfig': True, 'language': 'ja'}) def test_numref_with_language_ja(app, status, warning): app.build() - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -556,7 +556,7 @@ def test_latex_add_latex_package(app, status, warning): @pytest.mark.sphinx('latex', testroot='latex-babel') def test_babel_with_no_language_settings(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -581,7 +581,7 @@ def test_babel_with_no_language_settings(app, status, warning): confoverrides={'language': 'de'}) def test_babel_with_language_de(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -606,7 +606,7 @@ def test_babel_with_language_de(app, status, warning): confoverrides={'language': 'ru'}) def test_babel_with_language_ru(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -631,7 +631,7 @@ def test_babel_with_language_ru(app, status, warning): confoverrides={'language': 'tr'}) def test_babel_with_language_tr(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -656,7 +656,7 @@ def test_babel_with_language_tr(app, status, warning): confoverrides={'language': 'ja'}) def test_babel_with_language_ja(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -680,7 +680,7 @@ def test_babel_with_language_ja(app, status, warning): confoverrides={'language': 'unknown'}) def test_babel_with_unknown_language(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -707,7 +707,7 @@ def test_babel_with_unknown_language(app, status, warning): confoverrides={'language': 'de', 'latex_engine': 'lualatex'}) def test_polyglossia_with_language_de(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -733,7 +733,7 @@ def test_polyglossia_with_language_de(app, status, warning): confoverrides={'language': 'de-1901', 'latex_engine': 'lualatex'}) def test_polyglossia_with_language_de_1901(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -786,7 +786,7 @@ def test_footnote(app, status, warning): @pytest.mark.sphinx('latex', testroot='footnotes') def test_reference_in_caption_and_codeblock_in_footnote(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -826,7 +826,7 @@ def test_reference_in_caption_and_codeblock_in_footnote(app, status, warning): @pytest.mark.sphinx('latex', testroot='footnotes') def test_footnote_referred_multiple_times(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -848,7 +848,7 @@ def test_footnote_referred_multiple_times(app, status, warning): confoverrides={'latex_show_urls': 'inline'}) def test_latex_show_urls_is_inline(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -905,7 +905,7 @@ def test_latex_show_urls_is_inline(app, status, warning): confoverrides={'latex_show_urls': 'footnote'}) def test_latex_show_urls_is_footnote(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -967,7 +967,7 @@ def test_latex_show_urls_is_footnote(app, status, warning): confoverrides={'latex_show_urls': 'no'}) def test_latex_show_urls_is_no(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -1022,7 +1022,7 @@ def test_latex_show_urls_footnote_and_substitutions(app, status, warning): @pytest.mark.sphinx('latex', testroot='image-in-section') def test_image_in_section(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -1045,7 +1045,7 @@ def test_latex_logo_if_not_found(app, status, warning): @pytest.mark.sphinx('latex', testroot='toctree-maxdepth') def test_toctree_maxdepth_manual(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -1057,12 +1057,12 @@ def test_toctree_maxdepth_manual(app, status, warning): @pytest.mark.sphinx( 'latex', testroot='toctree-maxdepth', confoverrides={'latex_documents': [ - ('index', 'python.tex', 'Sphinx Tests Documentation', + ('index', 'projectnamenotset.tex', 'Sphinx Tests Documentation', 'Georg Brandl', 'howto'), ]}) def test_toctree_maxdepth_howto(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -1076,7 +1076,7 @@ def test_toctree_maxdepth_howto(app, status, warning): confoverrides={'root_doc': 'foo'}) def test_toctree_not_found(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -1090,7 +1090,7 @@ def test_toctree_not_found(app, status, warning): confoverrides={'root_doc': 'bar'}) def test_toctree_without_maxdepth(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -1103,7 +1103,7 @@ def test_toctree_without_maxdepth(app, status, warning): confoverrides={'root_doc': 'qux'}) def test_toctree_with_deeper_maxdepth(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -1116,7 +1116,7 @@ def test_toctree_with_deeper_maxdepth(app, status, warning): confoverrides={'latex_toplevel_sectioning': None}) def test_latex_toplevel_sectioning_is_None(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -1128,7 +1128,7 @@ def test_latex_toplevel_sectioning_is_None(app, status, warning): confoverrides={'latex_toplevel_sectioning': 'part'}) def test_latex_toplevel_sectioning_is_part(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -1141,12 +1141,12 @@ def test_latex_toplevel_sectioning_is_part(app, status, warning): 'latex', testroot='toctree-maxdepth', confoverrides={'latex_toplevel_sectioning': 'part', 'latex_documents': [ - ('index', 'python.tex', 'Sphinx Tests Documentation', + ('index', 'projectnamenotset.tex', 'Sphinx Tests Documentation', 'Georg Brandl', 'howto'), ]}) def test_latex_toplevel_sectioning_is_part_with_howto(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -1160,7 +1160,7 @@ def test_latex_toplevel_sectioning_is_part_with_howto(app, status, warning): confoverrides={'latex_toplevel_sectioning': 'chapter'}) def test_latex_toplevel_sectioning_is_chapter(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -1171,12 +1171,12 @@ def test_latex_toplevel_sectioning_is_chapter(app, status, warning): 'latex', testroot='toctree-maxdepth', confoverrides={'latex_toplevel_sectioning': 'chapter', 'latex_documents': [ - ('index', 'python.tex', 'Sphinx Tests Documentation', + ('index', 'projectnamenotset.tex', 'Sphinx Tests Documentation', 'Georg Brandl', 'howto'), ]}) def test_latex_toplevel_sectioning_is_chapter_with_howto(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -1188,7 +1188,7 @@ def test_latex_toplevel_sectioning_is_chapter_with_howto(app, status, warning): confoverrides={'latex_toplevel_sectioning': 'section'}) def test_latex_toplevel_sectioning_is_section(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) @@ -1199,11 +1199,11 @@ def test_latex_toplevel_sectioning_is_section(app, status, warning): @pytest.mark.sphinx('latex', testroot='maxlistdepth') def test_maxlistdepth_at_ten(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) print(status.getvalue()) print(warning.getvalue()) - compile_latex_document(app, 'python.tex') + compile_latex_document(app, 'projectnamenotset.tex') @pytest.mark.sphinx('latex', testroot='latex-table', @@ -1211,7 +1211,7 @@ def test_maxlistdepth_at_ten(app, status, warning): @pytest.mark.test_params(shared_result='latex-table') def test_latex_table_tabulars(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') tables = {} for chap in re.split(r'\\(?:section|chapter){', result)[1:]: sectname, content = chap.split('}', 1) @@ -1282,7 +1282,7 @@ def get_expected(name): @pytest.mark.test_params(shared_result='latex-table') def test_latex_table_longtable(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') tables = {} for chap in re.split(r'\\(?:section|chapter){', result)[1:]: sectname, content = chap.split('}', 1) @@ -1343,7 +1343,7 @@ def get_expected(name): @pytest.mark.test_params(shared_result='latex-table') def test_latex_table_complex_tables(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') tables = {} for chap in re.split(r'\\(?:section|renewcommand){', result)[1:]: sectname, content = chap.split('}', 1) @@ -1373,7 +1373,7 @@ def get_expected(name): @pytest.mark.sphinx('latex', testroot='latex-table') def test_latex_table_with_booktabs_and_colorrows(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') assert r'\PassOptionsToPackage{booktabs}{sphinx}' in result assert r'\PassOptionsToPackage{colorrows}{sphinx}' in result # tabularcolumns @@ -1389,7 +1389,7 @@ def test_latex_table_with_booktabs_and_colorrows(app, status, warning): confoverrides={'templates_path': ['_mytemplates/latex']}) def test_latex_table_custom_template_caseA(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') assert 'SALUT LES COPAINS' in result assert 'AU REVOIR, KANIGGETS' in result @@ -1398,7 +1398,7 @@ def test_latex_table_custom_template_caseA(app, status, warning): confoverrides={'templates_path': ['_mytemplates']}) def test_latex_table_custom_template_caseB(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') assert 'SALUT LES COPAINS' not in result @@ -1406,14 +1406,14 @@ def test_latex_table_custom_template_caseB(app, status, warning): @pytest.mark.test_params(shared_result='latex-table') def test_latex_table_custom_template_caseC(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') assert 'SALUT LES COPAINS' not in result @pytest.mark.sphinx('latex', testroot='directives-raw') def test_latex_raw_directive(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') # standard case assert 'standalone raw directive (HTML)' not in result @@ -1430,7 +1430,7 @@ def test_latex_images(app, status, warning): with http_server(RemoteImageHandler, port=7777): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') # images are copied assert '\\sphinxincludegraphics{{sphinx}.png}' in result @@ -1454,7 +1454,7 @@ def test_latex_images(app, status, warning): def test_latex_index(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') assert ('A \\index{famous@\\spxentry{famous}}famous ' '\\index{equation@\\spxentry{equation}}equation:\n' in result) assert ('\n\\index{Einstein@\\spxentry{Einstein}}' @@ -1468,7 +1468,7 @@ def test_latex_index(app, status, warning): def test_latex_equations(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') expected = (app.srcdir / 'expects' / 'latex-equations.tex').read_text(encoding='utf8').strip() assert expected in result @@ -1478,7 +1478,7 @@ def test_latex_equations(app, status, warning): def test_latex_image_in_parsed_literal(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') assert ('{\\sphinxunactivateextrasandspace \\raisebox{-0.5\\height}' '{\\sphinxincludegraphics[height=2.00000cm]{{pic}.png}}' '}AFTER') in result @@ -1488,7 +1488,7 @@ def test_latex_image_in_parsed_literal(app, status, warning): def test_latex_nested_enumerated_list(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') assert ('\\sphinxsetlistlabels{\\arabic}{enumi}{enumii}{}{.}%\n' '\\setcounter{enumi}{4}\n' in result) assert ('\\sphinxsetlistlabels{\\alph}{enumii}{enumiii}{}{.}%\n' @@ -1505,7 +1505,7 @@ def test_latex_nested_enumerated_list(app, status, warning): def test_latex_thebibliography(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) assert ('\\begin{sphinxthebibliography}{AuthorYe}\n' '\\bibitem[AuthorYear]{index:authoryear}\n\\sphinxAtStartPar\n' @@ -1518,7 +1518,7 @@ def test_latex_thebibliography(app, status, warning): def test_latex_glossary(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') assert (r'\sphinxlineitem{ähnlich\index{ähnlich@\spxentry{ähnlich}|spxpagem}' r'\phantomsection' r'\label{\detokenize{index:term-ahnlich}}}' in result) @@ -1542,7 +1542,7 @@ def test_latex_glossary(app, status, warning): def test_latex_labels(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') # figures assert (r'\caption{labeled figure}' @@ -1590,7 +1590,7 @@ def test_latex_labels(app, status, warning): @pytest.mark.sphinx('latex', testroot='latex-figure-in-admonition') def test_latex_figure_in_admonition(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') assert r'\begin{figure}[H]' in result @@ -1620,7 +1620,7 @@ def test_includegraphics_oversized(app, status, warning): @pytest.mark.sphinx('latex', testroot='index_on_title') def test_index_on_title(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') assert ('\\chapter{Test for index in top level title}\n' '\\label{\\detokenize{contents:test-for-index-in-top-level-title}}' '\\index{index@\\spxentry{index}}\n' @@ -1631,7 +1631,7 @@ def test_index_on_title(app, status, warning): confoverrides={'latex_engine': 'pdflatex'}) def test_texescape_for_non_unicode_supported_engine(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) assert 'script small e: e' in result assert 'double struck italic small i: i' in result @@ -1643,7 +1643,7 @@ def test_texescape_for_non_unicode_supported_engine(app, status, warning): confoverrides={'latex_engine': 'xelatex'}) def test_texescape_for_unicode_supported_engine(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(result) assert 'script small e: e' in result assert 'double struck italic small i: i' in result @@ -1668,7 +1668,7 @@ def test_latex_nested_tables(app, status, warning): @pytest.mark.sphinx('latex', testroot='latex-container') def test_latex_container(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') assert r'\begin{sphinxuseclass}{classname}' in result assert r'\end{sphinxuseclass}' in result @@ -1676,7 +1676,7 @@ def test_latex_container(app, status, warning): @pytest.mark.sphinx('latex', testroot='reST-code-role') def test_latex_code_role(app): app.build() - content = (app.outdir / 'python.tex').read_text(encoding='utf8') + content = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') common_content = ( r'\PYG{k}{def} ' @@ -1721,7 +1721,7 @@ def test_copy_images(app, status, warning): @pytest.mark.sphinx('latex', testroot='latex-labels-before-module') def test_duplicated_labels_before_module(app, status, warning): app.build() - content: str = (app.outdir / 'python.tex').read_text(encoding='utf8') + content: str = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') def count_label(name): text = r'\phantomsection\label{\detokenize{%s}}' % name @@ -1752,7 +1752,7 @@ def count_label(name): confoverrides={'python_maximum_signature_line_length': 23}) def test_one_parameter_per_line(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') # TODO: should these asserts check presence or absence of a final \sphinxparamcomma? # signature of 23 characters is too short to trigger one-param-per-line mark-up diff --git a/tests/test_builders/test_build_manpage.py b/tests/test_builders/test_build_manpage.py index 7172281968c..0958b30f302 100644 --- a/tests/test_builders/test_build_manpage.py +++ b/tests/test_builders/test_build_manpage.py @@ -44,13 +44,13 @@ def test_man_pages_empty_description(app, status, warning): confoverrides={'man_make_section_directory': True}) def test_man_make_section_directory(app, status, warning): app.build() - assert (app.outdir / 'man1' / 'python.1').exists() + assert (app.outdir / 'man1' / 'projectnamenotset.1').exists() @pytest.mark.sphinx('man', testroot='directive-code') def test_captioned_code_block(app, status, warning): app.build(force_all=True) - content = (app.outdir / 'python.1').read_text(encoding='utf8') + content = (app.outdir / 'projectnamenotset.1').read_text(encoding='utf8') if docutils.__version_info__[:2] < (0, 21): expected = """\ @@ -100,5 +100,5 @@ def test_default_man_pages(): @pytest.mark.sphinx('man', testroot='markup-rubric') def test_rubric(app, status, warning): app.build() - content = (app.outdir / 'python.1').read_text(encoding='utf8') + content = (app.outdir / 'projectnamenotset.1').read_text(encoding='utf8') assert 'This is a rubric\n' in content diff --git a/tests/test_builders/test_build_texinfo.py b/tests/test_builders/test_build_texinfo.py index 3b8e27662ea..539ec9a96e7 100644 --- a/tests/test_builders/test_build_texinfo.py +++ b/tests/test_builders/test_build_texinfo.py @@ -40,7 +40,7 @@ def test_texinfo(app, status, warning): def test_texinfo_rubric(app, status, warning): app.build() - output = (app.outdir / 'python.texi').read_text(encoding='utf8') + output = (app.outdir / 'projectnamenotset.texi').read_text(encoding='utf8') assert '@heading This is a rubric' in output assert '@heading This is a multiline rubric' in output @@ -49,7 +49,7 @@ def test_texinfo_rubric(app, status, warning): def test_texinfo_citation(app, status, warning): app.build(force_all=True) - output = (app.outdir / 'python.texi').read_text(encoding='utf8') + output = (app.outdir / 'projectnamenotset.texi').read_text(encoding='utf8') assert 'This is a citation ref; @ref{1,,[CITE1]} and @ref{2,,[CITE2]}.' in output assert ('@anchor{index cite1}@anchor{1}@w{(CITE1)} \n' 'This is a citation\n') in output @@ -87,7 +87,7 @@ def test_texinfo_escape_id(app, status, warning): def test_texinfo_footnote(app, status, warning): app.build(force_all=True) - output = (app.outdir / 'python.texi').read_text(encoding='utf8') + output = (app.outdir / 'projectnamenotset.texi').read_text(encoding='utf8') assert 'First footnote: @footnote{\nFirst\n}' in output @@ -120,7 +120,7 @@ def test_texinfo_samp_with_variable(app, status, warning): def test_copy_images(app, status, warning): app.build() - images_dir = Path(app.outdir) / 'python-figures' + images_dir = Path(app.outdir) / 'projectnamenotset-figures' images = {image.name for image in images_dir.rglob('*')} images.discard('python-logo.png') assert images == { diff --git a/tests/test_directives/test_directive_code.py b/tests/test_directives/test_directive_code.py index 9f038ec19ad..618019543e5 100644 --- a/tests/test_directives/test_directive_code.py +++ b/tests/test_directives/test_directive_code.py @@ -330,7 +330,7 @@ def test_code_block_caption_html(app, status, warning): @pytest.mark.sphinx('latex', testroot='directive-code') def test_code_block_caption_latex(app, status, warning): app.build(force_all=True) - latex = (app.outdir / 'python.tex').read_text(encoding='utf8') + latex = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') caption = '\\sphinxSetupCaptionForVerbatim{caption \\sphinxstyleemphasis{test} rb}' label = '\\def\\sphinxLiteralBlockLabel{\\label{\\detokenize{caption:id1}}}' link = '\\hyperref[\\detokenize{caption:name-test-rb}]' \ @@ -343,7 +343,7 @@ def test_code_block_caption_latex(app, status, warning): @pytest.mark.sphinx('latex', testroot='directive-code') def test_code_block_namedlink_latex(app, status, warning): app.build(force_all=True) - latex = (app.outdir / 'python.tex').read_text(encoding='utf8') + latex = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') label1 = '\\def\\sphinxLiteralBlockLabel{\\label{\\detokenize{caption:name-test-rb}}}' link1 = '\\hyperref[\\detokenize{caption:name-test-rb}]'\ '{\\sphinxcrossref{\\DUrole{std,std-ref}{Ruby}}' @@ -360,7 +360,7 @@ def test_code_block_namedlink_latex(app, status, warning): @pytest.mark.sphinx('latex', testroot='directive-code') def test_code_block_emphasize_latex(app, status, warning): app.build(filenames=[app.srcdir / 'emphasize.rst']) - latex = (app.outdir / 'python.tex').read_text(encoding='utf8').replace('\r\n', '\n') + latex = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8').replace('\r\n', '\n') includes = '\\fvset{hllines={, 5, 6, 13, 14, 15, 24, 25, 26,}}%\n' assert includes in latex includes = '\\end{sphinxVerbatim}\n\\sphinxresetverbatimhllines\n' @@ -424,7 +424,7 @@ def test_literal_include_linenos(app, status, warning): @pytest.mark.sphinx('latex', testroot='directive-code') def test_literalinclude_file_whole_of_emptyline(app, status, warning): app.build(force_all=True) - latex = (app.outdir / 'python.tex').read_text(encoding='utf8').replace('\r\n', '\n') + latex = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8').replace('\r\n', '\n') includes = ( '\\begin{sphinxVerbatim}' '[commandchars=\\\\\\{\\},numbers=left,firstnumber=1,stepnumber=1]\n' @@ -450,7 +450,7 @@ def test_literalinclude_caption_html(app, status, warning): @pytest.mark.sphinx('latex', testroot='directive-code') def test_literalinclude_caption_latex(app, status, warning): app.build(filenames='index') - latex = (app.outdir / 'python.tex').read_text(encoding='utf8') + latex = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') caption = '\\sphinxSetupCaptionForVerbatim{caption \\sphinxstylestrong{test} py}' label = '\\def\\sphinxLiteralBlockLabel{\\label{\\detokenize{caption:id2}}}' link = '\\hyperref[\\detokenize{caption:name-test-py}]' \ @@ -463,7 +463,7 @@ def test_literalinclude_caption_latex(app, status, warning): @pytest.mark.sphinx('latex', testroot='directive-code') def test_literalinclude_namedlink_latex(app, status, warning): app.build(filenames='index') - latex = (app.outdir / 'python.tex').read_text(encoding='utf8') + latex = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') label1 = '\\def\\sphinxLiteralBlockLabel{\\label{\\detokenize{caption:name-test-py}}}' link1 = '\\hyperref[\\detokenize{caption:name-test-py}]'\ '{\\sphinxcrossref{\\DUrole{std,std-ref}{Python}}' diff --git a/tests/test_extensions/test_ext_autosummary.py b/tests/test_extensions/test_ext_autosummary.py index 5f767379df0..1aa8f4afb25 100644 --- a/tests/test_extensions/test_ext_autosummary.py +++ b/tests/test_extensions/test_ext_autosummary.py @@ -545,7 +545,7 @@ def test_autosummary_filename_map(app, status, warning): @pytest.mark.sphinx('latex', **default_kw) def test_autosummary_latex_table_colspec(app, status, warning): app.build(force_all=True) - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') print(status.getvalue()) print(warning.getvalue()) assert r'\begin{longtable}{\X{1}{2}\X{1}{2}}' in result diff --git a/tests/test_extensions/test_ext_graphviz.py b/tests/test_extensions/test_ext_graphviz.py index 866a92aa89c..cd1fd92a003 100644 --- a/tests/test_extensions/test_ext_graphviz.py +++ b/tests/test_extensions/test_ext_graphviz.py @@ -105,7 +105,7 @@ def test_graphviz_svg_html(app, status, warning): def test_graphviz_latex(app, status, warning): app.build(force_all=True) - content = (app.outdir / 'python.tex').read_text(encoding='utf8') + content = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') macro = ('\\\\begin{figure}\\[htbp\\]\n\\\\centering\n\\\\capstart\n\n' '\\\\sphinxincludegraphics\\[\\]{graphviz-\\w+.pdf}\n' '\\\\caption{caption of graph}\\\\label{.*}\\\\end{figure}') diff --git a/tests/test_extensions/test_ext_imgconverter.py b/tests/test_extensions/test_ext_imgconverter.py index a56827b7ac5..fee659351df 100644 --- a/tests/test_extensions/test_ext_imgconverter.py +++ b/tests/test_extensions/test_ext_imgconverter.py @@ -24,7 +24,7 @@ def _if_converter_found(app): def test_ext_imgconverter(app, status, warning): app.build(force_all=True) - content = (app.outdir / 'python.tex').read_text(encoding='utf8') + content = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') # supported image (not converted) assert '\\sphinxincludegraphics{{img}.pdf}' in content diff --git a/tests/test_extensions/test_ext_imgmockconverter.py b/tests/test_extensions/test_ext_imgmockconverter.py index 4c3c64e03c1..c1552746395 100644 --- a/tests/test_extensions/test_ext_imgmockconverter.py +++ b/tests/test_extensions/test_ext_imgmockconverter.py @@ -7,7 +7,7 @@ def test_ext_imgmockconverter(app, status, warning): app.build(force_all=True) - content = (app.outdir / 'python.tex').read_text(encoding='utf8') + content = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') # check identical basenames give distinct files assert '\\sphinxincludegraphics{{svgimg}.pdf}' in content diff --git a/tests/test_extensions/test_ext_inheritance_diagram.py b/tests/test_extensions/test_ext_inheritance_diagram.py index c13ccea9247..45a5ff0dda9 100644 --- a/tests/test_extensions/test_ext_inheritance_diagram.py +++ b/tests/test_extensions/test_ext_inheritance_diagram.py @@ -251,7 +251,7 @@ def test_inheritance_diagram_svg_html(tmp_path, app): def test_inheritance_diagram_latex(app, status, warning): app.build(force_all=True) - content = (app.outdir / 'python.tex').read_text(encoding='utf8') + content = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') pattern = ('\\\\begin{figure}\\[htbp]\n\\\\centering\n\\\\capstart\n\n' '\\\\sphinxincludegraphics\\[\\]{inheritance-\\w+.pdf}\n' diff --git a/tests/test_extensions/test_ext_math.py b/tests/test_extensions/test_ext_math.py index b673f83d298..bbff31f2c09 100644 --- a/tests/test_extensions/test_ext_math.py +++ b/tests/test_extensions/test_ext_math.py @@ -127,7 +127,7 @@ def test_math_number_all_mathjax(app, status, warning): def test_math_number_all_latex(app, status, warning): app.build() - content = (app.outdir / 'python.tex').read_text(encoding='utf8') + content = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') macro = (r'\\begin{equation\*}\s*' r'\\begin{split}a\^2\+b\^2=c\^2\\end{split}\s*' r'\\end{equation\*}') @@ -170,7 +170,7 @@ def test_math_eqref_format_html(app, status, warning): def test_math_eqref_format_latex(app, status, warning): app.build(force_all=True) - content = (app.outdir / 'python.tex').read_text(encoding='utf8') + content = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') macro = (r'Referencing equation Eq.\\ref{equation:math:foo} and ' r'Eq.\\ref{equation:math:foo}.') assert re.search(macro, content, re.DOTALL) diff --git a/tests/test_extensions/test_ext_todo.py b/tests/test_extensions/test_ext_todo.py index 1903f9f9ddb..5acfcac3a8d 100644 --- a/tests/test_extensions/test_ext_todo.py +++ b/tests/test_extensions/test_ext_todo.py @@ -89,7 +89,7 @@ def test_todo_valid_link(app, status, warning): # Ensure the LaTeX output is built. app.build(force_all=True) - content = (app.outdir / 'python.tex').read_text(encoding='utf8') + content = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') # Look for the link to foo. Note that there are two of them because the # source document uses todolist twice. We could equally well look for links diff --git a/tests/test_markup/test_smartquotes.py b/tests/test_markup/test_smartquotes.py index 6c84386dc20..b35f05f865a 100644 --- a/tests/test_markup/test_smartquotes.py +++ b/tests/test_markup/test_smartquotes.py @@ -41,7 +41,7 @@ def test_text_builder(app, status, warning): def test_man_builder(app, status, warning): app.build() - content = (app.outdir / 'python.1').read_text(encoding='utf8') + content = (app.outdir / 'projectnamenotset.1').read_text(encoding='utf8') assert r'\-\- \(dqSphinx\(dq is a tool that makes it easy ...' in content @@ -49,7 +49,7 @@ def test_man_builder(app, status, warning): def test_latex_builder(app, status, warning): app.build() - content = (app.outdir / 'python.tex').read_text(encoding='utf8') + content = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') assert '\\textendash{} “Sphinx” is a tool that makes it easy …' in content @@ -94,5 +94,5 @@ def test_smartquotes_excludes_language(app, status, warning): def test_smartquotes_excludes_builders(app, status, warning): app.build() - content = (app.outdir / 'python.1').read_text(encoding='utf8') + content = (app.outdir / 'projectnamenotset.1').read_text(encoding='utf8') assert '– “Sphinx” is a tool that makes it easy …' in content diff --git a/tests/test_theming/test_theming.py b/tests/test_theming/test_theming.py index 56b179030bd..680465ba4d0 100644 --- a/tests/test_theming/test_theming.py +++ b/tests/test_theming/test_theming.py @@ -112,12 +112,12 @@ def test_staticfiles(app, status, warning): assert (app.outdir / '_static' / 'legacytmpl.html').exists() assert (app.outdir / '_static' / 'legacytmpl.html').read_text(encoding='utf8') == ( '<!-- testing legacy _t static templates -->\n' - '<html><project>python</project></html>' + '<html><project>project name not set</project></html>' ) assert (app.outdir / '_static' / 'staticimg.png').exists() assert (app.outdir / '_static' / 'statictmpl.html').exists() assert (app.outdir / '_static' / 'statictmpl.html').read_text(encoding='utf8') == ( - '<!-- testing static templates -->\n<html><project>Python</project></html>' + '<!-- testing static templates -->\n<html><project>Project name not set</project></html>' ) result = (app.outdir / 'index.html').read_text(encoding='utf8') diff --git a/tests/test_transforms/test_transforms_post_transforms_code.py b/tests/test_transforms/test_transforms_post_transforms_code.py index 4423d5b4781..96d5a0c751f 100644 --- a/tests/test_transforms/test_transforms_post_transforms_code.py +++ b/tests/test_transforms/test_transforms_post_transforms_code.py @@ -34,7 +34,7 @@ def test_trim_doctest_flags_disabled(app, status, warning): def test_trim_doctest_flags_latex(app, status, warning): app.build() - result = (app.outdir / 'python.tex').read_text(encoding='utf8') + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') assert 'FOO' not in result assert 'BAR' in result assert 'BAZ' not in result diff --git a/utils/release-checklist.rst b/utils/release-checklist.rst index 5aabbcee12b..2a169666e84 100644 --- a/utils/release-checklist.rst +++ b/utils/release-checklist.rst @@ -49,12 +49,12 @@ Bump to next development version for stable and major releases ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* ``python utils/bump_version.py --in-develop X.Y.Z+1b0`` (ex. 1.5.3b0) +* ``python utils/bump_version.py --in-develop X.Y.Z+1b0`` (e.g. 1.5.3b0) for beta releases ~~~~~~~~~~~~~~~~~ -* ``python utils/bump_version.py --in-develop X.Y.0bN+1`` (ex. 1.6.0b2) +* ``python utils/bump_version.py --in-develop X.Y.0bN+1`` (e.g. 1.6.0b2) Commit version bump -------------------