diff options
Diffstat (limited to 'doc')
79 files changed, 5638 insertions, 3461 deletions
diff --git a/doc/_static/conf.py.txt b/doc/_static/conf.py.txt deleted file mode 100644 index c5e75e0..0000000 --- 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. -# "<project> v<release> documentation" by default. -# -# html_title = 'test vtest' - -# A shorter title for the navigation bar. Default is the same as html_title. -# -# html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -# -# html_logo = None - -# The name of an image file (relative to this directory) to use as a favicon of -# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -# -# html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -# -# html_extra_path = [] - -# If not None, a 'Last updated on:' timestamp is inserted at every page -# bottom, using the given strftime format. -# The empty string is equivalent to '%b %d, %Y'. -# -# html_last_updated_fmt = None - -# Custom sidebar templates, maps document names to template names. -# -# html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -# -# html_additional_pages = {} - -# If false, no module index is generated. -# -# html_domain_indices = True - -# If false, no index is generated. -# -# html_use_index = True - -# If true, the index is split into individual pages for each letter. -# -# html_split_index = False - -# If true, links to the reST sources are added to the pages. -# -# html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -# -# html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -# -# html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a <link> tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -# -# html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -# html_file_suffix = None - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh' -# -# html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# 'ja' uses this config value. -# 'zh' user can custom change `jieba` dictionary path. -# -# html_search_options = {'type': 'default'} - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -# -# html_search_scorer = 'scorer.js' - -# Output file base name for HTML help builder. -htmlhelp_basename = 'testdoc' - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (root_doc, 'test.tex', 'test Documentation', - 'test', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -# -# latex_logo = None - -# If true, show page references after internal links. -# -# latex_show_pagerefs = False - -# If true, show URL addresses after external links. -# -# latex_show_urls = False - -# Documents to append as an appendix to all manuals. -# -# latex_appendices = [] - -# If false, no module index is generated. -# -# latex_domain_indices = True - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (root_doc, 'test', 'test Documentation', - [author], 1) -] - -# If true, show URL addresses after external links. -# -# man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (root_doc, 'test', 'test Documentation', - author, 'test', 'One line description of project.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -# -# texinfo_appendices = [] - -# If false, no module index is generated. -# -# texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -# -# texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -# -# texinfo_no_detailmenu = False - -# If false, do not generate in manual @ref nodes. -# -# texinfo_cross_references = False - -# -- A random example ----------------------------------------------------- - -import sys, os -sys.path.insert(0, os.path.abspath('.')) -exclude_patterns = ['zzz'] - -numfig = True -#language = 'ja' - -extensions.append('sphinx.ext.todo') -extensions.append('sphinx.ext.autodoc') -#extensions.append('sphinx.ext.autosummary') -extensions.append('sphinx.ext.intersphinx') -extensions.append('sphinx.ext.mathjax') -extensions.append('sphinx.ext.viewcode') -extensions.append('sphinx.ext.graphviz') - - -autosummary_generate = True -html_theme = 'default' -#source_suffix = ['.rst', '.txt'] diff --git a/doc/_static/diagrams/sphinx_build_flow.dot b/doc/_static/diagrams/sphinx_build_flow.dot new file mode 100644 index 0000000..0e736f5 --- /dev/null +++ b/doc/_static/diagrams/sphinx_build_flow.dot @@ -0,0 +1,47 @@ +// UML for the standard Sphinx build workflow + +digraph build { + graph [ + rankdir=LR + ]; + node [ + shape=rect + style=rounded + ]; + + "Sphinx" [ + shape=record + label = "Sphinx | <init> __init__ | <build> build" + ]; + "Sphinx":init -> "Builder.init"; + "Sphinx":build -> "Builder.build_all"; + "Sphinx":build -> "Builder.build_specific"; + "Builder.build_update" [ + shape=record + label = "<p1> Builder.build_update | Builder.get_outdated_docs" + ]; + "Sphinx":build -> "Builder.build_update":p1 ; + + "Builder.build_all" -> "Builder.build"; + "Builder.build_specific" -> "Builder.build"; + "Builder.build_update":p1 -> "Builder.build"; + + "Builder.build" -> "Builder.read"; + "Builder.write" [ + shape=record + label = "<p1> Builder.write | Builder._write_serial | Builder._write_parallel" + ]; + "Builder.build" -> "Builder.write"; + "Builder.build" -> "Builder.finish"; + + "Builder.read" -> "Builder.read_doc"; + "Builder.read_doc" -> "Builder.write_doctree"; + + "Builder.write":p1 -> "Builder.prepare_writing"; + "Builder.write":p1 -> "Builder.copy_assets"; + "Builder.write":p1 -> "Builder.write_doc"; + + "Builder.write_doc" -> "Builder.get_relative_uri"; + + "Builder.get_relative_uri" -> "Builder.get_target_uri"; +} diff --git a/doc/_static/diagrams/sphinx_core_events_flow.dot b/doc/_static/diagrams/sphinx_core_events_flow.dot new file mode 100644 index 0000000..1499e6b --- /dev/null +++ b/doc/_static/diagrams/sphinx_core_events_flow.dot @@ -0,0 +1,125 @@ +// A flow graph of the Sphinx build process, highlighting event callbacks + +digraph events { + graph [ + rankdir=TB + ]; + node [ + shape=rect + style=rounded + ]; + "Sphinx" [ + shape=record + label = "<init> Sphinx.__init__() | <build> Sphinx.build()" + ]; + + // During initialization + "config-inited"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2]; + "Sphinx":init -> "config-inited"; + "builder-inited"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2]; + "Sphinx":init -> "builder-inited"; + + // During build + "Builder" [label = "Builder.build()"] + "Sphinx":build -> "Builder"; + "Builder.build" [ + shape=record + label = " + <before_read> before read | + <read> read | + <after_read> after read | + <write> write | + <finalize> finalize" + ]; + "Builder" -> "Builder.build"; + + "env-get-outdated"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2]; + "Builder.build":before_read -> "env-get-outdated"; + remove_each_doc [shape="ellipse", label="for removed"]; + "Builder.build":before_read -> "remove_each_doc"; + "env-purge-doc"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2]; + "remove_each_doc" -> "env-purge-doc"; + "env-before-read-docs"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2]; + "Builder.build":before_read -> "env-before-read-docs"; + + // during read phase + "Builder.read" [label = "Builder.read()"] + "Builder.build":read -> "Builder.read"; + read_each_doc [shape="ellipse", label="for added | changed"]; + "Builder.read" -> "read_each_doc"; + merge_each_process [ + shape="ellipse", label="for each process\n(parallel only)" + ]; + "Builder.read" -> merge_each_process; + "env-updated"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2]; + "Builder.read" -> "env-updated" + + // during read phase, for each document/process + "env-purge-doc"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2]; + "read_each_doc" -> "env-purge-doc"; + "source-read"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2]; + "read_each_doc" -> "source-read"; + "Include" [label="Include\ndirective"] + "read_each_doc" -> "Include"; + "include-read"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2]; + "Include" -> "include-read"; + "ObjectDescription" [label="ObjectDescription\ndirective"] + "read_each_doc" -> "ObjectDescription"; + "object-description-transform"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2]; + "ObjectDescription" -> "object-description-transform"; + "doctree-read"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2]; + "read_each_doc" -> "doctree-read"; + "env-merge-info"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2]; + "merge_each_process" -> "env-merge-info"; + + // after read phase + "env-get-updated"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2]; + "Builder.build":after_read -> "env-get-updated"; + if_read_changes [shape="diamond", label="if changed\ndocuments"]; + "Builder.build":after_read -> if_read_changes; + if_read_changes -> "cache the\nBuild.Environment"; + "env-check-consistency"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2]; + if_read_changes -> "env-check-consistency"; + + // during write phase + "write-started"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2]; + "Builder.build":write -> "write-started"; + "Builder.write" [label = "Builder.write()"] + "Builder.build":write -> "Builder.write"; + write_each_doc [shape="ellipse", label="for updated"]; + "Builder.write" -> write_each_doc; + "ReferenceResolver" [ + label="ReferenceResolver\nPost-transform" + ] + write_each_doc -> "ReferenceResolver"; + "missing-reference"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2]; + ReferenceResolver -> "missing-reference"; + "warn-missing-reference"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2]; + ReferenceResolver -> "warn-missing-reference"; + "HyperlinkCollector" [ + label="HyperlinkCollector\nPost-transform" + ] + write_each_doc -> "HyperlinkCollector"; + "linkcheck-process-uri"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2]; + HyperlinkCollector -> "linkcheck-process-uri"; + "doctree-resolved"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2]; + write_each_doc -> "doctree-resolved"; + "html-page-context"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2]; + write_each_doc -> "html-page-context"; + + // html only + "html-collect-pages"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2]; + "Builder.build":finalize -> "html-collect-pages"; + + // finalize build + "build-finished"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2]; + "Builder.build":finalize -> "build-finished"; + + // constrain layout ordering + {rank=same "config-inited" "builder-inited"}; + {rank=same; "env-get-outdated" "env-before-read-docs" "env-get-updated"}; + {rank=same; "env-purge-doc" "source-read" "doctree-read", "merge_each_process"}; + {rank=same; "env-updated" "env-check-consistency"}; + {rank=same; "env-merge-info" "write-started" "Builder.write"}; + {rank=max; "build-finished"}; +} diff --git a/doc/_static/jupyter-logo.png b/doc/_static/jupyter-logo.png Binary files differnew file mode 100644 index 0000000..f50121c --- /dev/null +++ b/doc/_static/jupyter-logo.png diff --git a/doc/_static/linux-logo.png b/doc/_static/linux-logo.png Binary files differnew file mode 100644 index 0000000..b707653 --- /dev/null +++ b/doc/_static/linux-logo.png diff --git a/doc/_static/more.png b/doc/_static/more.png Binary files differdeleted file mode 100644 index 97553a8..0000000 --- a/doc/_static/more.png +++ /dev/null diff --git a/doc/_static/python-logo.png b/doc/_static/python-logo.png Binary files differnew file mode 100644 index 0000000..34e6fec --- /dev/null +++ b/doc/_static/python-logo.png diff --git a/doc/_themes/sphinx13/layout.html b/doc/_themes/sphinx13/layout.html index aae163a..a260da9 100644 --- a/doc/_themes/sphinx13/layout.html +++ b/doc/_themes/sphinx13/layout.html @@ -9,16 +9,24 @@ {% endblock %} {% block header %} +{{ svgs() }} <div class="pageheader"> - <a href="{{ pathto(root_doc)|e }}"> - <img src="{{ pathto('_static/sphinx-logo.svg', resource=True) }}" alt="logo" /> - </a> - <h1>Sphinx</h1> + <div class="brand"> + <a href="{{ pathto(root_doc)|e }}"> + <img src="{{ pathto('_static/sphinx-logo.svg', resource=True) }}" alt="logo" /> + </a> + <h1>Sphinx</h1> + </div> + <div class="icons"> + <a href="https://github.com/sphinx-doc/sphinx" title="{{ _('Source Code') }}" target="_blank"> + <svg><use href="#github"></use></svg> + </a> + </div> </div> {% endblock %} {%- block relbar1 %} -<div class="related" role="navigation" aria-label="related navigation"> +<div class="related" role="navigation" aria-label="Related"> <h3>{{ _('Navigation') }}</h3> <ul> <li><a href="{{ pathto(root_doc)|e }}">Documentation</a> »</li> @@ -32,20 +40,22 @@ {%- block content %} <div class="document"> - <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebar" role="navigation" aria-label="Main"> {%- include "searchfield.html" %} - <div class="sphinxsidebar-navigation__contents"> - <h3>{{ _('On this page') }}</h3> - {{ toc }} - </div> + {%- if display_toc %} + <div class="sphinxsidebar-navigation__contents"> + <h3>{{ _('On this page') }}</h3> + {{ toc }} + </div> + {%- endif %} <div class="sphinxsidebar-navigation__pages"> - <h3>{{ _('Site navigation') }}</h3> {{ toctree(includehidden=True, maxdepth=3, titles_only=True) }} </div> </div> {%- block document %} <div class="body" role="main"> {% block body %}{% endblock %} + {{ prev_next() }} </div> {%- endblock %} </div> @@ -59,3 +69,60 @@ {% trans sphinx_version=sphinx_version|e %}Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %} </div> {%- endblock %} + +{% macro prev_next() %} + <div class="related-pages" role="navigation" aria-label="Related"> + {% if prev -%} + <a class="prev-page" href="{{ prev.link }}"> + <svg><use href="#svg-arrow-right"></use></svg> + <div class="page-info"> + <div class="context"> + <span>{{ _("Previous") }}</span> + </div> + {% if prev.link == pathto(root_doc) %} + <div class="title">{{ _("Home") }}</div> + {% else %} + <div class="title">{{ prev.title }}</div> + {% endif %} + </div> + </a> + {%- else %} + <div></div> + {%- endif %} + {% if next -%} + <a class="next-page" href="{{ next.link }}"> + <div class="page-info"> + <div class="context"> + <span>{{ _("Next") }}</span> + </div> + <div class="title">{{ next.title }}</div> + </div> + <svg><use href="#svg-arrow-right"></use></svg> + </a> + {%- endif %} + </div> +{% endmacro %} + +{% macro svgs() %} +<svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> + <symbol id="github" viewBox="0 0 16 16"> + <title>GitHub</title> + <svg + stroke="currentColor" + fill="currentColor" + stroke-width="0" + viewBox="0 0 16 16" + > + <path + fill-rule="evenodd" + d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z" + ></path> + </svg> + <symbol id="svg-arrow-right" viewBox="0 0 24 24"> + <title>Expand</title> + <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right"> + <polyline points="9 18 15 12 9 6"></polyline> + </svg> + </symbol> +</svg> +{% endmacro %} diff --git a/doc/_themes/sphinx13/static/sphinx13.css b/doc/_themes/sphinx13/static/sphinx13.css index 3234a37..b0d0322 100644 --- a/doc/_themes/sphinx13/static/sphinx13.css +++ b/doc/_themes/sphinx13/static/sphinx13.css @@ -6,38 +6,89 @@ --colour-sphinx-blue: #0A507A; --colour-text: #333; --colour-links-light: #057; + --admonition-radius: 3px; + + /* colours for admonition titles */ + --color-admonition-bg: hsl(0, 0%, 90%); + --color-admonition-fg: hsl(0, 0%, 50%); + --colour-warning-bg: hsl(28.5, 74%, 90%); + --colour-warning-fg: hsl(28.5, 74%, 50%); + --colour-note-bg: hsl(219.5, 84%, 90%); + --colour-note-fg: hsl(219.5, 84%, 50%); + --colour-success-bg: hsl(150, 36.7%, 90%); + --colour-success-fg: hsl(150, 36.7%, 50%); + --colour-error-bg: hsl(0, 37%, 90%); + --colour-error-fg: hsl(0, 37%, 50%); + --colour-todo-bg: hsl(266.8, 100%, 90%); + --colour-todo-fg: hsl(266.8, 100%, 50%); + + /* icons used for admonition titles */ + --icon-pencil: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20.71 7.04c.39-.39.39-1.04 0-1.41l-2.34-2.34c-.37-.39-1.02-.39-1.41 0l-1.84 1.83 3.75 3.75M3 17.25V21h3.75L17.81 9.93l-3.75-3.75L3 17.25z"/></svg>'); + --icon-abstract: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 5h16v2H4V5m0 4h16v2H4V9m0 4h16v2H4v-2m0 4h10v2H4v-2z"/></svg>'); + --icon-info: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 9h-2V7h2m0 10h-2v-6h2m-1-9A10 10 0 002 12a10 10 0 0010 10 10 10 0 0010-10A10 10 0 0012 2z"/></svg>'); + --icon-flame: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M17.55 11.2c-.23-.3-.5-.56-.76-.82-.65-.6-1.4-1.03-2.03-1.66C13.3 7.26 13 4.85 13.91 3c-.91.23-1.75.75-2.45 1.32-2.54 2.08-3.54 5.75-2.34 8.9.04.1.08.2.08.33 0 .22-.15.42-.35.5-.22.1-.46.04-.64-.12a.83.83 0 01-.15-.17c-1.1-1.43-1.28-3.48-.53-5.12C5.89 10 5 12.3 5.14 14.47c.04.5.1 1 .27 1.5.14.6.4 1.2.72 1.73 1.04 1.73 2.87 2.97 4.84 3.22 2.1.27 4.35-.12 5.96-1.6 1.8-1.66 2.45-4.32 1.5-6.6l-.13-.26c-.2-.46-.47-.87-.8-1.25l.05-.01m-3.1 6.3c-.28.24-.73.5-1.08.6-1.1.4-2.2-.16-2.87-.82 1.19-.28 1.89-1.16 2.09-2.05.17-.8-.14-1.46-.27-2.23-.12-.74-.1-1.37.18-2.06.17.38.37.76.6 1.06.76 1 1.95 1.44 2.2 2.8.04.14.06.28.06.43.03.82-.32 1.72-.92 2.27h.01z"/></svg>'); + --icon-question: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M15.07 11.25l-.9.92C13.45 12.89 13 13.5 13 15h-2v-.5c0-1.11.45-2.11 1.17-2.83l1.24-1.26c.37-.36.59-.86.59-1.41a2 2 0 00-2-2 2 2 0 00-2 2H8a4 4 0 014-4 4 4 0 014 4 3.2 3.2 0 01-.93 2.25M13 19h-2v-2h2M12 2A10 10 0 002 12a10 10 0 0010 10 10 10 0 0010-10c0-5.53-4.5-10-10-10z"/></svg>'); + --icon-warning: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 14h-2v-4h2m0 8h-2v-2h2M1 21h22L12 2 1 21z"/></svg>'); + --icon-failure: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 2c5.53 0 10 4.47 10 10s-4.47 10-10 10S2 17.53 2 12 6.47 2 12 2m3.59 5L12 10.59 8.41 7 7 8.41 10.59 12 7 15.59 8.41 17 12 13.41 15.59 17 17 15.59 13.41 12 17 8.41 15.59 7z"/></svg>'); + --icon-spark: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M11.5 20l4.86-9.73H13V4l-5 9.73h3.5V20M12 2c2.75 0 5.1 1 7.05 2.95C21 6.9 22 9.25 22 12s-1 5.1-2.95 7.05C17.1 21 14.75 22 12 22s-5.1-1-7.05-2.95C3 17.1 2 14.75 2 12s1-5.1 2.95-7.05C6.9 3 9.25 2 12 2z"/></svg>'); } body { font-family: var(--fonts-sans-serif); margin: 0 auto; - color: var(--colour-text); + color: var(var(--colour-text)); } .pageheader { + position: sticky; + top: 0; + z-index: 99; + height: 3rem; display: flex; column-gap: 1em; align-items: center; + justify-content: space-between; width: 100%; background-color: var(--colour-sphinx-blue); padding: 10px 20px; + box-sizing: border-box; +} + +.pageheader .brand { + display: flex; + align-items: baseline; + column-gap: 1em; + color: white; + text-decoration: none; } -.pageheader a { - width: 5%; +.pageheader .brand a { + width: 2em; } -.pageheader img { +.pageheader .brand img { filter: invert(1) drop-shadow(1px 1px 2px black); } -.pageheader h1{ +.pageheader .brand h1 { color: white; margin: 0; - font-weight: 600; - font-size: 3.5rem; + font-weight: 400; + font-size: 2em; line-height: 1; - font-variant: small-caps; +} + +.pageheader .icons a { + color: white; +} + +.pageheader .icons a:hover { + color: rgba(255, 255, 255, 0.8); +} + +.pageheader .icons svg { + height: 1.6em; + width: 1.6em; } div.document { @@ -54,6 +105,9 @@ div.body { } div.related { + position: sticky; + top: 3rem; + z-index: 99; display: flex; color: white; background-color: var(--colour-sphinx-blue); @@ -81,20 +135,31 @@ div.sphinxsidebarwrapper { div.sphinxsidebar { position: sticky; - top: 0; + top: 4.6rem; align-self: flex-start; - height: 100vh; + height: calc(100vh - 4.6rem); width: 250px; + min-width: 150px; overflow-y: auto; overflow-wrap: break-word; margin: 0; - padding-right: 15px; - padding-top: 0.5em; + padding: 0.5em 15px 0.5em 10px; font-size: 1em; } +/* horizontal line between sidebar components */ +div.sphinxsidebar div:not(:first-child) { + border-top: 1px solid var(--colour-sphinx-blue); +} + +/* overwrite color from basic theme */ +div.sphinxsidebar input { + border: 1px solid var(--colour-sphinx-blue); +} + div.sphinxsidebar h3 { - font-size: 1.5em; + font-size: 1.2em; + font-weight: 300; margin-top: 0; margin-bottom: 0.5em; padding-top: 0.5em; @@ -169,8 +234,14 @@ div.footer a { /* -- body styles ----------------------------------------------------------- */ +.body :target { + /* ensure targets are not obscured by top-bar when they are navigated to */ + scroll-margin-top: 6.5rem; +} + p { margin: 0.8em 0 0.5em 0; + line-height: 1.5; } a { @@ -186,7 +257,7 @@ h1 { margin: 10px 0 0 0; font-size: 2.4em; color: var(--colour-sphinx-blue); - font-weight: 300; + font-weight: 400; } h1 span.pre { @@ -198,7 +269,7 @@ h1 span.pre { h2 { margin: 1em 0 0.2em 0; font-size: 1.5em; - font-weight: 300; + font-weight: 400; padding: 0; color: #174967; } @@ -206,7 +277,7 @@ h2 { h3 { margin: 1em 0 -0.3em 0; font-size: 1.3em; - font-weight: 300; + font-weight: 400; } div.body h1 a, div.body h2 a, div.body h3 a, div.body h4 a, div.body h5 a, div.body h6 a { @@ -311,6 +382,10 @@ aside.topic { background-color: #f8f8f8; } +p.topic-title { + margin-top: 0; +} + table { border-collapse: collapse; margin: 0 -0.5em 0 -0.5em; @@ -324,7 +399,7 @@ div.admonition, div.warning { font-size: 0.9em; margin: 1em 0 1em 0; border: 1px solid #86989B; - border-radius: 2px; + border-radius: var(--admonition-radius); background-color: #f7f7f7; padding: 1rem; } @@ -338,13 +413,120 @@ div.admonition > pre, div.warning > pre { margin: 0.4em 1em 0.4em 1em; } -div.admonition > p.admonition-title, +div.admonition > p.admonition-title { + position: relative; + font-weight: 500; + background-color: var(--color-admonition-bg); + margin: -1rem -1rem 0.8rem -1rem; + padding: 0.3rem 1rem 0.3rem 2rem; + border-radius: var(--admonition-radius) var(--admonition-radius) 0 0; +} + +div.attention > p.admonition-title, +div.danger > p.admonition-title, +div.error > p.admonition-title { + background-color: var(--colour-error-bg); +} + +div.important > p.admonition-title, +div.caution > p.admonition-title, div.warning > p.admonition-title { - font-weight: bold; + background-color: var(--colour-warning-bg); } +div.note > p.admonition-title { + background-color: var(--colour-note-bg); +} + +div.hint > p.admonition-title, +div.tip > p.admonition-title, +div.seealso > p.admonition-title { + background-color: var(--colour-success-bg); +} + +div.admonition-todo > p.admonition-title { + background-color: var(--colour-todo-bg); +} + +p.admonition-title::before { + content: ""; + height: 1rem; + left: .5rem; + top: .5rem; + position: absolute; + width: 1rem; + background-color: #5f5f5f; +} + +div.admonition > p.admonition-title::before { + background-color: var(--color-admonition-fg); + -webkit-mask-image: var(--icon-abstract); + mask-image: var(--icon-abstract); +} +div.attention > p.admonition-title::before { + background-color: var(--colour-error-fg); + -webkit-mask-image: var(--icon-warning); + mask-image: var(--icon-warning); +} +div.caution > p.admonition-title::before { + background-color: var(--colour-warning-fg); + -webkit-mask-image: var(--icon-spark); + mask-image: var(--icon-spark); +} +div.danger > p.admonition-title::before { + background-color: var(--colour-error-fg); + -webkit-mask-image: var(--icon-spark); + mask-image: var(--icon-spark); +} +div.error > p.admonition-title::before { + background-color: var(--colour-error-fg); + -webkit-mask-image: var(--icon-failure); + mask-image: var(--icon-failure); +} +div.hint > p.admonition-title::before { + background-color: var(--colour-success-fg); + -webkit-mask-image: var(--icon-question); + mask-image: var(--icon-question); +} +div.important > p.admonition-title::before { + background-color: var(--colour-warning-fg); + -webkit-mask-image: var(--icon-flame); + mask-image: var(--icon-flame); +} +div.note > p.admonition-title::before { + background-color: var(--colour-note-fg); + -webkit-mask-image: var(--icon-pencil); + mask-image: var(--icon-pencil); +} +div.seealso > p.admonition-title::before { + background-color: var(--colour-success-fg); + -webkit-mask-image: var(--icon-info); + mask-image: var(--icon-info); +} +div.tip > p.admonition-title::before { + background-color: var(--colour-success-fg); + -webkit-mask-image: var(--icon-info); + mask-image: var(--icon-info); +} +div.admonition-todo > p.admonition-title::before { + background-color: var(--colour-todo-fg); + -webkit-mask-image: var(--icon-pencil); + mask-image: var(--icon-pencil); +} +div.warning > p.admonition-title::before { + background-color: var(--colour-warning-fg); + -webkit-mask-image: var(--icon-warning); + mask-image: var(--icon-warning); +} +div.caution, +div.important, div.warning { - border: 1px solid #940000; + border-color: var(--colour-warning-fg); +} +div.attention, +div.danger, +div.error { + border-color: var(--colour-error-fg); } div.admonition > ul, @@ -373,11 +555,132 @@ div.viewcode-block:target { /* media queries */ /* Reduce padding & margins for smaller screens */ -@media (max-width: 750px) { +@media (max-width: 768px) { .sphinxsidebar { display: none; } div.body { border-left: none; + padding-left: 0.5em; + padding-right: 0.5em; } } + +/* Next/previous content footer */ +.related-pages { + display: flex; + flex-direction: row; + justify-content: space-between; + margin-top: 2rem; + font-size: smaller; +} +.related-pages .next-page { + text-align: right; +} +.related-pages a.prev-page, +.related-pages a.next-page { + flex: 1 1 0%; + display: flex; + align-items: center; + border-radius: .25rem; + padding: .25rem; + text-decoration: none; +} +.related-pages a.prev-page { + justify-content: flex-start; + padding-left: 0; +} +.related-pages a.next-page { + justify-content: flex-end; + padding-right: 0; +} +.related-pages a:hover { + background-color: #f8f8f8; +} +.related-pages a .context { + font-size: small; + color: #5f5f5f; +} +.related-pages svg { + height: .75rem; + width: .75rem; + margin: 0 .5rem; + flex-shrink: 0; +} +.related-pages .prev-page svg { + transform: rotate(180deg); +} + +/* ReadtheDocs docs selector */ +/* see https://docs.readthedocs.io/en/stable/flyout-menu.html */ +.rst-versions.rst-badge { + background-color: #f7f7f7; + border: 1px solid var(--colour-sphinx-blue); + border-radius: var(--admonition-radius); + color: var(--colour-sphinx-blue); +} +.rst-versions .rst-current-version { + background-color: #f7f7f7; + border-radius: var(--admonition-radius); + color: var(--colour-sphinx-blue); +} +.rst-versions .rst-current-version .fa { + color: var(--colour-sphinx-blue); +} +.rst-versions .rst-other-versions { + border-radius: 0 0 var(--admonition-radius) var(--admonition-radius); + border-top: 1px solid var(--colour-sphinx-blue); + background-color: #f7f7f7; + color: var(--colour-text); +} +.rst-versions .rst-other-versions dd a { + color: var(--colour-sphinx-blue); +} + + +/* Landing page */ +.sphinx-tagline * { + hyphens: none !important; + font-style: italic !important; +} +/* By default align the sphinx-features one per-row and center them, +then for larger screens align them two per-row. */ +.sphinx-features { + display: flex; + flex-wrap: wrap; + gap: 10px; + justify-content: center; +} +.sphinx-feature { + flex: 1 1 100%; + margin: 0 !important; + background-color: white !important; +} +.sphinx-feature p { + hyphens: none !important; +} +div.sphinx-feature > p.admonition-title { + background-color: #f7f7f7 !important; + padding-left: 1rem; + font-weight: bold; +} +div.sphinx-feature > p.admonition-title::before { + display: none; +} +@media (min-width: 768px) { + .sphinx-feature { + flex: 0 0 auto; + box-sizing: border-box; + width: 48%; + } +} +.sphinx-users { + text-align: center; + font-weight: 500; +} +.sphinx-users-logos { + display: flex; + flex-wrap: wrap; + justify-content: center; + gap: 10px; +} diff --git a/doc/conf.py b/doc/conf.py index 49fcba4..9582f79 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -1,10 +1,11 @@ # Sphinx documentation build configuration file +from __future__ import annotations import os import re import time -import sphinx +from sphinx import __display_version__ os.environ['SPHINX_AUTODOC_RELOAD_MODULES'] = '1' @@ -18,6 +19,7 @@ extensions = [ 'sphinx.ext.viewcode', 'sphinx.ext.inheritance_diagram', 'sphinx.ext.coverage', + 'sphinx.ext.graphviz', ] coverage_statistics_to_report = coverage_statistics_to_stdout = True templates_path = ['_templates'] @@ -25,8 +27,7 @@ exclude_patterns = ['_build'] 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 @@ -114,15 +115,15 @@ linkcheck_anchors_ignore_for_url = [ autodoc_member_order = 'groupwise' autosummary_generate = False -todo_include_todos = True +todo_include_todos = 'READTHEDOCS' not in os.environ extlinks = { - 'dupage': ('https://docutils.sourceforge.io/docs/ref/rst/' '%s.html', '%s'), + 'dupage': ('https://docutils.sourceforge.io/docs/ref/rst/%s.html', '%s'), 'duref': ( - 'https://docutils.sourceforge.io/docs/ref/rst/' 'restructuredtext.html#%s', + 'https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#%s', '%s', ), - 'durole': ('https://docutils.sourceforge.io/docs/ref/rst/' 'roles.html#%s', '%s'), - 'dudir': ('https://docutils.sourceforge.io/docs/ref/rst/' 'directives.html#%s', '%s'), + 'durole': ('https://docutils.sourceforge.io/docs/ref/rst/roles.html#%s', '%s'), + 'dudir': ('https://docutils.sourceforge.io/docs/ref/rst/directives.html#%s', '%s'), } man_pages = [ @@ -137,7 +138,7 @@ man_pages = [ ( 'man/sphinx-quickstart', 'sphinx-quickstart', - 'Sphinx documentation ' 'template generator', + 'Sphinx documentation template generator', '', 1, ), @@ -154,7 +155,7 @@ texinfo_documents = [ 'Sphinx', 'The Sphinx documentation builder.', 'Documentation tools', - 1, + True, ), ] @@ -179,11 +180,16 @@ nitpick_ignore = { ('js:func', 'string'), ('py:attr', 'srcline'), ('py:class', 'Element'), # sphinx.domains.Domain + ('py:class', 'Documenter'), # sphinx.application.Sphinx.add_autodocumenter ('py:class', 'IndexEntry'), # sphinx.domains.IndexEntry ('py:class', 'Node'), # sphinx.domains.Domain ('py:class', 'NullTranslations'), # gettext.NullTranslations ('py:class', 'RoleFunction'), # sphinx.domains.Domain + ('py:class', 'RSTState'), # sphinx.utils.parsing.nested_parse_to_nodes ('py:class', 'Theme'), # sphinx.application.TemplateBridge + ('py:class', 'SearchLanguage'), # sphinx.application.Sphinx.add_search_language + ('py:class', 'StringList'), # sphinx.utils.parsing.nested_parse_to_nodes + ('py:class', 'system_message'), # sphinx.utils.docutils.SphinxDirective ('py:class', 'TitleGetter'), # sphinx.domains.Domain ('py:class', 'XRefRole'), # sphinx.domains.Domain ('py:class', 'docutils.nodes.Element'), @@ -234,13 +240,14 @@ nitpick_ignore = { # -- Extension interface ------------------------------------------------------- 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() @@ -253,40 +260,72 @@ def parse_event(env, sig, signode): return name -def linkify_issues_in_changelog(app, docname, source): +def linkify_issues_in_changelog(app, path, docname, source): """Linkify issue references like #123 in changelog to GitHub.""" if docname == 'changes': - changelog_path = os.path.join(os.path.dirname(__file__), '../CHANGES.rst') - # this path trickery is needed because this script can - # be invoked with different working directories: - # * running make in docs/ - # * running tox -e docs in the repo root dir - - with open(changelog_path, encoding='utf-8') as f: - changelog = f.read() def linkify(match): url = 'https://github.com/sphinx-doc/sphinx/issues/' + match[1] return f'`{match[0]} <{url}>`_' - linkified_changelog = re.sub(r'(?:PR)?#([0-9]+)\b', linkify, changelog) + linkified_changelog = re.sub(r'(?:PR)?#([0-9]+)\b', linkify, source[0]) + + source[0] = linkified_changelog + - source[0] = source[0].replace('.. include:: ../CHANGES.rst', linkified_changelog) +REDIRECT_TEMPLATE = """ +<html> + <head> + <noscript> + <meta http-equiv="refresh" content="0; url={{rel_url}}"/> + </noscript> + </head> + <body> + <script> + window.location.href = '{{rel_url}}' + (window.location.search || '') + (window.location.hash || ''); + </script> + <p>You should have been redirected.</p> + <a href="{{rel_url}}">If not, click here to continue.</a> + </body> +</html> +""" # noqa: E501 -def setup(app): +def build_redirects(app: Sphinx, exception: Exception | None) -> None: + # this is a very simple implementation of + # https://github.com/wpilibsuite/sphinxext-rediraffe/blob/main/sphinxext/rediraffe.py + # to re-direct some old pages to new ones + if exception is not None or app.builder.name != 'html': + return + for page, rel_redirect in ( + (('development', 'overview.html'), 'index.html'), + (('development', 'builders.html'), 'howtos/builders.html'), + (('development', 'theming.html'), 'html_themes/index.html'), + (('development', 'templating.html'), 'html_themes/templating.html'), + (('development', 'tutorials', 'helloworld.html'), 'extending_syntax.html'), + (('development', 'tutorials', 'todo.html'), 'extending_build.html'), + (('development', 'tutorials', 'recipe.html'), 'adding_domain.html'), + ): + path = app.outdir.joinpath(*page) + if path.exists(): + continue + path.parent.mkdir(parents=True, exist_ok=True) + with path.open('w', encoding='utf-8') as f: + f.write(REDIRECT_TEMPLATE.replace('{{rel_url}}', rel_redirect)) + + +def setup(app: Sphinx) -> None: from sphinx.ext.autodoc import cut_lines from sphinx.util.docfields import GroupedField app.connect('autodoc-process-docstring', cut_lines(4, what=['module'])) - app.connect('source-read', linkify_issues_in_changelog) - app.add_object_type( - 'confval', - 'confval', - objname='configuration value', - indextemplate='pair: %s; configuration value', - ) + app.connect('include-read', linkify_issues_in_changelog) + 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/development/builders.rst b/doc/development/howtos/builders.rst index 7792fbd..7792fbd 100644 --- a/doc/development/builders.rst +++ b/doc/development/howtos/builders.rst diff --git a/doc/development/howtos/index.rst b/doc/development/howtos/index.rst new file mode 100644 index 0000000..9800655 --- /dev/null +++ b/doc/development/howtos/index.rst @@ -0,0 +1,8 @@ +How-tos +======= + +.. toctree:: + :maxdepth: 1 + + setup_extension + builders diff --git a/doc/development/overview.rst b/doc/development/howtos/setup_extension.rst index df8f5bb..bcb4daf 100644 --- a/doc/development/overview.rst +++ b/doc/development/howtos/setup_extension.rst @@ -1,10 +1,5 @@ -Developing extensions overview -============================== - -This page contains general information about developing Sphinx extensions. - -Make an extension depend on another extension ---------------------------------------------- +Depend on another extension +=========================== Sometimes your extension depends on the functionality of another Sphinx extension. Most Sphinx extensions are activated in a @@ -19,12 +14,12 @@ use the :meth:`sphinx.application.Sphinx.setup_extension` method. This will activate another extension at run-time, ensuring that you have access to its functionality. -For example, the following code activates the ``recommonmark`` extension: +For example, the following code activates the :mod:`sphinx.ext.autodoc` extension: .. code-block:: python def setup(app): - app.setup_extension("recommonmark") + app.setup_extension('sphinx.ext.autodoc') .. note:: diff --git a/doc/development/theming.rst b/doc/development/html_themes/index.rst index 13a5802..8724398 100644 --- a/doc/development/theming.rst +++ b/doc/development/html_themes/index.rst @@ -1,3 +1,5 @@ +.. _extension-html-theme: + HTML theme development ====================== @@ -112,7 +114,7 @@ Theme configuration (``theme.conf``) The :file:`theme.conf` file is in INI format [1]_ (readable by the standard Python :mod:`configparser` module) and has the following structure: -.. sourcecode:: ini +.. code-block:: ini [theme] inherit = base theme @@ -222,6 +224,11 @@ If your theme package contains two or more themes, please call Templating ---------- +.. toctree:: + :hidden: + + templating + The :doc:`guide to templating <templating>` is helpful if you want to write your own templates. What is important to keep in mind is the order in which Sphinx searches for templates: @@ -247,12 +254,28 @@ template static files as well as HTML files. Therefore, Sphinx supports so-called "static templates", like this: If the name of a file in the ``static/`` directory of a theme (or in the user's -static path, for that matter) ends with ``_t``, it will be processed by the -template engine. The ``_t`` will be left from the final file name. For -example, the *classic* theme has a file ``static/classic.css_t`` which uses -templating to put the color options into the stylesheet. When a documentation -project is built with the classic theme, the output directory will contain a -``_static/classic.css`` file where all template tags have been processed. +static path) ends with ``.jinja`` or ``_t``, it will be processed by the +template engine. The suffix will be removed from the final file name. + +For example, a theme with a ``static/theme_styles.css.jinja`` file could use +templating to put options into the stylesheet. +When a documentation project is built with that theme, +the output directory will contain a ``_static/theme_styles.css`` file +where all template tags have been processed. + +.. versionchanged:: 7.4 + + The preferred suffix for static templates is now ``.jinja``, in line with + the Jinja project's `recommended file extension`_. + + The ``_t`` file suffix for static templates is now considered 'legacy', and + support may eventually be removed. + + If a static template with either a ``_t`` suffix or a ``.jinja`` suffix is + detected, it will be processed by the template engine, with the suffix + removed from the final file name. + + .. _recommended file extension: https://jinja.palletsprojects.com/en/latest/templates/#template-file-extension Use custom page metadata in HTML templates diff --git a/doc/development/templating.rst b/doc/development/html_themes/templating.rst index 016b8b8..e2de045 100644 --- a/doc/development/templating.rst +++ b/doc/development/html_themes/templating.rst @@ -289,8 +289,8 @@ in the future. .. data:: has_source - True if the reST document sources are copied (if :confval:`html_copy_source` - is ``True``). + True if the reStructuredText document sources are copied + (if :confval:`html_copy_source` is ``True``). .. data:: language @@ -326,8 +326,8 @@ in the future. .. data:: pagename The "page name" of the current file, i.e. either the document name if the - file is generated from a reST source, or the equivalent hierarchical name - relative to the output directory + file is generated from a reStructuredText source, + or the equivalent hierarchical name relative to the output directory (``[directory/]filename_without_extension``). .. data:: project diff --git a/doc/development/index.rst b/doc/development/index.rst index 55a31a0..b059569 100644 --- a/doc/development/index.rst +++ b/doc/development/index.rst @@ -1,24 +1,19 @@ -========================= -Writing Sphinx Extensions -========================= +.. _extending-sphinx: + +Extending Sphinx +================ This guide is aimed at giving a quick introduction for those wishing to -develop their own extensions for Sphinx. Sphinx possesses significant -extensibility capabilities including the ability to hook into almost every -point of the build process. If you simply wish to use Sphinx with existing -extensions, refer to :doc:`/usage/index`. For a more detailed discussion of -the extension interface see :doc:`/extdev/index`. +develop their own extensions for Sphinx. +Sphinx possesses significant extensibility capabilities +including the ability to hook into almost every point of the build process. +If you simply wish to use Sphinx with existing extensions, +refer to :doc:`/usage/index`. +For a more detailed discussion of the extension interface see :doc:`/extdev/index`. .. toctree:: :maxdepth: 2 - overview tutorials/index - builders - -.. toctree:: - :caption: Theming - :maxdepth: 2 - - templating - theming + howtos/index + html_themes/index diff --git a/doc/development/tutorials/recipe.rst b/doc/development/tutorials/adding_domain.rst index 683cc8c..8a00211 100644 --- a/doc/development/tutorials/recipe.rst +++ b/doc/development/tutorials/adding_domain.rst @@ -1,5 +1,7 @@ -Developing a "recipe" extension -=============================== +.. _tutorial-adding-domain: + +Adding a reference domain +========================= The objective of this tutorial is to illustrate roles, directives and domains. Once complete, we will be able to use this extension to describe a recipe and @@ -41,7 +43,9 @@ For that, we will need to add the following elements to Sphinx: Prerequisites ------------- -We need the same setup as in :doc:`the previous extensions <todo>`. This time, +We need the same setup as in +:ref:`the previous extensions <tutorial-extend-build>`. +This time, we will be putting out extension in a file called :file:`recipe.py`. Here is an example of the folder structure you might obtain: @@ -77,7 +81,8 @@ The first thing to examine is the ``RecipeDirective`` directive: :linenos: :pyobject: RecipeDirective -Unlike :doc:`helloworld` and :doc:`todo`, this directive doesn't derive from +Unlike :ref:`tutorial-extending-syntax` and :ref:`tutorial-extend-build`, +this directive doesn't derive from :class:`docutils.parsers.rst.Directive` and doesn't define a ``run`` method. Instead, it derives from :class:`sphinx.directives.ObjectDescription` and defines ``handle_signature`` and ``add_target_and_index`` methods. This is @@ -90,9 +95,10 @@ for this node. We also see that this directive defines ``has_content``, ``required_arguments`` and ``option_spec``. Unlike the ``TodoDirective`` directive added in the -:doc:`previous tutorial <todo>`, this directive takes a single argument, the -recipe name, and an option, ``contains``, in addition to the nested -reStructuredText in the body. +:ref:`previous tutorial <tutorial-extend-build>`, +this directive takes a single argument, +the recipe name, and an option, ``contains``, +in addition to the nested reStructuredText in the body. .. rubric:: The index classes @@ -167,7 +173,8 @@ indices and our cross-referencing code use this feature. .. currentmodule:: sphinx.application -:doc:`As always <todo>`, the ``setup`` function is a requirement and is used to +:ref:`As always <tutorial-extend-build>`, +the ``setup`` function is a requirement and is used to hook the various parts of our extension into Sphinx. Let's look at the ``setup`` function for this extension. @@ -224,4 +231,7 @@ Further reading For more information, refer to the `docutils`_ documentation and :doc:`/extdev/index`. +If you wish to share your extension across multiple projects or with others, +check out the :ref:`third-party-extensions` section. + .. _docutils: https://docutils.sourceforge.io/docs/ diff --git a/doc/development/tutorials/autodoc_ext.rst b/doc/development/tutorials/autodoc_ext.rst index cfd23e7..fb2a917 100644 --- a/doc/development/tutorials/autodoc_ext.rst +++ b/doc/development/tutorials/autodoc_ext.rst @@ -1,7 +1,7 @@ .. _autodoc_ext_tutorial: -Developing autodoc extension for IntEnum -======================================== +Developing autodoc extensions +============================= The objective of this tutorial is to create an extension that adds support for new type for autodoc. This autodoc extension will format @@ -27,8 +27,10 @@ We want to add following to autodoc: Prerequisites ------------- -We need the same setup as in :doc:`the previous extensions <todo>`. This time, -we will be putting out extension in a file called :file:`autodoc_intenum.py`. +We need the same setup as in +:ref:`the previous extensions <tutorial-extend-build>`. +This time, we will be putting out extension +in a file called :file:`autodoc_intenum.py`. The :file:`my_enums.py` will contain the sample enums we will document. Here is an example of the folder structure you might obtain: @@ -139,3 +141,9 @@ This will be the documentation file with auto-documentation directive: :caption: index.rst .. autointenum:: my_enums.Colors + +Further reading +--------------- + +If you wish to share your extension across multiple projects or with others, +check out the :ref:`third-party-extensions` section. diff --git a/doc/development/tutorials/examples/autodoc_intenum.py b/doc/development/tutorials/examples/autodoc_intenum.py index c52bb4c..7a19a23 100644 --- a/doc/development/tutorials/examples/autodoc_intenum.py +++ b/doc/development/tutorials/examples/autodoc_intenum.py @@ -9,6 +9,7 @@ if TYPE_CHECKING: from docutils.statemachine import StringList from sphinx.application import Sphinx + from sphinx.util.typing import ExtensionMetadata class IntEnumDocumenter(ClassDocumenter): @@ -52,6 +53,10 @@ class IntEnumDocumenter(ClassDocumenter): self.add_line('', source_name) -def setup(app: Sphinx) -> None: +def setup(app: Sphinx) -> ExtensionMetadata: app.setup_extension('sphinx.ext.autodoc') # Require autodoc extension app.add_autodocumenter(IntEnumDocumenter) + return { + 'version': '1', + 'parallel_read_safe': True, + } diff --git a/doc/development/tutorials/examples/helloworld.py b/doc/development/tutorials/examples/helloworld.py index da29562..3f7e504 100644 --- a/doc/development/tutorials/examples/helloworld.py +++ b/doc/development/tutorials/examples/helloworld.py @@ -1,18 +1,33 @@ +from __future__ import annotations + from docutils import nodes -from docutils.parsers.rst import Directive from sphinx.application import Sphinx +from sphinx.util.docutils import SphinxDirective, SphinxRole from sphinx.util.typing import ExtensionMetadata -class HelloWorld(Directive): - def run(self): - paragraph_node = nodes.paragraph(text='Hello World!') +class HelloRole(SphinxRole): + """A role to say hello!""" + + def run(self) -> tuple[list[nodes.Node], list[nodes.system_message]]: + node = nodes.inline(text=f'Hello {self.text}!') + return [node], [] + + +class HelloDirective(SphinxDirective): + """A directive to say hello!""" + + required_arguments = 1 + + def run(self) -> list[nodes.Node]: + paragraph_node = nodes.paragraph(text=f'hello {self.arguments[0]}!') return [paragraph_node] def setup(app: Sphinx) -> ExtensionMetadata: - app.add_directive('helloworld', HelloWorld) + app.add_role('hello', HelloRole()) + app.add_directive('hello', HelloDirective) return { 'version': '0.1', diff --git a/doc/development/tutorials/examples/recipe.py b/doc/development/tutorials/examples/recipe.py index 28d25f2..baf85fe 100644 --- a/doc/development/tutorials/examples/recipe.py +++ b/doc/development/tutorials/examples/recipe.py @@ -122,6 +122,7 @@ class RecipeDomain(Domain): 'recipes': [], # object list 'recipe_ingredients': {}, # name -> object } + data_version = 0 def get_full_qualified_name(self, node): return f'recipe.{node.arguments[0]}' diff --git a/doc/development/tutorials/examples/todo.py b/doc/development/tutorials/examples/todo.py index 2baac5c..4e9dc66 100644 --- a/doc/development/tutorials/examples/todo.py +++ b/doc/development/tutorials/examples/todo.py @@ -38,7 +38,7 @@ class TodoDirective(SphinxDirective): todo_node = todo('\n'.join(self.content)) todo_node += nodes.title(_('Todo'), _('Todo')) - self.state.nested_parse(self.content, self.content_offset, todo_node) + todo_node += self.parse_content_to_nodes() if not hasattr(self.env, 'todo_all_todos'): self.env.todo_all_todos = [] @@ -132,6 +132,7 @@ def setup(app: Sphinx) -> ExtensionMetadata: return { 'version': '0.1', + 'env_version': 1, 'parallel_read_safe': True, 'parallel_write_safe': True, } diff --git a/doc/development/tutorials/todo.rst b/doc/development/tutorials/extending_build.rst index f23d8ad..a81c84b 100644 --- a/doc/development/tutorials/todo.rst +++ b/doc/development/tutorials/extending_build.rst @@ -1,14 +1,20 @@ -Developing a "TODO" extension -============================= +.. _tutorial-extend-build: -The objective of this tutorial is to create a more comprehensive extension than -that created in :doc:`helloworld`. Whereas that guide just covered writing a -custom :term:`directive`, this guide adds multiple directives, along with custom -nodes, additional config values and custom event handlers. To this end, we will -cover a ``todo`` extension that adds capabilities to include todo entries in the -documentation, and to collect these in a central place. This is similar the -``sphinxext.todo`` extension distributed with Sphinx. +Extending the build process +=========================== +The objective of this tutorial is to create a more comprehensive extension than +that created in :ref:`tutorial-extending-syntax`. +Whereas that guide just covered writing +a custom :term:`role` and :term:`directive`, +this guide covers a more complex extension to the Sphinx build process; +adding multiple directives, +along with custom nodes, additional config values and custom event handlers. + +To this end, we will cover a ``todo`` extension +that adds capabilities to include todo entries in the documentation, +and to collect these in a central place. +This is similar to the :mod:`sphinx.ext.todo` extension distributed with Sphinx. Overview -------- @@ -47,7 +53,8 @@ For that, we will need to add the following elements to Sphinx: Prerequisites ------------- -As with :doc:`helloworld`, we will not be distributing this plugin via PyPI so +As with :ref:`tutorial-extending-syntax`, +we will not be distributing this plugin via PyPI so once again we need a Sphinx project to call this from. You can use an existing project or create a new one using :program:`sphinx-quickstart`. @@ -83,7 +90,8 @@ explain in detail shortly: :language: python :linenos: -This is far more extensive extension than the one detailed in :doc:`helloworld`, +This is far more extensive extension than the one detailed in +:ref:`tutorial-extending-syntax`, however, we will will look at each piece step-by-step to explain what's happening. @@ -250,7 +258,8 @@ ID as the anchor name. .. currentmodule:: sphinx.application -As noted :doc:`previously <helloworld>`, the ``setup`` function is a requirement +As noted :ref:`previously <tutorial-extending-syntax>`, +the ``setup`` function is a requirement and is used to plug directives into Sphinx. However, we also use it to hook up the other parts of our extension. Let's look at our ``setup`` function: @@ -361,6 +370,9 @@ Further reading For more information, refer to the `docutils`_ documentation and :doc:`/extdev/index`. +If you wish to share your extension across multiple projects or with others, +check out the :ref:`third-party-extensions` section. + .. _docutils: https://docutils.sourceforge.io/docs/ .. _Python path: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH diff --git a/doc/development/tutorials/extending_syntax.rst b/doc/development/tutorials/extending_syntax.rst new file mode 100644 index 0000000..bab8037 --- /dev/null +++ b/doc/development/tutorials/extending_syntax.rst @@ -0,0 +1,223 @@ +.. _tutorial-extending-syntax: + +Extending syntax with roles and directives +========================================== + +Overview +-------- + +The syntax of both reStructuredText and MyST can be extended +by creating new **directives** - for block-level elements - +and **roles** - for inline elements. + +In this tutorial we shall extend Sphinx to add: + +* A ``hello`` role, that will simply output the text ``Hello {text}!``. +* A ``hello`` directive, that will simply output the text ``Hello {text}!``, + as a paragraph. + +For this extension, you will need some basic understanding of Python, +and we shall also introduce aspects of the docutils_ API. + +Setting up the project +---------------------- + +You can either use an existing Sphinx project +or create a new one using :program:`sphinx-quickstart`. + +With this we will add the extension to the project, +within the :file:`source` folder: + +#. Create an :file:`_ext` folder in :file:`source` +#. Create a new Python file in the :file:`_ext` folder called + :file:`helloworld.py` + +Here is an example of the folder structure you might obtain: + +.. code-block:: text + + └── source + ├── _ext + │ └── helloworld.py + ├── conf.py + ├── index.rst + + +Writing the extension +--------------------- + +Open :file:`helloworld.py` and paste the following code in it: + +.. literalinclude:: examples/helloworld.py + :language: python + :linenos: + +Some essential things are happening in this example: + +The role class +............... + +Our new role is declared in the ``HelloRole`` class. + +.. literalinclude:: examples/helloworld.py + :language: python + :linenos: + :pyobject: HelloRole + +This class extends the :class:`.SphinxRole` class. +The class contains a ``run`` method, +which is a requirement for every role. +It contains the main logic of the role and it +returns a tuple containing: + +- a list of inline-level docutils nodes to be processed by Sphinx. +- an (optional) list of system message nodes + +The directive class +................... + +Our new directive is declared in the ``HelloDirective`` class. + +.. literalinclude:: examples/helloworld.py + :language: python + :linenos: + :pyobject: HelloDirective + +This class extends the :class:`.SphinxDirective` class. +The class contains a ``run`` method, +which is a requirement for every directive. +It contains the main logic of the directive and it +returns a list of block-level docutils nodes to be processed by Sphinx. +It also contains a ``required_arguments`` attribute, +which tells Sphinx how many arguments are required for the directive. + +What are docutils nodes? +........................ + +When Sphinx parses a document, +it creates an "Abstract Syntax Tree" (AST) of nodes +that represent the content of the document in a structured way, +that is generally independent of any one +input (rST, MyST, etc) or output (HTML, LaTeX, etc) format. +It is a tree because each node can have children nodes, and so on: + +.. code-block:: xml + + <document> + <paragraph> + <text> + Hello world! + +The docutils_ package provides many `built-in nodes <docutils nodes_>`_, +to represent different types of content such as +text, paragraphs, references, tables, etc. + +Each node type generally only accepts a specific set of direct child nodes, +for example the ``document`` node should only contain "block-level" nodes, +such as ``paragraph``, ``section``, ``table``, etc, +whilst the ``paragraph`` node should only contain "inline-level" nodes, +such as ``text``, ``emphasis``, ``strong``, etc. + +.. seealso:: + + The docutils documentation on + `creating directives <docutils directives_>`_, and + `creating roles <docutils roles_>`_. + +The ``setup`` function +...................... + +This function is a requirement. +We use it to plug our new directive into Sphinx. + +.. literalinclude:: examples/helloworld.py + :language: python + :pyobject: setup + +The simplest thing you can do is to call the +:meth:`.Sphinx.add_role` and :meth:`.Sphinx.add_directive` methods, +which is what we've done here. +For this particular call, the first argument is the name of the role/directive itself +as used in a reStructuredText file. +In this case, we would use ``hello``. For example: + +.. code-block:: rst + + Some intro text here... + + .. hello:: world + + Some text with a :hello:`world` role. + +We also return the :ref:`extension metadata <ext-metadata>` that indicates the +version of our extension, along with the fact that it is safe to use the +extension for both parallel reading and writing. + +Using the extension +------------------- + +The extension has to be declared in your :file:`conf.py` file to make Sphinx +aware of it. There are two steps necessary here: + +#. Add the :file:`_ext` directory to the `Python path`_ using + ``sys.path.append``. This should be placed at the top of the file. + +#. Update or create the :confval:`extensions` list and add the extension file + name to the list + +For example: + +.. code-block:: python + + import os + import sys + + sys.path.append(os.path.abspath("./_ext")) + + extensions = ['helloworld'] + +.. tip:: + + Because we haven't installed our extension as a `Python package`_, we need to + modify the `Python path`_ so Sphinx can find our extension. This is why we + need the call to ``sys.path.append``. + +You can now use the extension in a file. For example: + +.. code-block:: rst + + Some intro text here... + + .. hello:: world + + Some text with a :hello:`world` role. + +The sample above would generate: + +.. code-block:: text + + Some intro text here... + + Hello world! + + Some text with a hello world! role. + + +Further reading +--------------- + +This is the very basic principle of an extension +that creates a new role and directive. + +For a more advanced example, refer to :ref:`tutorial-extend-build`. + +If you wish to share your extension across multiple projects or with others, +check out the :ref:`third-party-extensions` section. + +.. _docutils: https://docutils.sourceforge.io/ +.. _docutils roles: https://docutils.sourceforge.io/docs/howto/rst-roles.html +.. _docutils directives: https://docutils.sourceforge.io/docs/howto/rst-directives.html +.. _docutils nodes: https://docutils.sourceforge.io/docs/ref/doctree.html +.. _PyPI: https://pypi.org/ +.. _Python package: https://packaging.python.org/ +.. _Python path: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH diff --git a/doc/development/tutorials/helloworld.rst b/doc/development/tutorials/helloworld.rst deleted file mode 100644 index 8940e3d..0000000 --- a/doc/development/tutorials/helloworld.rst +++ /dev/null @@ -1,189 +0,0 @@ -Developing a "Hello world" extension -==================================== - -The objective of this tutorial is to create a very basic extension that adds a -new directive. This directive will output a paragraph containing "hello world". - -Only basic information is provided in this tutorial. For more information, refer -to the :doc:`other tutorials <index>` that go into more details. - -.. warning:: - - For this extension, you will need some basic understanding of docutils_ - and Python. - - -Overview --------- - -We want the extension to add the following to Sphinx: - -* A ``helloworld`` directive, that will simply output the text "hello world". - - -Prerequisites -------------- - -We will not be distributing this plugin via `PyPI`_ and will instead include it -as part of an existing project. This means you will need to use an existing -project or create a new one using :program:`sphinx-quickstart`. - -We assume you are using separate source (:file:`source`) and build -(:file:`build`) folders. Your extension file could be in any folder of your -project. In our case, let's do the following: - -#. Create an :file:`_ext` folder in :file:`source` -#. Create a new Python file in the :file:`_ext` folder called - :file:`helloworld.py` - -Here is an example of the folder structure you might obtain: - -.. code-block:: text - - └── source - ├── _ext - │ └── helloworld.py - ├── _static - ├── conf.py - ├── somefolder - ├── index.rst - ├── somefile.rst - └── someotherfile.rst - - -Writing the extension ---------------------- - -Open :file:`helloworld.py` and paste the following code in it: - -.. literalinclude:: examples/helloworld.py - :language: python - :linenos: - -Some essential things are happening in this example, and you will see them for -all directives. - -.. rubric:: The directive class - -Our new directive is declared in the ``HelloWorld`` class. - -.. literalinclude:: examples/helloworld.py - :language: python - :linenos: - :lines: 5-9 - -This class extends the docutils_' ``Directive`` class. All extensions that -create directives should extend this class. - -.. seealso:: - - `The docutils documentation on creating directives <docutils directives_>`_ - -This class contains a ``run`` method. This method is a requirement and it is -part of every directive. It contains the main logic of the directive and it -returns a list of docutils nodes to be processed by Sphinx. These nodes are -docutils' way of representing the content of a document. There are many types of -nodes available: text, paragraph, reference, table, etc. - -.. seealso:: - - `The docutils documentation on nodes <docutils nodes_>`_ - -The ``nodes.paragraph`` class creates a new paragraph node. A paragraph -node typically contains some text that we can set during instantiation using -the ``text`` parameter. - -.. rubric:: The ``setup`` function - -.. currentmodule:: sphinx.application - -This function is a requirement. We use it to plug our new directive into -Sphinx. - -.. literalinclude:: examples/helloworld.py - :language: python - :linenos: - :lines: 12- - -The simplest thing you can do is to call the :meth:`~Sphinx.add_directive` method, -which is what we've done here. For this particular call, the first argument is -the name of the directive itself as used in a reST file. In this case, we would -use ``helloworld``. For example: - -.. code-block:: rst - - Some intro text here... - - .. helloworld:: - - Some more text here... - -We also return the :ref:`extension metadata <ext-metadata>` that indicates the -version of our extension, along with the fact that it is safe to use the -extension for both parallel reading and writing. - - -Using the extension -------------------- - -The extension has to be declared in your :file:`conf.py` file to make Sphinx -aware of it. There are two steps necessary here: - -#. Add the :file:`_ext` directory to the `Python path`_ using - ``sys.path.append``. This should be placed at the top of the file. - -#. Update or create the :confval:`extensions` list and add the extension file - name to the list - -For example: - -.. code-block:: python - - import os - import sys - - sys.path.append(os.path.abspath("./_ext")) - - extensions = ['helloworld'] - -.. tip:: - - We're not distributing this extension as a `Python package`_, we need to - modify the `Python path`_ so Sphinx can find our extension. This is why we - need the call to ``sys.path.append``. - -You can now use the extension in a file. For example: - -.. code-block:: rst - - Some intro text here... - - .. helloworld:: - - Some more text here... - -The sample above would generate: - -.. code-block:: text - - Some intro text here... - - Hello World! - - Some more text here... - - -Further reading ---------------- - -This is the very basic principle of an extension that creates a new directive. - -For a more advanced example, refer to :doc:`todo`. - - -.. _docutils: https://docutils.sourceforge.io/ -.. _docutils directives: https://docutils.sourceforge.io/docs/howto/rst-directives.html -.. _docutils nodes: https://docutils.sourceforge.io/docs/ref/doctree.html -.. _PyPI: https://pypi.org/ -.. _Python package: https://packaging.python.org/ -.. _Python path: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH diff --git a/doc/development/tutorials/index.rst b/doc/development/tutorials/index.rst index a7eee48..0c5c920 100644 --- a/doc/development/tutorials/index.rst +++ b/doc/development/tutorials/index.rst @@ -1,17 +1,12 @@ .. _extension-tutorials-index: -Extension tutorials -=================== - -Refer to the following tutorials to get started with extension development. - +Tutorials +========= .. toctree:: - :caption: Directive tutorials - :maxdepth: 1 + :maxdepth: 2 - helloworld - todo - recipe + extending_syntax + extending_build + adding_domain autodoc_ext - diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index 10d030b..682db4e 100644 --- a/doc/extdev/appapi.rst +++ b/doc/extdev/appapi.rst @@ -1,4 +1,4 @@ -.. highlight:: rest +.. highlight:: rst Application API =============== @@ -137,294 +137,12 @@ The application object also provides runtime information as attributes. Directory for storing built document. - -.. _events: +.. autoattribute:: Sphinx.fresh_env_used Sphinx core events ------------------ -These events are known to the core. The arguments shown are given to the -registered event handlers. Use :meth:`.Sphinx.connect` in an extension's -``setup`` function (note that ``conf.py`` can also have a ``setup`` function) to -connect handlers to the events. Example: - -.. code-block:: python - - def source_read_handler(app, docname, source): - print('do something here...') - - def setup(app): - app.connect('source-read', source_read_handler) - - -Below is an overview of each event that happens during a build. In the list -below, we include the event name, its callback parameters, and the input and output -type for that event: - -.. code-block:: none - - 1. event.config-inited(app,config) - 2. event.builder-inited(app) - 3. event.env-get-outdated(app, env, added, changed, removed) - 4. event.env-before-read-docs(app, env, docnames) - - for docname in docnames: - 5. event.env-purge-doc(app, env, docname) - - if doc changed and not removed: - 6. source-read(app, docname, source) - 7. run source parsers: text -> docutils.document - - parsers can be added with the app.add_source_parser() API - 8. apply transforms based on priority: docutils.document -> docutils.document - - event.doctree-read(app, doctree) is called in the middle of transforms, - transforms come before/after this event depending on their priority. - - 9. event.env-merge-info(app, env, docnames, other) - - if running in parallel mode, this event will be emitted for each process - - 10. event.env-updated(app, env) - 11. event.env-get-updated(app, env) - 12. event.env-check-consistency(app, env) - - # The updated-docs list can be builder dependent, but generally includes all new/changed documents, - # plus any output from `env-get-updated`, and then all "parent" documents in the ToC tree - # For builders that output a single page, they are first joined into a single doctree before post-transforms - # or the doctree-resolved event is emitted - for docname in updated-docs: - 13. apply post-transforms (by priority): docutils.document -> docutils.document - 14. event.doctree-resolved(app, doctree, docname) - - In the event that any reference nodes fail to resolve, the following may emit: - - event.missing-reference(env, node, contnode) - - event.warn-missing-reference(domain, node) - - 15. Generate output files - 16. event.build-finished(app, exception) - -Here is a more detailed list of these events. - -.. event:: builder-inited (app) - - Emitted when the builder object has been created. It is available as - ``app.builder``. - -.. event:: config-inited (app, config) - - Emitted when the config object has been initialized. - - .. versionadded:: 1.8 - -.. event:: env-get-outdated (app, env, added, changed, removed) - - Emitted when the environment determines which source files have changed and - should be re-read. *added*, *changed* and *removed* are sets of docnames - that the environment has determined. You can return a list of docnames to - re-read in addition to these. - - .. versionadded:: 1.1 - -.. event:: env-purge-doc (app, env, docname) - - Emitted when all traces of a source file should be cleaned from the - environment, that is, if the source file is removed or before it is freshly - read. This is for extensions that keep their own caches in attributes of the - environment. - - For example, there is a cache of all modules on the environment. When a - source file has been changed, the cache's entries for the file are cleared, - since the module declarations could have been removed from the file. - - .. versionadded:: 0.5 - -.. event:: env-before-read-docs (app, env, docnames) - - Emitted after the environment has determined the list of all added and - changed files and just before it reads them. It allows extension authors to - reorder the list of docnames (*inplace*) before processing, or add more - docnames that Sphinx did not consider changed (but never add any docnames - that are not in ``env.found_docs``). - - You can also remove document names; do this with caution since it will make - Sphinx treat changed files as unchanged. - - .. versionadded:: 1.3 - -.. event:: source-read (app, docname, source) - - Emitted when a source file has been read. The *source* argument is a list - whose single element is the contents of the source file. You can process the - contents and replace this item to implement source-level transformations. - - For example, if you want to use ``$`` signs to delimit inline math, like in - LaTeX, you can use a regular expression to replace ``$...$`` by - ``:math:`...```. - - .. versionadded:: 0.5 - -.. event:: include-read (app, relative_path, parent_docname, content) - - Emitted when a file has been read with the :dudir:`include` directive. - The *relative_path* argument is a :py:class:`~pathlib.Path` object representing - the relative path of the included file from the :term:`source directory`. - The *parent_docname* argument is the name of the document that - contains the :dudir:`include` directive. - The *source* argument is a list whose single element is - the contents of the included file. - You can process the contents and replace this item - to transform the included content, - as with the :event:`source-read` event. - - .. versionadded:: 7.2.5 - - .. seealso:: The :dudir:`include` directive and the :event:`source-read` event. - -.. event:: object-description-transform (app, domain, objtype, contentnode) - - Emitted when an object description directive has run. The *domain* and - *objtype* arguments are strings indicating object description of the object. - And *contentnode* is a content for the object. It can be modified in-place. - - .. versionadded:: 2.4 - -.. event:: doctree-read (app, doctree) - - Emitted when a doctree has been parsed and read by the environment, and is - about to be pickled. The *doctree* can be modified in-place. - -.. event:: missing-reference (app, env, node, contnode) - - Emitted when a cross-reference to an object cannot be resolved. - If the event handler can resolve the reference, it should return a - new docutils node to be inserted in the document tree in place of the node - *node*. Usually this node is a :class:`~nodes.reference` node containing - *contnode* as a child. - If the handler can not resolve the cross-reference, - it can either return ``None`` to let other handlers try, - or raise :class:`~sphinx.errors.NoUri` to prevent other handlers in - trying and suppress a warning about this cross-reference being unresolved. - - :param env: The build environment (``app.builder.env``). - :param node: The :class:`~sphinx.addnodes.pending_xref` node to be resolved. - Its ``reftype``, ``reftarget``, ``modname`` and ``classname`` attributes - determine the type and target of the reference. - :param contnode: The node that carries the text and formatting inside the - future reference and should be a child of the returned reference node. - - .. versionadded:: 0.5 - -.. event:: warn-missing-reference (app, domain, node) - - Emitted when a cross-reference to an object cannot be resolved even after - :event:`missing-reference`. If the event handler can emit warnings for - the missing reference, it should return ``True``. The configuration variables - :confval:`nitpick_ignore` and :confval:`nitpick_ignore_regex` prevent the - event from being emitted for the corresponding nodes. - - .. versionadded:: 3.4 - -.. event:: doctree-resolved (app, doctree, docname) - - Emitted when a doctree has been "resolved" by the environment, that is, all - references have been resolved and TOCs have been inserted. The *doctree* can - be modified in place. - - Here is the place to replace custom nodes that don't have visitor methods in - the writers, so that they don't cause errors when the writers encounter them. - -.. event:: env-merge-info (app, env, docnames, other) - - This event is only emitted when parallel reading of documents is enabled. It - is emitted once for every subprocess that has read some documents. - - You must handle this event in an extension that stores data in the - environment in a custom location. Otherwise the environment in the main - process will not be aware of the information stored in the subprocess. - - *other* is the environment object from the subprocess, *env* is the - environment from the main process. *docnames* is a set of document names - that have been read in the subprocess. - - .. versionadded:: 1.3 - -.. event:: env-updated (app, env) - - Emitted after reading all documents, when the environment and all - doctrees are now up-to-date. - - You can return an iterable of docnames from the handler. These documents - will then be considered updated, and will be (re-)written during the writing - phase. - - .. versionadded:: 0.5 - - .. versionchanged:: 1.3 - The handlers' return value is now used. - -.. event:: env-check-consistency (app, env) - - Emitted when Consistency checks phase. You can check consistency of - metadata for whole of documents. - - .. versionadded:: 1.6 - - As a **experimental** event - -.. event:: html-collect-pages (app) - - Emitted when the HTML builder is starting to write non-document pages. You - can add pages to write by returning an iterable from this event consisting of - ``(pagename, context, templatename)``. - - .. versionadded:: 1.0 - -.. event:: html-page-context (app, pagename, templatename, context, doctree) - - Emitted when the HTML builder has created a context dictionary to render a - template with -- this can be used to add custom elements to the context. - - The *pagename* argument is the canonical name of the page being rendered, - that is, without ``.html`` suffix and using slashes as path separators. The - *templatename* is the name of the template to render, this will be - ``'page.html'`` for all pages from reST documents. - - The *context* argument is a dictionary of values that are given to the - template engine to render the page and can be modified to include custom - values. Keys must be strings. - - The *doctree* argument will be a doctree when the page is created from a reST - documents; it will be ``None`` when the page is created from an HTML template - alone. - - You can return a string from the handler, it will then replace - ``'page.html'`` as the HTML template for this page. - - .. note:: You can install JS/CSS files for the specific page via - :meth:`Sphinx.add_js_file` and :meth:`Sphinx.add_css_file` since - v3.5.0. - - .. versionadded:: 0.4 - - .. versionchanged:: 1.3 - The return value can now specify a template name. - -.. event:: linkcheck-process-uri (app, uri) - - Emitted when the linkcheck builder collects hyperlinks from document. *uri* - is a collected URI. The event handlers can modify the URI by returning a - string. - - .. versionadded:: 4.1 - -.. event:: build-finished (app, exception) - - Emitted when a build has finished, before Sphinx exits, usually used for - cleanup. This event is emitted even when the build process raised an - exception, given as the *exception* argument. The exception is reraised in - the application after the event handlers have run. If the build process - raised no exception, *exception* will be ``None``. This allows to customize - cleanup actions depending on the exception status. - - .. versionadded:: 0.5 - +.. note:: Moved to :ref:`events`. Checking the Sphinx version --------------------------- diff --git a/doc/extdev/builderapi.rst b/doc/extdev/builderapi.rst index 5c5a525..9259aaa 100644 --- a/doc/extdev/builderapi.rst +++ b/doc/extdev/builderapi.rst @@ -3,15 +3,20 @@ Builder API =========== -.. todo:: Expand this. - .. currentmodule:: sphinx.builders .. class:: Builder This is the base class for all builders. - These attributes should be set on builder classes: + It follows this basic workflow: + + .. graphviz:: /_static/diagrams/sphinx_build_flow.dot + :caption: UML for the standard Sphinx build workflow + + .. rubric:: Overridable Attributes + + These attributes should be set on builder sub-classes: .. autoattribute:: name .. autoattribute:: format @@ -22,24 +27,39 @@ Builder API .. autoattribute:: supported_data_uri_images .. autoattribute:: default_translator_class - These methods are predefined and will be called from the application: + .. rubric:: Core Methods + + These methods are predefined and should generally not be overridden, + since they form the core of the build process: - .. automethod:: get_relative_uri .. automethod:: build_all .. automethod:: build_specific .. automethod:: build_update .. automethod:: build + .. automethod:: read + .. automethod:: read_doc + .. automethod:: write_doctree - These methods can be overridden in concrete builder classes: + .. rubric:: Overridable Methods + + These must be implemented in builder sub-classes: - .. automethod:: init .. automethod:: get_outdated_docs - .. automethod:: get_target_uri .. automethod:: prepare_writing .. automethod:: write_doc + .. automethod:: get_target_uri + + These methods can be overridden in builder sub-classes: + + .. automethod:: init + .. automethod:: write + .. automethod:: copy_assets + .. automethod:: get_relative_uri .. automethod:: finish - **Attributes** + .. rubric:: Attributes + + Attributes that are callable from the builder instance: .. attribute:: events diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst index 1476ce8..7504be3 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/extdev/envapi.rst b/doc/extdev/envapi.rst index d7ec239..971e506 100644 --- a/doc/extdev/envapi.rst +++ b/doc/extdev/envapi.rst @@ -45,6 +45,8 @@ Build environment API .. autoattribute:: docname + .. autoattribute:: parser + **Utility methods** .. automethod:: doc2path diff --git a/doc/extdev/event_callbacks.rst b/doc/extdev/event_callbacks.rst new file mode 100644 index 0000000..1edade4 --- /dev/null +++ b/doc/extdev/event_callbacks.rst @@ -0,0 +1,424 @@ +.. _events: + +Event callbacks API +=================== + +Connecting callback functions to events is a simple way to extend Sphinx, +by hooking into the build process at various points. + +Use :meth:`.Sphinx.connect` in an extension's ``setup`` function, +or a ``setup`` function in your projects :file:`conf.py`, +to connect functions to the events: + +.. code-block:: python + + def source_read_handler(app, docname, source): + print('do something here...') + + def setup(app): + app.connect('source-read', source_read_handler) + +.. seealso:: + + Extensions can add their own events by using :meth:`.Sphinx.add_event`, + and calling them them with + :meth:`.Sphinx.emit` or :meth:`.Sphinx.emit_firstresult`. + +Core events overview +-------------------- + +Below is an overview of the core event that happens during a build. + +.. code-block:: none + + 1. event.config-inited(app,config) + 2. event.builder-inited(app) + 3. event.env-get-outdated(app, env, added, changed, removed) + 4. event.env-before-read-docs(app, env, docnames) + + for docname in docnames: + 5. event.env-purge-doc(app, env, docname) + + if doc changed and not removed: + 6. source-read(app, docname, source) + 7. run source parsers: text -> docutils.document + - parsers can be added with the app.add_source_parser() API + - event.include-read(app, relative_path, parent_docname, content) + is called for each include directive + 8. apply transforms based on priority: docutils.document -> docutils.document + - event.doctree-read(app, doctree) is called in the middle of transforms, + transforms come before/after this event depending on their priority. + + 9. event.env-merge-info(app, env, docnames, other) + - if running in parallel mode, this event will be emitted for each process + + 10. event.env-updated(app, env) + 11. event.env-get-updated(app, env) + + if environment is written to disk: + 12. event.env-check-consistency(app, env) + + 13. event.write-started(app, builder) + - This is called after ``app.parallel_ok`` has been set, + which must not be altered by any event handler. + + # The updated-docs list can be builder dependent, but generally includes all new/changed documents, + # plus any output from `env-get-updated`, and then all "parent" documents in the ToC tree + # For builders that output a single page, they are first joined into a single doctree before post-transforms + # or the doctree-resolved event is emitted + for docname in updated-docs: + 14. apply post-transforms (by priority): docutils.document -> docutils.document + 15. event.doctree-resolved(app, doctree, docname) + - In the event that any reference nodes fail to resolve, the following may emit: + - event.missing-reference(env, node, contnode) + - event.warn-missing-reference(domain, node) + + 16. Generate output files + 17. event.build-finished(app, exception) + +Here is also a flow diagram of the events, +within the context of the Sphinx build process: + +.. graphviz:: /_static/diagrams/sphinx_core_events_flow.dot + :caption: Sphinx core events flow + +Core event details +------------------ + +Here is a more detailed list of these events. + +.. event:: config-inited (app, config) + + :param app: :class:`.Sphinx` + :param config: :class:`.Config` + + Emitted when the config object has been initialized. + + .. versionadded:: 1.8 + +.. event:: builder-inited (app) + + :param app: :class:`.Sphinx` + + Emitted when the builder object has been created + (available as ``app.builder``). + +.. event:: env-get-outdated (app, env, added, changed, removed) + + :param app: :class:`.Sphinx` + :param env: :class:`.BuildEnvironment` + :param added: ``set[str]`` + :param changed: ``set[str]`` + :param removed: ``set[str]`` + :returns: ``list[str]`` of additional docnames to re-read + + Emitted when the environment determines which source files have changed and + should be re-read. + *added*, *changed* and *removed* are sets of docnames + that the environment has determined. + You can return a list of docnames to re-read in addition to these. + + .. versionadded:: 1.1 + +.. event:: env-purge-doc (app, env, docname) + + :param app: :class:`.Sphinx` + :param env: :class:`.BuildEnvironment` + :param docname: ``str`` + + Emitted when all traces of a source file should be cleaned from the + environment, that is, if the source file is removed or before it is freshly read. + This is for extensions that keep their own caches + in attributes of the environment. + + For example, there is a cache of all modules on the environment. + When a source file has been changed, the cache's entries for the file are cleared, + since the module declarations could have been removed from the file. + + .. versionadded:: 0.5 + +.. event:: env-before-read-docs (app, env, docnames) + + :param app: :class:`.Sphinx` + :param env: :class:`.BuildEnvironment` + :param docnames: ``list[str]`` + + Emitted after the environment has determined the list of all added and + changed files and just before it reads them. + It allows extension authors to reorder + the list of docnames (*inplace*) before processing, + or add more docnames that Sphinx did not consider changed + (but never add any docnames that are not in :attr:`.found_docs`). + + You can also remove document names; do this with caution since it will make + Sphinx treat changed files as unchanged. + + .. versionadded:: 1.3 + +.. event:: source-read (app, docname, content) + + :param app: :class:`.Sphinx` + :param docname: ``str`` + :param content: ``list[str]`` + with a single element, + representing the content of the included file. + + Emitted when a source file has been read. + + You can process the ``content`` and + replace this item to implement source-level transformations. + + For example, if you want to use ``$`` signs to delimit inline math, like in + LaTeX, you can use a regular expression to replace ``$...$`` by + ``:math:`...```. + + .. versionadded:: 0.5 + +.. event:: include-read (app, relative_path, parent_docname, content) + + :param app: :class:`.Sphinx` + :param relative_path: :class:`~pathlib.Path` + representing the included file + relative to the :term:`source directory`. + :param parent_docname: ``str`` + of the document name that + contains the :dudir:`include` directive. + :param content: ``list[str]`` + with a single element, + representing the content of the included file. + + Emitted when a file has been read with the :dudir:`include` directive. + + You can process the ``content`` and replace this item + to transform the included content, as with the :event:`source-read` event. + + .. versionadded:: 7.2.5 + + .. seealso:: The :dudir:`include` directive and the :event:`source-read` event. + +.. event:: object-description-transform (app, domain, objtype, contentnode) + + :param app: :class:`.Sphinx` + :param domain: ``str`` + :param objtype: ``str`` + :param contentnode: :class:`.desc_content` + + Emitted when an object description directive has run. The *domain* and + *objtype* arguments are strings indicating object description of the object. + And *contentnode* is a content for the object. It can be modified in-place. + + .. versionadded:: 2.4 + +.. event:: doctree-read (app, doctree) + + :param app: :class:`.Sphinx` + :param doctree: :class:`docutils.nodes.document` + + Emitted when a doctree has been parsed and read by the environment, and is + about to be pickled. + The ``doctree`` can be modified in-place. + +.. event:: missing-reference (app, env, node, contnode) + + :param app: :class:`.Sphinx` + :param env: :class:`.BuildEnvironment` + :param node: The :class:`.pending_xref` node to be resolved. + Its ``reftype``, ``reftarget``, ``modname`` and ``classname`` attributes + determine the type and target of the reference. + :param contnode: The node that carries the text and formatting inside the + future reference and should be a child of the returned reference node. + :returns: A new node to be inserted in the document tree in place of the node, + or ``None`` to let other handlers try. + + Emitted when a cross-reference to an object cannot be resolved. + If the event handler can resolve the reference, it should return a + new docutils node to be inserted in the document tree in place of the node + *node*. Usually this node is a :class:`~nodes.reference` node containing + *contnode* as a child. + If the handler can not resolve the cross-reference, + it can either return ``None`` to let other handlers try, + or raise :class:`~sphinx.errors.NoUri` to prevent other handlers in + trying and suppress a warning about this cross-reference being unresolved. + + .. versionadded:: 0.5 + +.. event:: warn-missing-reference (app, domain, node) + + :param app: :class:`.Sphinx` + :param domain: The :class:`.Domain` of the missing reference. + :param node: The :class:`.pending_xref` node that could not be resolved. + :returns: ``True`` if a warning was emitted, else ``None`` + + Emitted when a cross-reference to an object cannot be resolved even after + :event:`missing-reference`. + If the event handler can emit warnings for the missing reference, + it should return ``True``. + The configuration variables + :confval:`nitpick_ignore` and :confval:`nitpick_ignore_regex` + prevent the event from being emitted for the corresponding nodes. + + .. versionadded:: 3.4 + +.. event:: doctree-resolved (app, doctree, docname) + + :param app: :class:`.Sphinx` + :param doctree: :class:`docutils.nodes.document` + :param docname: ``str`` + + Emitted when a doctree has been "resolved" by the environment, that is, all + references have been resolved and TOCs have been inserted. The *doctree* can + be modified in place. + + Here is the place to replace custom nodes that don't have visitor methods in + the writers, so that they don't cause errors when the writers encounter them. + +.. event:: env-merge-info (app, env, docnames, other) + + :param app: :class:`.Sphinx` + :param env: :class:`.BuildEnvironment` + :param docnames: ``list[str]`` + :param other: :class:`.BuildEnvironment` + + This event is only emitted when parallel reading of documents is enabled. It + is emitted once for every subprocess that has read some documents. + + You must handle this event in an extension that stores data in the + environment in a custom location. Otherwise the environment in the main + process will not be aware of the information stored in the subprocess. + + *other* is the environment object from the subprocess, *env* is the + environment from the main process. *docnames* is a set of document names + that have been read in the subprocess. + + .. versionadded:: 1.3 + +.. event:: env-updated (app, env) + + :param app: :class:`.Sphinx` + :param env: :class:`.BuildEnvironment` + :returns: iterable of ``str`` + + Emitted after reading all documents, when the environment and all + doctrees are now up-to-date. + + You can return an iterable of docnames from the handler. These documents + will then be considered updated, and will be (re-)written during the writing + phase. + + .. versionadded:: 0.5 + + .. versionchanged:: 1.3 + The handlers' return value is now used. + +.. event:: env-get-updated (app, env) + + :param app: :class:`.Sphinx` + :param env: :class:`.BuildEnvironment` + :returns: iterable of ``str`` + + Emitted when the environment determines which source files have changed and + should be re-read. + You can return an iterable of docnames to re-read. + +.. event:: env-check-consistency (app, env) + + :param app: :class:`.Sphinx` + :param env: :class:`.BuildEnvironment` + + Emitted when Consistency checks phase. You can check consistency of + metadata for whole of documents. + + .. versionadded:: 1.6 + +.. event:: write-started (app, builder) + + :param app: :class:`.Sphinx` + :param builder: :class:`.Builder` + + Emitted before the builder starts to + resolve and write documents. + + .. versionadded:: 7.4 + +.. event:: build-finished (app, exception) + + :param app: :class:`.Sphinx` + :param exception: ``Exception`` or ``None`` + + Emitted when a build has finished, before Sphinx exits, usually used for + cleanup. This event is emitted even when the build process raised an + exception, given as the *exception* argument. The exception is reraised in + the application after the event handlers have run. If the build process + raised no exception, *exception* will be ``None``. This allows to customize + cleanup actions depending on the exception status. + + .. versionadded:: 0.5 + +Builder specific events +----------------------- + +These events are emitted by specific builders. + +.. event:: html-collect-pages (app) + + :param app: :class:`.Sphinx` + :returns: iterable of ``(pagename, context, templatename)`` + where *pagename* and *templatename* are strings and + *context* is a ``dict[str, Any]``. + + Emitted when the HTML builder is starting to write non-document pages. + + You can add pages to write by returning an iterable from this event. + + .. versionadded:: 1.0 + +.. event:: html-page-context (app, pagename, templatename, context, doctree) + + :param app: :class:`.Sphinx` + :param pagename: ``str`` + :param templatename: ``str`` + :param context: ``dict[str, Any]`` + :param doctree: :class:`docutils.nodes.document` or ``None`` + :returns: ``str`` or ``None`` + + Emitted when the HTML builder has created a context dictionary to render a + template with -- this can be used to add custom elements to the context. + + The *pagename* argument is the canonical name of the page being rendered, + that is, without ``.html`` suffix and using slashes as path separators. + The *templatename* is the name of the template to render, this will be + ``'page.html'`` for all pages from reStructuredText documents. + + The *context* argument is a dictionary of values that are given to the + template engine to render the page and can be modified to include custom + values. + + The *doctree* argument will be a doctree when + the page is created from a reStructuredText documents; + it will be ``None`` when the page is created from an HTML template alone. + + You can return a string from the handler, it will then replace + ``'page.html'`` as the HTML template for this page. + + .. tip:: + + You can install JS/CSS files for the specific page via + :meth:`.Sphinx.add_js_file` and :meth:`.Sphinx.add_css_file` + (since v3.5.0). + + .. versionadded:: 0.4 + + .. versionchanged:: 1.3 + The return value can now specify a template name. + +.. event:: linkcheck-process-uri (app, uri) + + :param app: :class:`.Sphinx` + :param uri: ``str`` of the collected URI + :returns: ``str`` or ``None`` + + Emitted when the linkcheck builder collects hyperlinks from document. + + The event handlers can modify the URI by returning a string. + + .. versionadded:: 4.1 diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index 8332315..9617dd4 100644 --- a/doc/extdev/index.rst +++ b/doc/extdev/index.rst @@ -1,7 +1,7 @@ .. _dev-extensions: -Sphinx Extensions API -===================== +Sphinx API +========== Since many projects will need special features in their documentation, Sphinx is designed to be extensible on several levels. @@ -85,7 +85,7 @@ extension. These are: The config is available as ``app.config`` or ``env.config``. To see an example of use of these objects, refer to -:doc:`../development/tutorials/index`. +:ref:`the tutorials <extension-tutorials-index>`. .. _build-phases: @@ -147,7 +147,7 @@ the individual nodes of each doctree and produces some output in the process. that checks external links does not need anything more than the parsed doctrees and therefore does not have phases 2--4. -To see an example of application, refer to :doc:`../development/tutorials/todo`. +To see an example of application, refer to :ref:`tutorial-extend-build`. .. _ext-metadata: @@ -204,6 +204,7 @@ disposal when developing Sphinx extensions. Some are core to Sphinx :maxdepth: 2 appapi + event_callbacks projectapi envapi builderapi diff --git a/doc/extdev/markupapi.rst b/doc/extdev/markupapi.rst index 072760c..7aa6324 100644 --- a/doc/extdev/markupapi.rst +++ b/doc/extdev/markupapi.rst @@ -1,12 +1,53 @@ Docutils markup API =================== -This section describes the API for adding ReST markup elements (roles and -directives). +This section describes the API for adding reStructuredText markup elements +(roles and directives). + Roles ----- +Roles follow the interface described below. +They have to be registered by an extension using +:meth:`.Sphinx.add_role` or :meth:`.Sphinx.add_role_to_domain`. + + +.. code-block:: python + + def role_function( + role_name: str, raw_source: str, text: str, + lineno: int, inliner: Inliner, + options: dict = {}, content: list = [], + ) -> tuple[list[Node], list[system_message]]: + elements = [] + messages = [] + return elements, messages + +The *options* and *content* parameters are only used for custom roles +created via the :dudir:`role` directive. +The return value is a tuple of two lists, +the first containing the text nodes and elements from the role, +and the second containing any system messages generated. +For more information, see the `custom role overview`_ from Docutils. + +.. _custom role overview: https://docutils.sourceforge.io/docs/howto/rst-roles.html + + +Creating custom roles +^^^^^^^^^^^^^^^^^^^^^ + +Sphinx provides two base classes for creating custom roles, +:class:`~sphinx.util.docutils.SphinxRole` and :class:`~sphinx.util.docutils.ReferenceRole`. + +These provide a class-based interface for creating roles, +where the main logic must be implemented in your ``run()`` method. +The classes provide a number of useful methods and attributes, +such as ``self.text``, ``self.config``, and ``self.env``. +The ``ReferenceRole`` class implements Sphinx's ``title <target>`` logic, +exposing ``self.target`` and ``self.title`` attributes. +This is useful for creating cross-reference roles. + Directives ---------- @@ -85,68 +126,106 @@ using :meth:`.Sphinx.add_directive` or :meth:`.Sphinx.add_directive_to_domain`. The state and state machine which controls the parsing. Used for ``nested_parse``. +.. seealso:: + + `Creating directives`_ HOWTO of the Docutils documentation + + .. _Creating directives: https://docutils.sourceforge.io/docs/howto/rst-directives.html + + +.. _parsing-directive-content-as-rest: + +Parsing directive content as reStructuredText +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -ViewLists -^^^^^^^^^ +Many directives will contain more markup that must be parsed. +To do this, use one of the following APIs from the :meth:`~Directive.run` method: -Docutils represents document source lines in a class -``docutils.statemachine.ViewList``. This is a list with extended functionality --- for one, slicing creates views of the original list, and also the list -contains information about the source line numbers. +* :py:meth:`.SphinxDirective.parse_content_to_nodes()` +* :py:meth:`.SphinxDirective.parse_text_to_nodes()` -The :attr:`Directive.content` attribute is a ViewList. If you generate content -to be parsed as ReST, you have to create a ViewList yourself. Important for -content generation are the following points: +The first method parses all the directive's content as markup, +whilst the second only parses the given *text* string. +Both methods return the parsed Docutils nodes in a list. -* The constructor takes a list of strings (lines) and a source (document) name. +The methods are used as follows: -* The ``.append()`` method takes a line and a source name as well. +.. code-block:: python + def run(self) -> list[Node]: + # either + parsed = self.parse_content_to_nodes() + # or + parsed = self.parse_text_to_nodes('spam spam spam') + return parsed -Parsing directive content as ReST -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. note:: + + The above utility methods were added in Sphinx 7.4. + Prior to Sphinx 7.4, the following methods should be used to parse content: -Many directives will contain more markup that must be parsed. To do this, use -one of the following APIs from the :meth:`Directive.run` method: + * ``self.state.nested_parse`` + * :func:`sphinx.util.nodes.nested_parse_with_titles` -- this allows titles in + the parsed content. -* ``self.state.nested_parse`` -* :func:`sphinx.util.nodes.nested_parse_with_titles` -- this allows titles in - the parsed content. + .. code-block:: python -Both APIs parse the content into a given node. They are used like this:: + def run(self) -> list[Node]: + container = docutils.nodes.Element() + # either + nested_parse_with_titles(self.state, self.result, container) + # or + self.state.nested_parse(self.result, 0, container) + parsed = container.children + return parsed - node = docutils.nodes.paragraph() - # either - nested_parse_with_titles(self.state, self.result, node) - # or - self.state.nested_parse(self.result, 0, node) +To parse inline markup, +use :py:meth:`~sphinx.util.docutils.SphinxDirective.parse_inline()`. +This must only be used for text which is a single line or paragraph, +and does not contain any structural elements +(headings, transitions, directives, etc). .. note:: - ``sphinx.util.docutils.switch_source_input()`` allows to change a target file - during nested_parse. It is useful to mixed contents. For example, ``sphinx. - ext.autodoc`` uses it to parse docstrings:: + ``sphinx.util.docutils.switch_source_input()`` allows changing + the source (input) file during parsing content in a directive. + It is useful to parse mixed content, such as in ``sphinx.ext.autodoc``, + where it is used to parse docstrings. + + .. code-block:: python - from sphinx.util.docutils import switch_source_input + from sphinx.util.docutils import switch_source_input + from sphinx.util.parsing import nested_parse_to_nodes - # Switch source_input between parsing content. - # Inside this context, all parsing errors and warnings are reported as - # happened in new source_input (in this case, ``self.result``). - with switch_source_input(self.state, self.result): - node = docutils.nodes.paragraph() - self.state.nested_parse(self.result, 0, node) + # Switch source_input between parsing content. + # Inside this context, all parsing errors and warnings are reported as + # happened in new source_input (in this case, ``self.result``). + with switch_source_input(self.state, self.result): + parsed = nested_parse_to_nodes(self.state, self.result) .. deprecated:: 1.7 Until Sphinx 1.6, ``sphinx.ext.autodoc.AutodocReporter`` was used for this purpose. It is replaced by ``switch_source_input()``. -If you don't need the wrapping node, you can use any concrete node type and -return ``node.children`` from the Directive. +.. _ViewLists: -.. seealso:: +ViewLists and StringLists +^^^^^^^^^^^^^^^^^^^^^^^^^ - `Creating directives`_ HOWTO of the Docutils documentation +Docutils represents document source lines in a ``StringList`` class, +which inherits from ``ViewList``, both in the ``docutils.statemachine`` module. +This is a list with extended functionality, +including that slicing creates views of the original list and +that the list contains information about source line numbers. + +The :attr:`Directive.content` attribute is a ``StringList``. +If you generate content to be parsed as reStructuredText, +you have to create a ``StringList`` for the Docutils APIs. +The utility functions provided by Sphinx handle this automatically. +Important for content generation are the following points: -.. _Creating directives: https://docutils.sourceforge.io/docs/howto/rst-directives.html +* The ``ViewList`` constructor takes a list of strings (lines) + and a source (document) name. +* The ``ViewList.append()`` method takes a line and a source name as well. diff --git a/doc/extdev/utils.rst b/doc/extdev/utils.rst index ff8dc4e..9e10a0d 100644 --- a/doc/extdev/utils.rst +++ b/doc/extdev/utils.rst @@ -3,6 +3,7 @@ Utilities Sphinx provides utility classes and functions to develop extensions. + Base classes for components --------------------------- @@ -30,12 +31,20 @@ components (e.g. :class:`.Config`, :class:`.BuildEnvironment` and so on) easily. .. autoclass:: sphinx.transforms.post_transforms.images.ImageConverter :members: + Utility components ------------------ .. autoclass:: sphinx.events.EventManager :members: + +Utility functions +----------------- + +.. autofunction:: sphinx.util.parsing.nested_parse_to_nodes + + Utility types ------------- diff --git a/doc/faq.rst b/doc/faq.rst index 8538cdc..7645326 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -30,10 +30,10 @@ How do I... ``sidebartoc`` block. ... write my own extension? - See the :doc:`/development/tutorials/index`. + See the :ref:`extension-tutorials-index`. ... convert from my existing docs using MoinMoin markup? - The easiest way is to convert to xhtml, then convert `xhtml to reST`_. + The easiest way is to convert to xhtml, then convert `xhtml to reStructuredText`_. You'll still need to mark up classes and such, but the headings and code examples come through cleanly. @@ -58,8 +58,8 @@ Epydoc Epydoc's API docs for a given identifier. Doxygen - Michael Jones is developing a reST/Sphinx bridge to doxygen called `breathe - <https://github.com/michaeljones/breathe/tree/master>`_. + Michael Jones has developed a reStructuredText/Sphinx bridge to doxygen + called `breathe <https://github.com/breathe-doc/breathe/tree/master>`_. SCons Glenn Hutchings has written a SCons build script to build Sphinx @@ -147,7 +147,7 @@ Google Search .. _Getting Started: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html .. _api role: https://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py -.. _xhtml to reST: https://docutils.sourceforge.io/sandbox/xhtml2rest/xhtml2rest.py +.. _xhtml to reStructuredText: https://docutils.sourceforge.io/sandbox/xhtml2rest/xhtml2rest.py Sphinx vs. Docutils diff --git a/doc/glossary.rst b/doc/glossary.rst index 85e0057..24653b6 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. @@ -36,9 +36,10 @@ Glossary See :ref:`rst-directives` for more information. document name - Since reST source files can have different extensions (some people like - ``.txt``, some like ``.rst`` -- the extension can be configured with - :confval:`source_suffix`) and different OSes have different path + Since reStructuredText source files can have different extensions + (some people like ``.txt``, some like ``.rst`` -- the extension can be + configured with :confval:`source_suffix`) + and different OSes have different path separators, Sphinx abstracts them: :dfn:`document names` are always relative to the :term:`source directory`, the extension is stripped, and path separators are converted to slashes. All values, parameters and such diff --git a/doc/index.rst b/doc/index.rst index 6dfdb6d..bf3653c 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,40 +1,116 @@ -======= -Welcome -======= - -.. epigraph:: Sphinx makes it easy to create intelligent and beautiful documentation. - -Here are some of Sphinx's major features: - -* **Output formats:** HTML (including Windows HTML Help), LaTeX (for printable - PDF versions), ePub, Texinfo, manual pages, plain text -* **Extensive cross-references:** semantic markup and automatic links for - functions, classes, citations, glossary terms and similar pieces of - information -* **Hierarchical structure:** easy definition of a document tree, with automatic - links to siblings, parents and children -* **Automatic indices:** general index as well as a language-specific module - indices -* **Code handling:** automatic highlighting using the Pygments_ highlighter -* **Extensions:** automatic testing of code snippets, inclusion of docstrings - from Python modules (API docs) via :ref:`built-in extensions - <builtin-extensions>`, and much more functionality via :ref:`third-party - extensions <third-party-extensions>`. -* **Themes:** modify the look and feel of outputs via :doc:`creating themes - <development/theming>`, and reuse many :ref:`third-party themes - <third-party-themes>`. -* **Contributed extensions:** dozens of extensions :ref:`contributed by users - <third-party-extensions>`; most of them installable from PyPI. - -.. _reStructuredText: https://docutils.sourceforge.io/rst.html -.. _Docutils: https://docutils.sourceforge.io/ -.. _Pygments: https://pygments.org/ - -Sphinx uses the reStructuredText_ markup language by default, and can read -:ref:`MyST markdown <markdown>` via third-party extensions. Both of these -are powerful and straightforward to use, and have functionality -for complex documentation and publishing workflows. They both build upon -Docutils_ to parse and write documents. +====== +Sphinx +====== + +.. cssclass:: sphinx-tagline +.. epigraph:: Create intelligent and beautiful documentation with ease + +.. container:: sphinx-features + + .. admonition:: 📝 Rich Text Formatting + :class: sphinx-feature + + Author in :ref:`reStructuredText <rst-primer>` + or :ref:`MyST Markdown <markdown>` + to create highly structured technical documents, + including tables, highlighted code blocks, mathematical notations, and more. + + .. admonition:: 🔗 Powerful Cross-Referencing + :class: sphinx-feature + + Create :ref:`cross-references <xref-syntax>` + within your project, + and even across :ref:`different projects <ext-intersphinx>`. + Include references to + sections, figures, tables, citations, glossaries, code objects, + and more. + + .. admonition:: 📚 Versatile Documentation Formats + :class: sphinx-feature + + Generate documentation in the preferred formats of your audience, including + HTML, LaTeX (for PDF), ePub, Texinfo, :ref:`and more <builders>`. + + .. admonition:: 🎨 Extensive Theme Support + :class: sphinx-feature + + Create visually appealing documentation, + with a wide choice of :ref:`built-in <builtin-themes>` + and :ref:`third-party <third-party-themes>` HTML themes + and the ability to customize + or :ref:`create new themes <extension-html-theme>`. + + .. admonition:: 🔌 Fully Extensible + :class: sphinx-feature + + Add custom functionality, + via robust :ref:`extension mechanisms <extending-sphinx>` + with numerous :ref:`built-in <builtin-extensions>` + and :ref:`third-party <third-party-extensions>` + extensions available for tasks like + creating diagrams, testing code, and more. + + .. admonition:: 🛠️ Automatic API Documentation + :class: sphinx-feature + + Generate API documentation for + Python, C++ and other :ref:`software domains <usage-domains>`, + manually or :ref:`automatically from docstrings <ext-autodoc>`, + ensuring your code documentation + stays up-to-date with minimal effort. + + .. admonition:: 🌍 Internationalization (i18n) + :class: sphinx-feature + + Add documentation :ref:`translations <intl>` + multiple languages to reach a global audience. + + .. admonition:: 🌟 Active Community and Support + :class: sphinx-feature + + Benefit from an :ref:`active community <support-index>`, + with numerous resources, tutorials, forums, and examples. + + .. .. admonition:: 🌐 Integration with Version Control + .. :class: sphinx-feature + + .. Sphinx integrates seamlessly with version control systems like Git. + .. This allows for easy collaboration, version tracking, + .. and deployment of documentation as part of a continuous integration pipeline. + +---------------- + +.. container:: sphinx-users + + As used by: + + .. container:: sphinx-users-logos + + .. figure:: _static/python-logo.png + :alt: Python Logo + :height: 100px + :align: center + :target: https://docs.python.org + + Python + + .. figure:: _static/linux-logo.png + :alt: Linux Logo + :height: 100px + :align: center + :target: https://docs.kernel.org/ + + Linux Kernel + + .. figure:: _static/jupyter-logo.png + :alt: Jupyter Logo + :height: 100px + :align: center + :target: https://docs.jupyter.org + + Project Jupyter + +---------------- See below for how to navigate Sphinx's documentation. @@ -53,10 +129,10 @@ creating and building your own documentation from scratch. .. toctree:: :maxdepth: 2 - :caption: Get started + :caption: The Basics - usage/quickstart usage/installation + usage/quickstart tutorial/index .. _user-guides: @@ -75,8 +151,8 @@ starting with :ref:`get-started`. usage/index development/index - latex extdev/index + latex Community guide =============== diff --git a/doc/internals/contributing.rst b/doc/internals/contributing.rst index 207374e..eac3560 100644 --- a/doc/internals/contributing.rst +++ b/doc/internals/contributing.rst @@ -156,7 +156,7 @@ Please follow these guidelines when writing code for Sphinx: Style and type checks can be run as follows:: - ruff . + ruff check . mypy sphinx/ Unit tests @@ -338,3 +338,9 @@ Debugging tips Minified files in ``sphinx/search/minified-js/*.js`` are generated from non-minified ones using ``uglifyjs`` (installed via npm), with ``-m`` option to enable mangling. + +* The ``searchindex.js`` files found in the ``tests/js/fixtures/*`` directories + are generated by using the standard Sphinx HTML builder on the corresponding + input projects found in ``tests/js/roots/*``. The fixtures provide test data + used by the Sphinx JavaScript unit tests, and can be regenerated by running + the ``utils/generate_js_fixtures.py`` script. diff --git a/doc/latex.rst b/doc/latex.rst index 0101b24..821c832 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -10,12 +10,12 @@ LaTeX customization \begingroup \sphinxsetup{% - TitleColor={named}{DarkGoldenrod}, + TitleColor=DarkGoldenrod, pre_border-width=2pt, pre_border-right-width=8pt, pre_padding=5pt, pre_border-radius=5pt, - pre_background-TeXcolor={named}{OldLace}, + pre_background-TeXcolor=OldLace, pre_border-TeXcolor=Gold!90, pre_box-shadow=6pt 6pt, pre_box-shadow-TeXcolor=gray!20, @@ -52,6 +52,9 @@ interface for customization. For example: # inside conf.py latex_engine = 'xelatex' latex_elements = { + 'passoptionstopackages': r''' + \PassOptionsToPackage{svgnames}{xcolor} + ''', 'fontpkg': r''' \setmainfont{DejaVu Serif} \setsansfont{DejaVu Sans} @@ -64,6 +67,7 @@ interface for customization. For example: \setlength{\cftsecindent}{\cftchapnumwidth} \setlength{\cftsecnumwidth}{1.25cm} ''', + 'sphinxsetup': 'TitleColor=DarkGoldenrod', 'fncychap': r'\usepackage[Bjornstrup]{fncychap}', 'printindex': r'\footnotesize\raggedright\printindex', } @@ -148,7 +152,7 @@ Keys that you may want to override include: build repertory before next PDF build, else left-over auxiliary files are likely to break the build. - Default: ``'\\usepackage{babel}'`` (``''`` for Japanese documents) + Default: ``'\\usepackage{babel}'`` (for Japanese documents) .. versionchanged:: 1.5 For :confval:`latex_engine` set to ``'xelatex'``, the default @@ -158,8 +162,11 @@ Keys that you may want to override include: ``'lualatex'`` uses same default setting as ``'xelatex'`` .. versionchanged:: 1.7.6 - For French, ``xelatex`` and ``lualatex`` default to using - ``babel``, not ``polyglossia``. + For French with ``'xelatex'`` (not ``'lualatex'``) the default is to + use ``babel``, not ``polyglossia``. + + .. versionchanged:: 7.4.0 + For French with ``'lualatex'`` the default is to use ``babel``. ``'fontpkg'`` Font package inclusion. The default is:: @@ -422,14 +429,14 @@ Keys that don't need to be overridden unless in special cases are: ``'geometry'`` "geometry" package inclusion, the default definition is: - .. code:: latex + .. code-block:: latex '\\usepackage{geometry}' with an additional ``[dvipdfm]`` for Japanese documents. The Sphinx LaTeX style file executes: - .. code:: latex + .. code-block:: latex \PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry} @@ -588,23 +595,22 @@ provides a LaTeX-type customization interface:: 'sphinxsetup': 'key1=value1, key2=value2, ...', } -It defaults to empty. If non-empty, it will be passed as argument to the +LaTeX syntax for boolean keys requires *lowercase* ``true`` or ``false`` +e.g ``'sphinxsetup': "verbatimwrapslines=false"``. If setting a +boolean key to ``true``, ``=true`` is optional. +Spaces around the commas and equal signs are ignored, spaces inside LaTeX +macros may be significant. +Do not use ticks/quotes to enclose string or numerical values. + +The ``'sphinxsetup'`` defaults to empty. +If non-empty, it will be passed as argument to the ``\sphinxsetup`` macro inside the document preamble, like this:: \usepackage{sphinx} \sphinxsetup{key1=value1, key2=value2,...} -The colors used in the above are provided by the ``svgnames`` option of the -"xcolor" package:: - - latex_elements = { - 'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}', - } - It is possible to insert uses of the ``\sphinxsetup`` LaTeX macro directly -into the body of the document, via the ``raw`` directive. This chapter is -styled in the PDF output using the following insertion at its start. This -uses keys described later in :ref:`additionalcss`. +into the body of the document, via the ``raw`` directive: .. code-block:: latex @@ -612,83 +618,31 @@ uses keys described later in :ref:`additionalcss`. \begingroup \sphinxsetup{% - TitleColor={named}{DarkGoldenrod}, - % pre_border-width is 5.1.0 alias for verbatimborder - pre_border-width=2pt, - pre_border-right-width=8pt, - % pre_padding is a 5.1.0 alias for verbatimsep - pre_padding=5pt, - % Rounded boxes are new at 5.1.0 - pre_border-radius=5pt, - % TeXcolor reminds that syntax must be as for LaTeX \definecolor - pre_background-TeXcolor={named}{OldLace}, - % ... and since 5.3.0 also xcolor \colorlet syntax is accepted and we - % can thus drop the {named}{...} thing if xcolor is available! - pre_border-TeXcolor=Gold, - % ... and even take more advantage of xcolor syntax: - pre_border-TeXcolor=Gold!90, - % add a shadow to code-blocks - pre_box-shadow=6pt 6pt, - pre_box-shadow-TeXcolor=gray!20, - % - % This 5.1.0 CSS-named option is alias for warningborder - div.warning_border-width=3pt, - % Prior to 5.1.0, padding for admonitions was not customizable - div.warning_padding=6pt, - div.warning_padding-right=18pt, - div.warning_padding-bottom=18pt, - % Assume xcolor has been loaded with its svgnames option - div.warning_border-TeXcolor=DarkCyan, - div.warning_background-TeXcolor=LightCyan, - % This one is the only option with space separated input: - div.warning_box-shadow=-12pt -12pt inset, - div.warning_box-shadow-TeXcolor=Cyan, - % - % The 5.1.0 new name would be div.attention_border-width - attentionborder=3pt, - % The 5.1.0 name here would be div.attention_border-TeXcolor - attentionBorderColor=Crimson, - % The 5.1.0 name would be div.attention_background-TeXcolor - attentionBgColor=FloralWhite, - % - % For note/hint/important/tip, the CSS syntax was added at 6.2.0 - % Legacy syntax still works - noteborder=1pt, - noteBorderColor=Olive, - % But setting a background color via the new noteBgColor means that - % it will be rendered using the same interface as warning type - noteBgColor=Olive!10, - % We can customize separately the four border-widths, and mimic - % the legacy "light" rendering, but now with a background color: - % div.note_border-left-width=0pt, - % div.note_border-right-width=0pt, - % Let's rather for variety use lateral borders: - div.note_border-top-width=0pt, - div.note_border-bottom-width=0pt, - % - % As long as only border width and border color are set, *and* using - % for this the old interface, the rendering will be the "light" one - hintBorderColor=LightCoral, - % but if we had used div.hint_border-TeXcolor or *any* CSS-named - % option we would have triggered the more complex "heavybox" code. + TitleColor=DarkGoldenrod, + ... more comma separated key=value using LaTeX syntax ... } - -And this is placed at the end of the chapter source to end the scope of -the configuration: - -.. code-block:: latex + All elements here will be under the influence of the raw ``\sphinxsetup`` + settings. .. raw:: latex \endgroup -LaTeX syntax for boolean keys requires *lowercase* ``true`` or ``false`` -e.g ``'sphinxsetup': "verbatimwrapslines=false"``. If setting the -boolean key to ``true``, ``=true`` is optional. -Spaces around the commas and equal signs are ignored, spaces inside LaTeX -macros may be significant. -Do not use quotes to enclose values, whether numerical or strings. + From here on, the raw ``\sphinxsetup`` has no effect anymore. + +This is the technique which has been used to style especially the present part +of the documentation for the PDF output. The actually used options will be +found at top of :file:`doc/latex.rst` at the `development repository`_. + +.. _development repository: https://github.com/sphinx-doc/sphinx + +The color used in the above example is available from having passed the +``svgnames`` option to the "xcolor" package:: + + latex_elements = { + 'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}', + } ``bookmarksdepth`` Controls the depth of the collapsible bookmarks panel in the PDF. @@ -748,7 +702,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. @@ -875,11 +829,10 @@ Do not use quotes to enclose values, whether numerical or strings. - obey the syntax of the ``\definecolor`` LaTeX command, e.g. something such as ``VerbatimColor={rgb}{0.2,0.3,0.5}`` or ``{RGB}{37,23,255}`` or - ``{gray}{0.75}`` or (only with package ``xcolor``) ``{HTML}{808080}`` or + ``{gray}{0.75}`` or ``{HTML}{808080}`` or ... - or obey the syntax of the ``\colorlet`` command from package ``xcolor`` - (which then must exist in the LaTeX installation), e.g. ``VerbatimColor=red!10`` or ``red!50!green`` or ``-red!75`` or ``MyPreviouslyDefinedColor`` or... Refer to xcolor_ documentation for this syntax. @@ -909,7 +862,7 @@ Do not use quotes to enclose values, whether numerical or strings. ``VerbatimColor`` The background color for :rst:dir:`code-block`\ s. - Default: ``{gray}{0.95}`` + Default: ``{RGB}{242,242,242}`` (same as ``{gray}{0.95}``). .. versionchanged:: 6.0.0 @@ -1014,27 +967,48 @@ Do not use quotes to enclose values, whether numerical or strings. Default: ``\fboxrule`` +.. important:: + + At 7.4.0 all admonitions (not only danger-type) use the possibilities + which were added at 5.1.0 and 6.2.0. All defaults have changed. + +``iconpackage`` + + The name of the LaTeX package used for icons in the admonition titles. It + defaults to ``fontawesome5`` or to fall-back ``fontawesome``. In case + neither one is available the option value will automatically default to + ``none``, which means that no attempt at loading a package is done. + Independently of this setting, arbitrary LaTeX code can be associated to + each admonition type via ``div.<type>_icon-title`` keys which are + described in the :ref:`additionalcss` section. If these keys are not + used, Sphinx will either apply its default choices of icons (if + ``fontawesome{5,}`` is available) or not draw the icon at all. Notice that + if fall-back ``fontawesome`` is used the common icon for :dudir:`caution` + and :dudir:`danger` will default to "bolt" not "radiation", which is only + found in ``fontawesome5``. + + .. versionadded:: 7.4.0 + |notebdcolors| - The color for the two horizontal rules used by Sphinx in LaTeX for styling - a :dudir:`note` type admonition. + The color for the admonition border. + + Default: ``{RGB}{134,152,155}``. - Default: ``{rgb}{0,0,0}`` (black) + .. versionchanged:: 7.4.0 |notebgcolors| - The optional color for the background. It is a priori set to white, but - is not used, unless it has been set explicitly, and doing this triggers - Sphinx into switching to the more complex LaTeX code which is employed - also for ``warning`` type admonitions. There are then additional options - which are described in :ref:`additionalcss`. + The color for the admonition background. - Default: ``{rgb}{1,1,1}`` (white) + Default: ``{RGB}{247,247,247}``. .. versionadded:: 6.2.0 + .. versionchanged:: 7.4.0 + |notetextcolors| - The optional color for the contents. + The color for the admonition contents. - Default: unset (uses ambient text color, a priori black) + Default: unset (contents text uses ambient text color, a priori black) .. versionadded:: 6.2.0 @@ -1055,41 +1029,45 @@ Do not use quotes to enclose values, whether numerical or strings. ``div.note_TeXextras`` (etc) described in :ref:`additionalcss`. ``noteborder``, ``hintborder``, ``importantborder``, ``tipborder`` - The width of the two horizontal rules. - - If the background color is set, or the alternative :ref:`additionalcss` - syntax is used (e.g. ``div.note_border-width=1pt`` in place of - ``noteborder=1pt``), or *any* option with a CSS-alike name is used, then - the border is a full frame and this parameter sets its width also for left - and right. + The width of the border. See + :ref:`additionalcss` for keys allowing to configure separately each + border width. Default: ``0.5pt`` .. only:: not latex |warningbdcolors| - The color for the admonition frame. + The color for the admonition border. + + Default: ``{RGB}{148,0,0}`` except for ``error`` which uses ``red``. - Default: ``{rgb}{0,0,0}`` (black) + .. versionchanged:: 7.4.0 .. only:: latex |wgbdcolorslatex| - The color for the admonition frame. + The color for the admonition border. + + Default: ``{RGB}{148,0,0}`` except for ``error`` which uses ``red``. - Default: ``{rgb}{0,0,0}`` (black) + .. versionchanged:: 7.4.0 |warningbgcolors| - The background colors for the respective admonitions. + The background color for the admonition background. - Default: ``{rgb}{1,1,1}`` (white) + Default: ``{RGB}{247,247,247}``. + + .. versionchanged:: 7.4.0 |warningborders| - The width of the frame. See + The width of the admonition frame. See :ref:`additionalcss` for keys allowing to configure separately each border width. - Default: ``1pt`` + Default: ``1pt`` except for ``error`` which uses ``1.25pt``. + + .. versionchanged:: 7.4.0 ``AtStartFootnote`` LaTeX macros inserted at the start of the footnote text at bottom of page, @@ -1157,6 +1135,20 @@ Additional CSS-like ``'sphinxsetup'`` keys ``noteBgColor`` (or ``hintBgColor``, ...) also triggers usage of ``sphinxheavybox`` for :dudir:`note` (or :dudir:`hint`, ...). +.. versionadded:: 7.4.0 + + For *all* admonition types, the default configuration does set a background + color (hence the richer ``sphinxheavybox`` is always used). + +.. important:: + + Further, all admonition titles are by default styled using a colored row + and an icon, which are modeled on the current rendering of Sphinx own + docs at https://www.sphinx-doc.org. CSS-named alike keys are added to + set the foreground and background colors for the title as well as the + LaTeX code for the icon. + + Perhaps in future these 5.1.0 (and 6.2.0) novel settings will be optionally imported from some genuine CSS external file, but currently they have to be used via the ``'sphinxsetup'`` interface (or the ``\sphinxsetup`` LaTeX command @@ -1166,13 +1158,12 @@ inserted via the :dudir:`raw` directive) and the CSS syntax is only imitated. the input syntax is not respected. * In particular colors must be input as for the other color related options - previously described, i.e. either in the ``\definecolor`` syntax or, if - package ``xcolor`` is available (it is then automatically used) also the + previously described, i.e. either in the ``\definecolor`` syntax or via the ``\colorlet`` syntax:: ...<other options> - div.warning_border-TeXcolor={rgb}{1,0,0},% (always works) - div.error_background-TeXcolor=red!10,% (works only if xcolor is available) + div.warning_border-TeXcolor={rgb}{1,0,0},% \definecolor syntax + div.error_background-TeXcolor=red!10,% \colorlet syntax ...<other options> * A colon in place of the equal sign will break LaTeX. @@ -1209,9 +1200,15 @@ which is then followed by an underscore, then the property name. :rst:dir:`code-block`, ``pre``, ``sphinxVerbatim`` :dudir:`topic`, ``div.topic``, ``sphinxShadowBox`` contents_, ``div.topic``, ``sphinxShadowBox`` - :dudir:`note`, ``div.note``, ``sphinxnote`` using ``sphinxheavybox`` - :dudir:`warning`, ``div.warning``, ``sphinxwarning`` (uses ``sphinxheavybox``) - admonition type, ``div.<type>``, ``sphinx<type>`` (using ``sphinxheavybox``) + :dudir:`note`, ``div.note``, ``sphinxnote`` + :dudir:`warning`, ``div.warning``, ``sphinxwarning`` + further admonition types ``<type>``, ``div.<type>``, ``sphinx<type>`` + :rst:dir:`seealso`, ``div.seealso``, ``sphinxseealso`` + :rst:dir:`todo`, ``div.todo``, ``sphinxtodo`` + + +.. versionadded:: 7.4.0 Customizability of the :rst:dir:`seealso` and + :rst:dir:`todo` directives. Here are now these options as well as their common defaults. Replace below ``<prefix>`` by the actual prefix as explained above. Don't @@ -1226,13 +1223,16 @@ forget the underscore separating the prefix from the property names. The default is that all those dimensions are equal. They are set to: - * ``\fboxrule`` (i.e. a priori ``0.4pt``) for :rst:dir:`code-block`, - * ``\fboxrule`` for :dudir:`topic` or contents_ directive, - * ``1pt`` for :dudir:`warning` and other "strong" admonitions, - * ``0.5pt`` for :dudir:`note` and other "light" admonitions. The framing - style of the "lighbox" used for them in absence of usage of CSS-named - options will be emulated by the richer "heavybox" if setting - ``border-left-width`` and ``border-right-width`` both to ``0pt``. + * ``0.4pt`` for :rst:dir:`code-block`, + * ``0.5pt`` for :dudir:`topic` or contents_ directive, + * ``0.5pt`` for :dudir:`note` and other "light" admonitions, + * ``0.5pt`` for :rst:dir:`seealso` and :rst:dir:`todo` directives, + * ``1pt`` for :dudir:`warning` and other "strong" admonitions except + :dudir:`error` which uses ``1.25pt``. + + .. versionchanged:: 7.4.0 + + Changed defaults for :dudir:`topic` and :dudir:`error`. - ``<prefix>_box-decoration-break`` can be set to either ``clone`` or ``slice`` and configures the behavior at page breaks. @@ -1245,25 +1245,24 @@ forget the underscore separating the prefix from the property names. | ``<prefix>_padding``. The latter can (currently) be only a *single* dimension which then sets all four others. - The default is that all those dimensions are equal. They are set to: + The defaults: - * ``\fboxsep`` (i.e. a priori ``3pt``) for :rst:dir:`code-block`, - * ``5pt`` for :dudir:`topic` or contents_ directive, - * a special value for :dudir:`warning` and other "strong" admonitions, - which ensures a backward compatible behavior. + * all four ``3pt`` for :rst:dir:`code-block`, + * ``10pt``, ``7pt``, ``12pt``, ``7pt`` for :dudir:`topic` or + contents_ directive, + * ``6pt``, ``7pt``, ``6pt``, ``7pt`` for all "light" admonitions as well + as the :rst:dir:`seealso` and :rst:dir:`todo` directives. + * ``6pt``, ``6.5pt``, ``6pt``, ``6.5pt`` for the strong admonition types + except :dudir:`error` which uses horizontal padding of ``6.25pt``. - .. important:: + .. versionchanged:: 7.4.0 - Prior to 5.1.0 there was no separate customizability of - padding for warning-type boxes in PDF via LaTeX output. The sum of - padding and border-width (as set for example for :dudir:`warning` by - ``warningborder``, now also named ``div.warning_border-width``) was - kept to a certain constant value. This limited the border-width - to small values else the border could overlap the text contents. - This behavior is kept as default. + All defaults were changed, except for :rst:dir:`code-block`. Admonitions + are set-up so that left (or right) padding plus left (or right) + border-width add up always to ``7.5pt``, so contents align well + vertically across admonition types on same page in PDF. This is only a + property of defaults, not a constraint on possible user choices. - * the same padding behavior is obeyed per default for :dudir:`note` or - other "light" admonitions when using ``sphinxheavybox``. - | ``<prefix>_border-top-left-radius``, | ``<prefix>_border-top-right-radius``, | ``<prefix>_border-bottom-right-radius``, @@ -1272,11 +1271,19 @@ forget the underscore separating the prefix from the property names. its assigned value. Each key value can be either a single, or *two*, dimensions which are then space separated. - The default is that all four corners are either circular or straight, - with common radii: + The defaults: - * ``\fboxsep`` (i.e. a priori ``3pt``) for :rst:dir:`code-block` (since 6.0.0). - * ``0pt`` for all other directives; this means to use straight corners. + * ``3pt`` for :rst:dir:`code-block` (since 6.0.0) and all corners, + * ``12pt`` for the bottom right corner of :dudir:`topic`, other corners are + straight, + * all radii set to ``5pt`` for :dudir:`note`, :dudir:`hint` and + :dudir:`tip`, + * ``0pt``, i.e. straight corners for all other directives. + + .. versionchanged:: 7.4.0 + + :dudir:`topic` and :dudir:`note`\ -like admonitions acquire (at least one) + rounded corners. See a remark above about traps with spaces in LaTeX. - ``<prefix>_box-shadow`` is special in so far as it may be: @@ -1297,14 +1304,24 @@ forget the underscore separating the prefix from the property names. | ``<prefix>_TeXcolor``. These are colors. - The shadow color defaults in all cases to ``{rgb}{0,0,0}`` i.e. to black. + Since 6.0.0 the border and background colors of :rst:dir:`code-block`, + default respectively to ``{RGB}{32,32,32}`` (i.e. ``{HTML}{202020}``), and + ``{RGB}{242,242,242}`` (i.e. ``{gray}{0.95}`` or ``{HTML}{F2F2F2}``). + + At 7.4.0 other directives acquire non-black/white default border and + background colors. Here they are using ``xcolor`` hexadecimal notation + (which requires always 6 hexadecimal digits): - Since 6.0.0 the border color and background color of :rst:dir:`code-block`, - i.e. ``pre`` prefix, default respectively to ``{RGB}{32,32,32}`` and - ``{gray}{0.95}``. They previously defaulted to black, respectively white. + - ``{HTML}{F7F7F7}`` serves as background color to all. + - ``{HTML}{86989B}`` is border color of light admonitions (inclusive of + :rst:dir:`seealso` and :rst:dir:`todo`) as well as of :dudir:`topic` and + contents_ directives. + - ``{HTML}{940000}`` is border color or :dudir:`warning`-type admonitions, + except :dudir:`error` which uses ``{HTML}{B40000}``. - For all other types, the border color defaults to black and the background - color to white. + The only directives displaying a shadow per default are :dudir:`topic` and + contents_ (handled identically at LaTeX level) and their shadow color is + ``{HTML}{6C6C6C}``. For all others the default shadow color is black. The ``<prefix>_TeXcolor`` stands for the CSS property "color", i.e. it influences the text color of the contents. As for the three other options, @@ -1323,6 +1340,35 @@ forget the underscore separating the prefix from the property names. start of the contents; for admonitions, this happens after the heading which reproduces the admonition type. +The next keys, for admonitions only, were all three added at 7.4.0. The +default colors are the ones applying to the current HTML rendering of Sphinx +own docs at https://www.sphinx-doc.org. + +- ``div.<type>_title-background-TeXcolor``: the background color for the title. + + .. important:: + + The colored title-row is produced as a result of the Sphinx default + definitions for the various ``\sphinxstyle<type>title`` commands, see + :ref:`latex-macros`. Custom redefinitions of these commands are + possible, but to re-use the colors and the icon, it is needed to check in + Sphinx LaTeX source code how the default definitions are done. + +- ``div.<type>_title-foreground-TeXcolor``: the color to be used for the icon + (it applies only to the icon, not to the title of the admonition). + +- ``div.<type>_title-icon``: the LaTeX code responsible for producing the + icon. For example, the default for :dudir:`note` is + ``div.note_title-icon=\faIcon{info-circle}``. This uses a command from the + LaTeX ``fontawesome5`` package, which is loaded automatically if available. + + If neither ``fontawesome5`` nor fall-back ``fontawesome`` (for which the + associated command is ``\faicon``, not ``\faIcon``) are found, or if the + ``iconpackage`` key of :ref:`'sphinxsetup' <latexsphinxsetup>` is set to + load some other user-chosen package, or no package at all, all the + ``title-icons`` default to empty LaTeX code. It is up to user to employ + this interface to inject the icon (or anything else) into the PDF output. + .. note:: - All directives support ``box-decoration-break`` to be set to ``slice``. @@ -1519,16 +1565,30 @@ Macros ``\sphinxstyleliteralintitle``; ``\sphinxcode{#1}`` ``\sphinxstylecodecontinued``; ``{\footnotesize(#1)}}`` ``\sphinxstylecodecontinues``; ``{\footnotesize(#1)}}`` - ``\sphinxstylenotetitle``; ``\sphinxstrong{#1}<space>`` - ``\sphinxstylehinttitle``; *idem* - ``\sphinxstyleimportanttitle``; *idem* - ``\sphinxstyletiptitle``; *idem* - ``\sphinxstylewarningtitle``; *idem* - ``\sphinxstylecautiontitle``; *idem* - ``\sphinxstyleattentiontitle``; *idem* - ``\sphinxstyledangertitle``; *idem* - ``\sphinxstyleerrortitle``; *idem* - ``\sphinxstyleseealsotitle``; ``\sphinxstrong{#1}\par\nopagebreak`` + ``\sphinxstylenotetitle``; ``\sphinxdotitlerowwithicon{note}{#1}`` + ``\sphinxstylehinttitle``; ``\sphinxdotitlerowwithicon{hint}{#1}`` + ``\sphinxstyleimportanttitle``; *similar* + ``\sphinxstyletiptitle``; *similar* + ``\sphinxstylewarningtitle``; *similar* + ``\sphinxstylecautiontitle``; *similar* + ``\sphinxstyleattentiontitle``; *similar* + ``\sphinxstyledangertitle``; *similar* + ``\sphinxstyleerrortitle``; *similar* + ``\sphinxstyleseealsotitle``; *similar* + ``\sphinxstyletodotitle``; *similar* + + .. note:: + + To let this table fit on the page width in PDF output we have lied a bit + and the actual definition of ``\sphinxstylenotetitle`` is: + + .. code-block:: latex + + \newcommand\sphinxstylenotetitle[1]% + {\sphinxdotitlerowwithicon{note}{\sphinxremovefinalcolon{#1}}} + + The same remark applies to all other similar commands associated with + admonitions. .. versionadded:: 1.5 These macros were formerly hard-coded as non customizable ``\texttt``, @@ -1547,23 +1607,16 @@ Macros .. versionadded:: 6.2.0 ``\sphinxstylenotetitle`` et al. The ``#1`` is the localized name of the directive, with a final colon. Wrap it as ``\sphinxremovefinalcolon{#1}`` - if this final colon is to be removed. Examples: + if this final colon is to be removed. - .. code-block:: latex + .. versionadded:: 7.4.0 The ``\sphinxdotitlerowwithicon`` LaTeX command, + whose first argument is the admonition type, so that it can recover + the associated colours and icon for the title row, and the second + argument gets typeset after the icon. - \renewcommand\sphinxstylewarningtitle[1]{% - \underline{\textbf{\sphinxremovefinalcolon{#1}}}\par - } - \renewcommand{\sphinxstylenotetitle}[1]{% - \textit{\textbf{\sphinxremovefinalcolon{#1}}}\par\nobreak - % LaTeX syntax is complex and we would be better off using \hrule. - {\parskip0pt\noindent}% - \raisebox{1ex}% - {\makebox[\linewidth]{\textcolor{sphinxnoteBorderColor}{\dotfill}}} - % It is complex to obtain nice vertical spacing for both a paragraph - % or a list following up; this set-up is better for a paragraph next. - \par\vskip-\parskip - } + .. todo:: The fact that we must employ ``\sphinxremovefinalcolon`` is a + legacy artefact from old ill-designed Sphinx LaTeX writer, + which postfixes (still today) the title with a colon automatically. - ``\sphinxtableofcontents``: A wrapper (defined differently in :file:`sphinxhowto.cls` and in :file:`sphinxmanual.cls`) of standard @@ -1743,6 +1796,11 @@ Environments Colon made part of the mark-up rather than being inserted by the environment for coherence with how admonitions are handled generally. +- Environment for the :rst:dir:`todo` directive: ``sphinxtodo``. + It takes one argument which will be the localized string ``Todo`` + followed with a colon. + + .. versionadded:: 7.4.0 - The contents_ directive (with ``:local:`` option) and the :dudir:`topic` directive are implemented by environment ``sphinxShadowBox``. @@ -1818,7 +1876,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 @@ -1826,16 +1884,21 @@ Miscellany .. hint:: As an experimental feature, Sphinx can use user-defined template file for - LaTeX source if you have a file named ``_templates/latex.tex_t`` in your + LaTeX source if you have a file named ``_templates/latex.tex.jinja`` in your project. - Additional files ``longtable.tex_t``, ``tabulary.tex_t`` and - ``tabular.tex_t`` can be added to ``_templates/`` to configure some aspects - of table rendering (such as the caption position). + Additional files ``longtable.tex.jinja``, ``tabulary.tex.jinja`` and + ``tabular.tex.jinja`` can be added to ``_templates/`` to configure some + aspects of table rendering (such as the caption position). .. versionadded:: 1.6 currently all template variables are unstable and undocumented. + .. versionchanged:: 7.4 + Added support for the ``.jinja`` file extension, which is preferred. + The old file names remain supported. + (``latex.tex_t``, ``longtable.tex_t``, ``tabulary.tex_t``, and ``tabular.tex_t``) + .. raw:: latex \endgroup diff --git a/doc/man/sphinx-apidoc.rst b/doc/man/sphinx-apidoc.rst index efc8230..a023b2d 100644 --- a/doc/man/sphinx-apidoc.rst +++ b/doc/man/sphinx-apidoc.rst @@ -54,7 +54,7 @@ Options .. option:: -n, --dry-run - Do not create any files. + Do not create or remove any files. .. option:: -s <suffix> @@ -73,6 +73,12 @@ Options Do not create a table of contents file. Ignored when :option:`--full` is provided. +.. option:: --remove-old + + Remove existing files in the output directory + that are not created anymore. + Not compatible with :option:`--full`. + .. option:: -F, --full Generate a full Sphinx project (``conf.py``, ``Makefile`` etc.) using @@ -142,15 +148,15 @@ These options are used when :option:`--full` is specified: sphinx project files generated by apidoc. Following Jinja2 template files are allowed: - * ``module.rst_t`` - * ``package.rst_t`` - * ``toc.rst_t`` - * ``root_doc.rst_t`` - * ``conf.py_t`` - * ``Makefile_t`` - * ``Makefile.new_t`` - * ``make.bat_t`` - * ``make.bat.new_t`` + * ``module.rst.jinja`` + * ``package.rst.jinja`` + * ``toc.rst.jinja`` + * ``root_doc.rst.jinja`` + * ``conf.py.jinja`` + * ``Makefile.jinja`` + * ``Makefile.new.jinja`` + * ``make.bat.jinja`` + * ``make.bat.new.jinja`` In detail, please refer the system template files Sphinx provides. (``sphinx/templates/apidoc`` and ``sphinx/templates/quickstart``) diff --git a/doc/man/sphinx-autogen.rst b/doc/man/sphinx-autogen.rst index caeb44b..43cc369 100644 --- a/doc/man/sphinx-autogen.rst +++ b/doc/man/sphinx-autogen.rst @@ -43,6 +43,11 @@ Options Document exactly the members in a module's ``__all__`` attribute. +.. option:: --remove-old + + Remove existing files in the output directory + that are not generated anymore. + Example ------- diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst index 8be2780..ac2e7ca 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 <tags>` for further detail. .. versionadded:: 0.6 @@ -126,7 +128,7 @@ Options Distribute the build over *N* processes in parallel, to make building on multiprocessor machines more effective. Note that not all parts and not all builders of Sphinx can be parallelized. If ``auto`` argument is given, - Sphinx uses the number of CPUs as *N*. + Sphinx uses the number of CPUs as *N*. Defaults to 1. .. versionadded:: 1.2 This option should be considered *experimental*. @@ -192,7 +194,7 @@ Options .. option:: -n, --nitpicky - Run in nit-picky mode. Currently, this generates warnings for all missing + Run in nitpicky mode. Currently, this generates warnings for all missing references. See the config value :confval:`nitpick_ignore` for a way to exclude some references as "known missing". diff --git a/doc/man/sphinx-quickstart.rst b/doc/man/sphinx-quickstart.rst index cc6673d..a8522ec 100644 --- a/doc/man/sphinx-quickstart.rst +++ b/doc/man/sphinx-quickstart.rst @@ -152,12 +152,12 @@ Options sphinx project files generated by quickstart. Following Jinja2 template files are allowed: - * ``root_doc.rst_t`` - * ``conf.py_t`` - * ``Makefile_t`` - * ``Makefile.new_t`` - * ``make.bat_t`` - * ``make.bat.new_t`` + * ``root_doc.rst.jinja`` + * ``conf.py.jinja`` + * ``Makefile.jinja`` + * ``Makefile.new.jinja`` + * ``make.bat.jinja`` + * ``make.bat.new.jinja`` In detail, please refer the system template files Sphinx provides. (``sphinx/templates/quickstart``) diff --git a/doc/support.rst b/doc/support.rst index 0d349a0..69f800d 100644 --- a/doc/support.rst +++ b/doc/support.rst @@ -1,20 +1,29 @@ +.. _support-index: + Get support =========== -For questions or to report problems with Sphinx, join the `sphinx-users`_ -mailing list on Google Groups, come to the ``#sphinx-doc`` channel on -`libera.chat`_, or open an issue at the tracker_. +For questions or to report problems with Sphinx: + +- Please verify that your question does not exist on StackOverflow_ + (with the tag ``python-sphinx``) +- open a topic at the `Github discussions`_ page, +- open an issue at the `Github issues`_ page, +- or join the `sphinx-users`_ mailing list on Google Groups, +.. _StackOverflow: https://stackoverflow.com/questions/tagged/python-sphinx .. _sphinx-users: https://groups.google.com/group/sphinx-users -.. _libera.chat: https://web.libera.chat/?channel=#sphinx-doc -.. _tracker: https://github.com/sphinx-doc/sphinx/issues +.. _Github discussions: https://github.com/sphinx-doc/sphinx/discussions +.. _Github issues: https://github.com/sphinx-doc/sphinx/issues + +Examples of other projects using Sphinx can be found in the +:doc:`examples page <examples>`. -Examples of other projects using Sphinx can be found in the :doc:`examples page -<examples>`. A useful tutorial_ has been written by the matplotlib developers. +See also the guide by ReadTheDocs_ on how to get started with Sphinx. -.. _tutorial: https://matplotlib.sourceforge.net/sampledoc/ +.. _Readthedocs: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html -There is a translation team in Transifex_ of this documentation, thanks to the -Sphinx document translators. +There is a translation team in Transifex_ of this documentation, +thanks to the Sphinx document translators. .. _Transifex: https://www.transifex.com/sphinx-doc/sphinx-doc/dashboard/ diff --git a/doc/tutorial/automatic-doc-generation.rst b/doc/tutorial/automatic-doc-generation.rst index 8d9c9c9..db880d0 100644 --- a/doc/tutorial/automatic-doc-generation.rst +++ b/doc/tutorial/automatic-doc-generation.rst @@ -142,7 +142,7 @@ contain two new pages: - ``api.html``, corresponding to ``docs/source/api.rst`` and containing a table with the objects you included in the ``autosummary`` directive (in this case, only one). -- ``generated/lumache.html``, corresponding to a newly created reST file +- ``generated/lumache.html``, corresponding to a newly created reStructuredText file ``generated/lumache.rst`` and containing a summary of members of the module, in this case one function and one exception. diff --git a/doc/tutorial/deploying.rst b/doc/tutorial/deploying.rst index 6b7913f..c269593 100644 --- a/doc/tutorial/deploying.rst +++ b/doc/tutorial/deploying.rst @@ -159,7 +159,7 @@ way of getting started is to follow :doc:`the RTD tutorial <readthedocs:tutorial/index>`, which is loosely based on this one. You can publish your sources on GitHub as explained :ref:`in the previous section <publishing-sources>`, then skip directly to -:ref:`readthedocs:tutorial/index:Sign up for Read the Docs`. +:ref:`readthedocs:tutorial/index:Creating a Read the Docs account`. If you choose GitLab instead, the process is similar. GitHub Pages diff --git a/doc/tutorial/describing-code.rst b/doc/tutorial/describing-code.rst index 16feb2a..e8c6a80 100644 --- a/doc/tutorial/describing-code.rst +++ b/doc/tutorial/describing-code.rst @@ -75,7 +75,7 @@ Cross-referencing Python objects By default, most of these directives generate entities that can be cross-referenced from any part of the documentation by using -:ref:`a corresponding role <python-roles>`. For the case of functions, +:ref:`a corresponding role <python-xref-roles>`. For the case of functions, you can use :rst:role:`py:func` for that, as follows: .. code-block:: rst diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index d7f4861..54f4c72 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -1,8 +1,7 @@ .. _tutorial: -================================== -Tutorial: Build your first project -================================== +Build your first project +======================== In this tutorial you will build a simple documentation project using Sphinx, and view it in your browser as HTML. The project will include narrative, diff --git a/doc/tutorial/narrative-documentation.rst b/doc/tutorial/narrative-documentation.rst index a81204d..0c41392 100644 --- a/doc/tutorial/narrative-documentation.rst +++ b/doc/tutorial/narrative-documentation.rst @@ -85,7 +85,7 @@ introduction paragraph in ``index.rst``: Check out the :doc:`usage` section for further information. -The :rst:role:`doc` :ref:`role <rst-roles-alt>` you used automatically +The :rst:role:`doc` :ref:`role <rst-roles>` you used automatically references a specific document in the project, in this case the ``usage.rst`` you created earlier. diff --git a/doc/usage/advanced/intl.rst b/doc/usage/advanced/intl.rst index e858c3c..8f16259 100644 --- a/doc/usage/advanced/intl.rst +++ b/doc/usage/advanced/intl.rst @@ -27,7 +27,7 @@ Sphinx uses these facilities to translate whole documents. Initially project maintainers have to collect all translatable strings (also referred to as *messages*) to make them known to translators. Sphinx extracts -these through invocation of ``sphinx-build -M gettext``. +these through invocation of :command:`sphinx-build -M gettext`. Every single element in the doctree will end up in a single message which results in lists being equally split into different chunks while large @@ -51,13 +51,13 @@ through :program:`msgfmt` for efficiency reasons. If you make these files discoverable with :confval:`locale_dirs` for your :confval:`language`, Sphinx will pick them up automatically. -An example: you have a document ``usage.rst`` in your Sphinx project. The -*gettext* builder will put its messages into ``usage.pot``. Imagine you have -Spanish translations [2]_ stored in ``usage.po`` --- for your builds to +An example: you have a document :file:`usage.rst` in your Sphinx project. The +*gettext* builder will put its messages into :file:`usage.pot`. Imagine you have +Spanish translations [2]_ stored in :file:`usage.po` --- for your builds to be translated you need to follow these instructions: * Compile your message catalog to a locale directory, say ``locale``, so it - ends up in ``./locale/es/LC_MESSAGES/usage.mo`` in your source directory + ends up in :file:`./locale/es/LC_MESSAGES/usage.mo` in your source directory (where ``es`` is the language code for Spanish.) :: msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo" @@ -101,7 +101,7 @@ section describe an easy way to translate with *sphinx-intl*. $ pip install sphinx-intl -#. Add configurations to ``conf.py``. +#. Add configurations to :file:`conf.py`. :: @@ -137,7 +137,7 @@ section describe an easy way to translate with *sphinx-intl*. #. Translate po files. As noted above, these are located in the ``./locale/<lang>/LC_MESSAGES`` - directory. An example of one such file, from Sphinx, ``builders.po``, is + directory. An example of one such file, from Sphinx, :file:`builders.po`, is given below. .. code-block:: po @@ -160,12 +160,12 @@ section describe an easy way to translate with *sphinx-intl*. "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE " "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE." - Please be careful not to break reST notation. Most po-editors will help you - with that. + Please be careful not to break reStructuredText notation. + Most po-editors will help you with that. #. Build translated document. - You need a :confval:`language` parameter in ``conf.py`` or you may also + You need a :confval:`language` parameter in :file:`conf.py` or you may also specify the parameter on the command line. For BSD/GNU make, run: @@ -218,23 +218,27 @@ Using Transifex service for team translation -------------------------------------------- Transifex_ is one of several services that allow collaborative translation via a -web interface. It has a nifty Python-based command line client that makes it +web interface. It has a nifty Go-based command line client that makes it easy to fetch and push translations. .. TODO: why use transifex? -#. Install `transifex-client`_. +#. Install the `Transifex CLI tool`_. - You need :command:`tx` command to upload resources (pot files). + You need the :command:`tx` command line tool for uploading resources (pot files). + The official installation process place the :file:`tx` binary file in + the current directory along with a README and a LICENSE file, and adds + the current directory to ``$PATH``. .. code-block:: console - $ pip install transifex-client + $ curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash .. seealso:: `Transifex Client documentation`_ -#. Create your Transifex_ account and create new project for your document. +#. Create your Transifex_ account and create a new project and an organization + for your document. Currently, Transifex does not allow for a translation project to have more than one version of the document, so you'd better include a version number in @@ -242,45 +246,75 @@ easy to fetch and push translations. For example: + :Organization ID: ``sphinx-document`` :Project ID: ``sphinx-document-test_1_0`` :Project URL: ``https://www.transifex.com/projects/p/sphinx-document-test_1_0/`` -#. Create config files for :command:`tx` command. +#. Create an API token to be used in the command-line. - This process will create ``.tx/config`` in the current directory, as well as - a ``~/.transifexrc`` file that includes auth information. + Go to your `Transifex API token`_ page and generate a token. + Copy the generated token now, as you will not be able to see it again later. + +#. Set your Transifex API token in the user configuration file + :file:`$HOME/.transifexrc`. + + .. code-block:: ini + + [https://app.transifex.com] + rest_hostname = https://rest.api.transifex.com + token = paste_your_api_token_here + +#. Alternatively, you can store your Transifex API token as the environment variable + ``TX_TOKEN``, which is recognized and used by :command:`tx`. + + .. code-block:: console + + $ export TX_TOKEN=paste_your_api_token_here + +#. Create the project's config file for :command:`tx` command. + + This process will create ``.tx/config`` in the current directory. .. code-block:: console + $ cd /your/document/root $ tx init - Creating .tx folder... - Transifex instance [https://www.transifex.com]: - ... - Please enter your transifex username: <transifex-username> - Password: <transifex-password> - ... - Done. + + Successful creation of '.tx/config' file #. Upload pot files to Transifex service. - Register pot files to ``.tx/config`` file: + Register pot files to ``.tx/config`` file using + :command:`sphinx-intl update-txconfig-resources`, adjusting + ``--pot-dir`` value to your project's pot files' directory: .. code-block:: console $ cd /your/document/root $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \ - --transifex-project-name sphinx-document-test_1_0 + --transifex-organization-name=sphinx-document \ + --transifex-project-name=sphinx-document-test_1_0 + + You can use the ``SPHINXINTL_TRANSIFEX_ORGANIZATION_NAME`` and + ``SPHINXINTL_TRANSIFEX_PROJECT_NAME`` environment variables + instead of the respective command line arguments. + + .. seealso:: `sphinx-intl update-txconfig-resources documentation`_ and upload pot files: .. code-block:: console $ tx push -s - Pushing translations for resource sphinx-document-test_1_0.builders: - Pushing source file (locale/pot/builders.pot) - Resource does not exist. Creating... - ... - Done. + # Getting info about resources + + sphinx-document-test_1_0.builders - Getting info + sphinx-document-test_1_0.builders - Done + + # Pushing source files + + sphinx-document-test_1_0.builders - Uploading file + sphinx-document-test_1_0.builders - Done #. Forward the translation on Transifex. @@ -295,12 +329,18 @@ easy to fetch and push translations. $ cd /your/document/root $ tx pull -l de - Pulling translations for resource sphinx-document-test_1_0.builders (...) - -> de: locale/de/LC_MESSAGES/builders.po - ... - Done. + # Getting info about resources + + sphinx-document-test_1_0.builders - Getting info + sphinx-document-test_1_0.builders - Done + + # Pulling files + + sphinx-document-test_1_0.builders [de] - Pulling file + sphinx-document-test_1_0.builders [de] - Creating download job + sphinx-document-test_1_0.builders [de] - Done - Invoke :command:`make html` (for BSD/GNU make): + Invoke :command:`make html` (for BSD/GNU make) passing the language code: .. code-block:: console @@ -338,7 +378,8 @@ There is a `sphinx translation page`_ for Sphinx (master) documentation. 4. Wait acceptance by Transifex sphinx translation maintainers. 5. (After acceptance) Translate on Transifex. -Detail is here: https://docs.transifex.com/getting-started-1/translators +Detail is here: +https://help.transifex.com/en/articles/6248698-getting-started-as-a-translator Translation progress and statistics @@ -364,9 +405,11 @@ percentage of nodes that have been translated on a per-document basis. for details on that software suite. .. [2] Because nobody expects the Spanish Inquisition! -.. _`transifex-client`: https://pypi.org/project/transifex-client/ +.. _`Transifex CLI tool`: https://github.com/transifex/cli/ .. _`sphinx-intl`: https://pypi.org/project/sphinx-intl/ -.. _Transifex: https://www.transifex.com/ +.. _Transifex: https://app.transifex.com/ .. _Weblate's documentation: https://docs.weblate.org/en/latest/devel/sphinx.html -.. _`sphinx translation page`: https://www.transifex.com/sphinx-doc/sphinx-doc/ -.. _`Transifex Client documentation`: https://docs.transifex.com/client/introduction/ +.. _`sphinx translation page`: https://app.transifex.com/sphinx-doc/sphinx-doc/ +.. _`Transifex Client documentation`: https://developers.transifex.com/docs/using-the-client +.. _`Transifex API token`: https://app.transifex.com/user/settings/api/ +.. _`sphinx-intl update-txconfig-resources documentation`: https://sphinx-intl.readthedocs.io/en/master/refs.html#sphinx-intl-update-txconfig-resources diff --git a/doc/usage/advanced/websupport/quickstart.rst b/doc/usage/advanced/websupport/quickstart.rst index e7c2b51..b75c617 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/builders/index.rst b/doc/usage/builders/index.rst index 9c538ee..e293399 100644 --- a/doc/usage/builders/index.rst +++ b/doc/usage/builders/index.rst @@ -71,9 +71,9 @@ The most common builders are: .. class:: StandaloneHTMLBuilder This is the standard HTML builder. Its output is a directory with HTML - files, complete with style sheets and optionally the reST sources. There are - quite a few configuration values that customize the output of this builder, - see the chapter :ref:`html-options` for details. + files, complete with style sheets and optionally the reStructuredText sources. + There are quite a few configuration values that customize + the output of this builder, see the chapter :ref:`html-options` for details. .. autoattribute:: name @@ -237,6 +237,8 @@ The most common builders are: * ``texlive-latex-recommended`` * ``texlive-fonts-recommended`` + * ``texlive-fonts-extra`` (needed for ``fontawesome5``, see the 7.4.0 + change notice below) * ``tex-gyre`` (if :confval:`latex_engine` left to default) * ``texlive-latex-extra`` * ``latexmk`` @@ -244,6 +246,12 @@ The most common builders are: .. versionchanged:: 4.0.0 TeX Gyre fonts now required for ``'pdflatex'`` engine (default). + .. versionchanged:: 7.4.0 + LaTeX package ``xcolor`` is now required (it is part of Ubuntu + ``texlive-latex-recommended`` anyhow). The LaTeX package + ``fontawesome5`` is recommended. See the :ref:`'sphinxsetup' + <latexsphinxsetup>` ``iconpackage`` key for more. + Additional packages are needed in some circumstances: * ``texlive-lang-cyrillic`` for Cyrillic (and also then @@ -298,9 +306,9 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details. .. module:: sphinx.builders.text .. class:: TextBuilder - This builder produces a text file for each reST file -- this is almost the - same as the reST source, but with much of the markup stripped for better - readability. + This builder produces a text file for each reStructuredText file. + This is almost the same as the reStructuredText source, + but with much of the markup stripped for better readability. .. autoattribute:: name @@ -540,8 +548,8 @@ Serialization builder details ----------------------------- All serialization builders outputs one file per source file and a few special -files. They also copy the reST source files in the directory ``_sources`` -under the output directory. +files. They also copy the reStructuredText source files +to the ``_sources`` directory under the output directory. The :class:`.PickleHTMLBuilder` is a builtin subclass that implements the pickle serialization interface. diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index a27107f..cd56674 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,1050 +32,1399 @@ 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. +* If not otherwise documented, values must be strings, + and their default is the empty string. + +* 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. + +.. _glob-style patterns: + +* 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. + +.. tip:: + + 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. + + 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. -* 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. + 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. -* 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. +.. _conf-tags: -* 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. +Project tags +============ - .. _conf-tags: +There is a special object named ``tags`` available in the config file, +which exposes the :ref:`project tags <tags>`. +Tags are defined either via the +:option:`--tag <sphinx-build --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`. -* There is a special object named ``tags`` available in the config file. - It can be used to query and change the tags (see :ref:`tags`). Use - ``tags.has('tag')`` to query, ``tags.add('tag')`` and ``tags.remove('tag')`` - to change. Only tags set via the ``-t`` command-line option or via - ``tags.add('tag')`` can be queried using ``tags.has('tag')``. - Note that the current builder tag is not available in ``conf.py``, as it is - created *after* the builder is initialized. +It can be used to query and change the defined tags as follows: +* 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')`. Project information -------------------- +=================== .. confval:: project + :type: :code-py:`str` + :default: :code-py:`'Project name not set'` The documented project's name. + Example: + + .. code-block:: python + + project = 'Thermidor' .. confval:: author + :type: :code-py:`str` + :default: :code-py:`'Author name not set'` - The author name(s) of the document. The default value is ``'unknown'``. + The project's author(s). + Example: + + .. code-block:: python + + author = 'Joe Bloggs' .. confval:: copyright + project_copyright + :type: :code-py:`str | Sequence[str]` + :default: :code-py:`''` + + A copyright statement. + Permitted styles are as follows, where 'YYYY' represents a four-digit year. - A copyright statement in the style ``'2008, Author Name'``. + * :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'` + + .. versionadded:: 3.5 + The :code-py:`project_copyright` alias. .. 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 +.. confval:: version + :type: :code-py:`str` + :default: :code-py:`''` - An alias of :confval:`copyright`. + The major project version, used as the replacement for the :code-rst:`|version|` + :ref:`default substitution <default-substitutions>`. - .. versionadded:: 3.5 + This may be something like :code-py:`version = '4.2'`. + The full project version is defined in :confval:`release`. -.. confval:: version - - The major project version, used as the replacement for ``|version|``. For - example, for the Python documentation, this may be something like ``2.6``. + 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:: release + :type: :code-py:`str` + :default: :code-py:`''` + + The full project version, used as the replacement for the :code-rst:`|release|` + :ref:`default substitution <default-substitutions>`, and + e.g. in the HTML templates. - 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``. + This may be something like :code-py:`release = '4.2.1b0'`. + The major (short) project version is defined in :confval:`version`. - If you don't need the separation provided between :confval:`version` and - :confval:`release`, just set them both to the same value. + 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. General configuration ---------------------- +===================== + +.. confval:: needs_sphinx + :type: :code-py:`str` + :default: :code-py:`''` + + 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. + + .. versionadded:: 1.0 + + .. versionchanged:: 1.4 + Allow a ``'major.minor.micro'`` version string. .. confval:: extensions + :type: :code-py:`list[str]` + :default: :code-py:`[]` - A list of strings that are module names of :doc:`extensions - <extensions/index>`. These can be extensions coming with Sphinx (named - ``sphinx.ext.*``) or custom ones. + A list of strings that are module names of + :doc:`Sphinx extensions <extensions/index>`. + These can be extensions bundled with Sphinx (named ``sphinx.ext.*``) + or custom first-party or third-party extensions. - 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:: + To use a third-party extension, you must ensure that it is installed + and include it in the :code-py:`extensions` list, like so: - import sys, os + .. code-block:: python - sys.path.append(os.path.abspath('sphinxext')) + extensions = [ + ... + 'numpydoc', + ] - extensions = ['extname'] + 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. - That way, you can load an extension called ``extname`` from the subdirectory - ``sphinxext``. + 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: - The configuration file itself can be an extension; for that, you only need - to provide a :func:`setup` function in it. + .. code-block:: python -.. confval:: source_suffix + import os, sys; sys.path.append(os.path.abspath('sphinxext')) - 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:: + extensions = [ + ... + 'extname', + ] - source_suffix = { - '.rst': 'restructuredtext', - '.txt': 'restructuredtext', - '.md': 'markdown', + The directory structure illustrated above would look like this: + + .. code-block:: none + + <project directory>/ + ├── conf.py + └── sphinxext/ + └── extname.py + + +.. 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: + + .. code-block:: python + + needs_extensions = { + 'sphinxcontrib.something': '1.5', } - 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 requires that the extension declares its version + in the :code-py:`setup()` function. See :ref:`dev-extensions` for further details. - The value may also be a list of file extensions: then Sphinx will consider - that they all map to the ``'restructuredtext'`` file type. + .. versionadded:: 1.3 - Default is ``{'.rst': 'restructuredtext'}``. +.. 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 + <https://manpages.debian.org/man(1)>. + The patterns available are: + + ``page`` + The manual page (``man``) + ``section`` + The manual section (``1``) + ``path`` + The original manual page and section specified (``man(1)``) - .. note:: file extensions have to start with a dot (e.g. ``.rst``). + This also supports manpages specified as ``man.1``. - .. versionchanged:: 1.3 - Can now be a list of extensions. + .. code-block:: python - .. versionchanged:: 1.8 - Support file type mapping + # 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}' -.. confval:: source_encoding + .. versionadded:: 1.7 - The encoding of all reST source files. The recommended encoding, and the - default value, is ``'utf-8-sig'``. +.. confval:: today + today_fmt - .. versionadded:: 0.5 - Previously, Sphinx accepted only UTF-8 encoded sources. + These values determine how to format the current date, + used as the replacement for the :code-rst:`|today|` + :ref:`default substitution <default-substitutions>`. + + * 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:: source_parsers + 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). - If given, a dictionary of parser classes for different source suffices. The - keys are the suffix, the values can be either a class or a string giving a - fully-qualified name of a parser class. The parser class can be either - ``docutils.parsers.Parser`` or :class:`sphinx.parsers.Parser`. Files with a - suffix that is not in the dictionary will be parsed with the default - reStructuredText parser. - For example:: +Options for figure numbering +---------------------------- - source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'} +.. confval:: numfig + :type: :code-py:`bool` + :default: :code-py:`False` + + 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. .. note:: - Refer to :doc:`/usage/markdown` for more information on using Markdown - with Sphinx. + The LaTeX builder always assigns numbers whether this option is enabled + or not. .. versionadded:: 1.3 - .. deprecated:: 1.8 - Now Sphinx provides an API :meth:`.Sphinx.add_source_parser` to register - a source parser. Please use it instead. +.. confval:: numfig_format + :type: :code-py:`dict[str, str]` + :default: :code-py:`{}` -.. confval:: master_doc + 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. - Same as :confval:`root_doc`. + The defaults are: - .. versionchanged:: 4.0 - Renamed ``master_doc`` to ``root_doc``. + .. code-block:: python -.. confval:: root_doc + numfig_format = { + 'code-block': 'Listing %s', + 'figure': 'Fig. %s', + 'section': 'Section', + 'table': 'Table %s', + } - The document name of the "root" document, that is, the document that - contains the root :rst:dir:`toctree` directive. Default is ``'index'``. + .. versionadded:: 1.3 - .. versionchanged:: 2.0 - The default is changed to ``'index'`` from ``'contents'``. - .. versionchanged:: 4.0 - Renamed ``root_doc`` from ``master_doc``. +.. 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. -.. confval:: exclude_patterns + .. versionadded:: 1.3 - 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. + .. versionchanged:: 1.7 + The LaTeX builder obeys this setting + if :confval:`numfig` is set to :code-py:`True`. - 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 +Options for highlighting +------------------------ - :confval:`exclude_patterns` is also consulted when looking for static files - in :confval:`html_static_path` and :confval:`html_extra_path`. +.. confval:: highlight_language + :type: :code-py:`str` + :default: :code-py:`'default'` - .. versionadded:: 1.0 + The default language to highlight source code in. + The default is :code-py:`'default'`, + which suppresses warnings if highlighting as Python code fails. -.. confval:: include_patterns + The value should be a valid Pygments lexer name, see + :ref:`code-examples` for more 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:: 0.5 - Example patterns: + .. versionchanged:: 1.4 + The default is now :code-py:`'default'`. - - ``'**'`` -- 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) +.. confval:: highlight_options + :type: :code-py:`dict[str, dict[str, Any]]` + :default: :code-py:`{}` - .. versionadded:: 5.1 + A dictionary that maps Pygments lexer names to their options. + These are lexer-specific; for the options understood by each, + see the `Pygments documentation <https://pygments.org/docs/lexers>`_. -.. confval:: templates_path + Example: - 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. + .. code-block:: python - .. versionchanged:: 1.3 - As these files are not meant to be built, they are automatically added to - :confval:`exclude_patterns`. + highlight_options = { + 'default': {'stripall': True}, + 'php': {'startinline': True}, + } -.. confval:: template_bridge + .. versionadded:: 1.3 + .. versionchanged:: 3.5 - 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.) + Allow configuring highlight options for multiple lexers. -.. confval:: rst_epilog +.. confval:: pygments_style + :type: :code-py:`str` + :default: :code-py:`'sphinx'` - .. index:: pair: global; substitutions + 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. - 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:: + .. versionchanged:: 0.3 + If the value is a fully-qualified name of a custom Pygments style class, + this is then used as custom style. - rst_epilog = """ - .. |psf| replace:: Python Software Foundation - """ - .. versionadded:: 0.6 +Options for HTTP requests +------------------------- -.. confval:: rst_prolog +.. confval:: tls_verify + :type: :code-py:`bool` + :default: :code-py:`True` - .. index:: pair: global; substitutions + If True, Sphinx verifies server certificates. - 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.5 - rst_prolog = """ - .. |psf| replace:: Python Software Foundation - """ +.. confval:: tls_cacerts + :type: :code-py:`str | dict[str, str]` + :default: :code-py:`''` - .. versionadded:: 1.0 + 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. -.. confval:: primary_domain + .. versionadded:: 1.5 - .. index:: default; domain - primary; domain + .. tip:: - The name of the default :doc:`domain </usage/domains/index>`. - 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"). + 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. - .. versionadded:: 1.0 + .. _requests: https://requests.readthedocs.io/ -.. confval:: default_role +.. 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'` - .. index:: default; role + Set the User-Agent used by Sphinx for HTTP requests. - 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. + .. versionadded:: 2.3 - The default role can always be set within individual documents using the - standard reST :dudir:`default-role` directive. - .. versionadded:: 0.4 +.. _intl-options: -.. confval:: keep_warnings +Options for internationalisation +-------------------------------- - 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. +These options influence Sphinx's *Native Language Support*. +See the documentation on :ref:`intl` for details. - The default is ``False``, the pre-0.5 behavior was to always keep them. +.. 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:: 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``. - - .. versionadded:: 7.3.0 + .. versionchanged:: 1.4 + Support figure substitution -.. confval:: suppress_warnings + .. versionchanged:: 5.0 + The default is now :code-py:`'en'` (previously :code-py:`None`). - A list of warning types to suppress arbitrary warning messages. + Currently supported languages by Sphinx are: - Sphinx core supports following warning types: + * ``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 - * ``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`` +.. confval:: locale_dirs + :type: :code-py:`list[str]` + :default: :code-py:`['locale']` - Extensions can also define their own warning types. - Those defined by the first-party ``sphinx.ext`` extensions are: + 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. - * ``autodoc`` - * ``autodoc.import_object`` - * ``autosectionlabel.<document name>`` - * ``autosummary`` - * ``intersphinx.external`` + 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`. - You can choose from these types. You can also give only the first - component to exclude all warnings attached to it. + .. note:: + The :option:`-v option to sphinx-build <sphinx-build -v>` + is useful to check the :confval:`!locale_dirs` setting is working as expected. + If the message catalog directory not found, debug messages are emitted. - .. versionadded:: 1.4 + .. versionadded:: 0.5 .. versionchanged:: 1.5 + Use ``locales`` directory as a default value - Added ``misc.highlighting_failure`` +.. confval:: gettext_allow_fuzzy_translations + :type: :code-py:`bool` + :default: :code-py:`False` - .. versionchanged:: 1.5.1 + If True, "fuzzy" messages in the message catalogs are used for translation. - Added ``epub.unknown_project_files`` + .. versionadded:: 4.3 - .. versionchanged:: 1.6 +.. 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``. - Added ``ref.footnote`` + .. versionadded:: 1.1 - .. versionchanged:: 2.1 + .. versionchanged:: 3.3 + Allow string values. - Added ``autosectionlabel.<document name>`` +.. confval:: gettext_uuid + :type: :code-py:`bool` + :default: :code-py:`False` - .. versionchanged:: 3.3.0 + If :code-py:`True`, Sphinx generates UUID information + for version tracking in message catalogs. + It is used to: - Added ``epub.duplicated_toc_entry`` + * 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.) - .. versionchanged:: 4.3 + .. tip:: + If you want to accelerate the calculation, + you can use a third-party package (Levenshtein_) by running + :command:`pip install levenshtein`. - Added ``toc.excluded`` and ``toc.not_readable`` + .. _Levenshtein: https://pypi.org/project/Levenshtein/ - .. versionadded:: 4.5 + .. versionadded:: 1.3 - Added ``i18n.inconsistent_references`` +.. confval:: gettext_location + :type: :code-py:`bool` + :default: :code-py:`True` - .. versionadded:: 7.1 + If :code-py:`True`, Sphinx generates location information + for messages in message catalogs. - Added ``index`` warning type. + .. versionadded:: 1.3 - .. versionadded:: 7.3 +.. confval:: gettext_auto_build + :type: :code-py:`bool` + :default: :code-py:`True` - Added ``config.cache`` warning type. + If :code-py:`True`, Sphinx builds a ``.mo`` file + for each translation catalog file. -.. confval:: needs_sphinx + .. versionadded:: 1.3 - 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:: gettext_additional_targets + :type: :code-py:`set[str] | Sequence[str]` + :default: :code-py:`[]` - .. versionadded:: 1.0 + Enable ``gettext`` translation for certain element types. + Example: - .. versionchanged:: 1.4 - also accepts micro version string + .. code-block:: python -.. confval:: needs_extensions + gettext_additional_targets = {'literal-block', 'image'} - 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. + The following element types are supported: - This requires that the extension specifies its version to Sphinx (see - :ref:`dev-extensions` for how to do that). + * :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.3 + .. versionchanged:: 4.0 + The alt text for images is translated by default. + .. versionchanged:: 7.4 + Permit and prefer a set type. -.. confval:: manpages_url +.. confval:: figure_language_filename + :type: :code-py:`str` + :default: :code-py:`'{root}.{language}{ext}'` - 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 - <https://manpages.debian.org/man(1)>. The patterns available are: + The filename format for language-specific figures. + The available format tokens are: - * ``page`` - the manual page (``man``) - * ``section`` - the manual section (``1``) - * ``path`` - the original manual page and section specified (``man(1)``) + * ``{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. - This also supports manpages specified as ``man.1``. + .. code-block:: python - .. note:: This currently affects only HTML writers but could be - expanded in the future. + figure_language_filename = '{path}{language}/{basename}{ext}' - .. versionadded:: 1.7 + .. versionadded:: 1.4 -.. confval:: nitpicky + .. versionchanged:: 1.5 + Added ``{path}`` and ``{basename}`` tokens. - If true, Sphinx will warn about *all* references where the target cannot be - found. Default is ``False``. You can activate this mode temporarily using - the :option:`-n <sphinx-build -n>` command-line switch. + .. versionchanged:: 3.2 + Added ``{docpath}`` token. - .. versionadded:: 1.0 +.. confval:: translation_progress_classes + :type: :code-py:`bool | 'translated' | 'untranslated'` + :default: :code-py:`False` -.. confval:: nitpick_ignore + 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. - 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')``. + :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.1 - .. versionchanged:: 6.2 - Changed allowable container types to a set, list, or tuple + .. versionadded:: 7.1 -.. 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). +Options for markup +------------------ - 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')``. +.. confval:: default_role + :type: :code-py:`str` + :default: :code-py:`None` - .. versionadded:: 4.1 - .. versionchanged:: 6.2 - Changed allowable container types to a set, list, or tuple + .. index:: default; role -.. confval:: numfig + 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". - 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``. + The default role can always be set within individual documents using + the standard reStructuredText :dudir:`default-role` directive. - .. note:: + .. versionadded:: 0.4 - The LaTeX builder always assigns numbers whether this option is enabled - or not. +.. confval:: keep_warnings + :type: :code-py:`bool` + :default: :code-py:`False` - .. versionadded:: 1.3 + 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. -.. confval:: numfig_format + .. versionadded:: 0.5 - 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. +.. confval:: option_emphasise_placeholders + :type: :code-py:`bool` + :default: :code-py:`False` - Default is to use ``'Fig. %s'`` for ``'figure'``, ``'Table %s'`` for - ``'table'``, ``'Listing %s'`` for ``'code-block'`` and ``'Section %s'`` for - ``'section'``. + 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. - .. versionadded:: 1.3 + .. versionadded:: 5.1 -.. confval:: numfig_secnum_depth +.. confval:: primary_domain + :type: :code-py:`str` + :default: :code-py:`'py'` - - 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... + .. index:: pair: default; domain - .. versionadded:: 1.3 + The name of the default :doc:`domain </usage/domains/index>`. + 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: - .. versionchanged:: 1.7 - The LaTeX builder obeys this setting (if :confval:`numfig` is set to - ``True``). + .. code-block:: python -.. confval:: smartquotes + primary_domain = 'cpp' - 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.0 - __ https://docutils.sourceforge.io/docs/user/smartquotes.html - __ https://daringfireball.net/projects/smartypants/ +.. confval:: rst_epilog + :type: :code-py:`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`.) + .. index:: pair: global; substitutions - 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. + 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: - __ https://docutils.sourceforge.io/docs/user/config.html - __ https://docutils.sourceforge.io/docs/user/config.html#smart-quotes + .. code-block:: python -.. confval:: smartquotes_action + rst_epilog = """ + .. |psf| replace:: Python Software Foundation + """ - 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 ``...``. + .. versionadded:: 0.6 - .. versionadded:: 1.6.6 +.. confval:: rst_prolog + :type: :code-py:`str` + :default: :code-py:`''` - __ https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/ + .. index:: pair: global; substitutions -.. confval:: smartquotes_excludes + 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: - This is a ``dict`` whose default is:: + .. code-block:: python - {'languages': ['ja'], 'builders': ['man', 'text']} + rst_prolog = """ + .. |psf| replace:: Python Software Foundation + """ - 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. + .. versionadded:: 1.0 - .. 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. +.. confval:: show_authors + :type: :code-py:`bool` + :default: :code-py:`False` - .. 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: + A boolean that decides whether :rst:dir:`codeauthor` and + :rst:dir:`sectionauthor` directives produce any output in the built files. - .. code-block:: console +.. confval:: trim_footnote_reference_space + :type: :code-py:`bool` + :default: :code-py:`False` - make latex O="-D smartquotes_action=" + 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. - This can follow some ``make html`` with no problem, in contrast to the - situation from the prior note. + .. versionadded:: 0.6 - .. versionadded:: 1.6.6 -.. confval:: user_agent +.. _math-options: - 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 Maths +----------------- - .. versionadded:: 2.3 +These options control maths markup and notation. -.. confval:: tls_verify +.. confval:: math_eqref_format + :type: :code-py:`str` + :default: :code-py:`'({number})'` - If true, Sphinx verifies server certifications. Default is ``True``. + A string used for formatting the labels of references to equations. + The ``{number}`` place-holder stands for the equation number. - .. versionadded:: 1.5 + Example: ``'Eq.{number}'`` gets rendered as, for example, ``Eq.10``. -.. confval:: tls_cacerts + .. versionadded:: 1.7 - 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:: math_number_all + :type: :code-py:`bool` + :default: :code-py:`False` - .. versionadded:: 1.5 + Force all displayed equations to be numbered. + Example: - .. 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. + .. code-block:: python - .. _requests: https://requests.readthedocs.io/en/master/ + math_number_all = True -.. confval:: today - today_fmt + .. versionadded:: 1.4 - These values determine how to format the current date, used as the - replacement for ``|today|``. +.. confval:: math_numfig + :type: :code-py:`bool` + :default: :code-py:`True` - * 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`. + 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. - 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). + .. versionadded:: 1.7 -.. confval:: highlight_language +.. confval:: math_numsep + :type: :code-py:`str` + :default: :code-py:`'.'` - 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. + A string that defines the separator between section numbers + and the equation number when :confval:`numfig` is enabled and + :confval:`numfig_secnum_depth` is positive. - The value should be a valid Pygments lexer name, see - :ref:`code-examples` for more details. + Example: :code-py:`'-'` gets rendered as ``1.2-3``. - .. versionadded:: 0.5 + .. versionadded:: 7.4 - .. versionchanged:: 1.4 - The default is now ``'default'``. If you prefer Python 2 only - highlighting, you can set it back to ``'python'``. -.. confval:: highlight_options +Options for the nitpicky mode +----------------------------- - 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 <https://pygments.org/docs/lexers>`_. +.. confval:: nitpicky + :type: :code-py:`bool` + :default: :code-py:`False` - Example:: + 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. - highlight_options = { - 'default': {'stripall': True}, - 'php': {'startinline': True}, - } + You can activate this mode temporarily using + the :option:`--nitpicky <sphinx-build --nitpicky>` command-line option. + See :confval:`nitpick_ignore` for a way to mark missing references + as "known missing". - A single dictionary of options are also allowed. Then it is recognized - as options to the lexer specified by :confval:`highlight_language`:: + .. code-block:: python - # configuration for the ``highlight_language`` - highlight_options = {'stripall': True} + nitpicky = True - .. versionadded:: 1.3 - .. versionchanged:: 3.5 + .. versionadded:: 1.0 - Allow to configure highlight options for multiple languages +.. confval:: nitpick_ignore + :type: :code-py:`set[tuple[str, str]] | Sequence[tuple[str, str]]` + :default: :code-py:`()` -.. confval:: pygments_style + A set or list of :code-py:`(warning_type, target)` tuples + that should be ignored when generating warnings + in :confval:`"nitpicky mode" <nitpicky>`. + Note that ``warning_type`` should include the domain name if present. + Example: + + .. 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. + nitpick_ignore = { + ('py:func', 'int'), + ('envvar', 'LD_LIBRARY_PATH'), + } - .. 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.1 + .. versionchanged:: 6.2 + Changed allowable container types to a set, list, or tuple -.. confval:: maximum_signature_line_length +.. confval:: nitpick_ignore_regex + :type: :code-py:`set[tuple[str, str]] | Sequence[tuple[str, str]]` + :default: :code-py:`()` - If a signature's length in characters exceeds the number set, each - parameter within the signature will be displayed on an individual logical - line. + 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). - When ``None`` (the default), there is no maximum length and the entire - signature will be displayed on a single logical line. + 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')`. - 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. + .. versionadded:: 4.1 + .. versionchanged:: 6.2 + Changed allowable container types to a set, list, or tuple - 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 +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. Default is ``True``. + name is callable. -.. confval:: add_module_names +.. confval:: maximum_signature_line_length + :type: :code-py:`int | None` + :default: :code-py:`None` - 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``. + If a signature's length in characters exceeds the number set, + each parameter within the signature will be displayed on + an individual logical line. -.. confval:: toc_object_entries + When :code-py:`None`, there is no maximum length and the entire + signature will be displayed on a single logical line. - Create table of contents entries for domain objects (e.g. functions, classes, - attributes, etc.). Default is ``True``. + 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. -.. confval:: toc_object_entries_show_parents + 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`). - A string that determines how domain objects (e.g. functions, classes, - attributes, etc.) are displayed in their table of contents entry. + .. versionadded:: 7.1 - 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. +.. confval:: strip_signature_backslash + :type: :code-py:`bool` + :default: :code-py:`False` - Use ``hide`` to only show the name of the element without any parents - (i.e. ``method()``). + 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 + :code-py:`True` will reinstate that behaviour. - Use ``all`` to show the fully-qualified name for the object - (i.e. ``module.Class.method()``), displaying all parents. + .. versionadded:: 3.0 + +.. 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:: show_authors +.. confval:: toc_object_entries_show_parents + :type: :code-py:`'domain' | 'hide' | 'all'` + :default: :code-py:`'domain'` - A boolean that decides whether :rst:dir:`codeauthor` and - :rst:dir:`sectionauthor` directives produce any output in the built files. + A string that determines how domain objects + (functions, classes, attributes, etc.) + are displayed in their table of contents entry. -.. confval:: modindex_common_prefix + 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. - 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 - ``[]``. + Use :code-py:`'hide'` to only show the name of the element + without any parents (i.e. :code-py:`method()`). - .. versionadded:: 0.6 + Use :code-py:`'all'` to show the fully-qualified name for the object + (i.e. :code-py:`module.Class.method()`), displaying all parents. -.. confval:: trim_footnote_reference_space + .. versionadded:: 5.2 - Trim spaces before footnote references that are necessary for the reST - parser to recognize the footnote, but do not look too nice in the output. - .. versionadded:: 0.6 +Options for source files +------------------------ -.. confval:: trim_doctest_flags +.. 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`. - If true, doctest flags (comments looking like ``# doctest: FLAG, ...``) at - the ends of lines and ``<BLANKLINE>`` markers are removed for all code - blocks showing interactive Python sessions (i.e. doctests). Default is - ``True``. See the extension :mod:`~sphinx.ext.doctest` for more - possibilities of including doctests. + Example patterns: - .. versionadded:: 1.0 - .. versionchanged:: 1.1 - Now also removes ``<BLANKLINE>``. + * :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:: strip_signature_backslash + :confval:`exclude_patterns` is also consulted when looking for static files + in :confval:`html_static_path` and :confval:`html_extra_path`. - 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. + .. versionadded:: 1.0 - .. versionadded:: 3.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`. -.. confval:: option_emphasise_placeholders + Example patterns: - 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. + * :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 <sphinx-build -v>` - 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:`()` - The alt text for image is translated by default. + 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: -.. confval:: figure_language_filename + .. code-block:: python - 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: + templates_path = ['.templates'] - * ``{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`` + .. versionchanged:: 1.3 + As these files are not meant to be built, + they are automatically excluded when discovering source files. - For example, setting this to ``{path}{language}/{basename}{ext}`` will - expand to ``dirname/en/filename.png`` instead. - .. versionadded:: 1.4 +Options for warning control +--------------------------- - .. versionchanged:: 1.5 - Added ``{path}`` and ``{basename}`` tokens. +.. confval:: show_warning_types + :type: :code-py:`bool` + :default: :code-py:`False` - .. versionchanged:: 3.2 - Added ``{docpath}`` token. + 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. -.. confval:: translation_progress_classes + .. versionadded:: 7.3.0 - 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. +.. confval:: suppress_warnings + :type: :code-py:`Sequence[str]` + :default: :code-py:`()` - * ``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. + A list of warning codes to suppress arbitrary warning messages. - Defaults to ``False``. + By default, Sphinx supports the following warning codes: - .. versionadded:: 7.1 + * ``app.add_node`` + * ``app.add_directive`` + * ``app.add_role`` + * ``app.add_generic_role`` + * ``app.add_source_parser`` + * ``config.cache`` + * ``docutils`` + * ``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`` -.. _math-options: + Extensions can also define their own warning types. + Those defined by the first-party ``sphinx.ext`` extensions are: -Options for Math ----------------- + * ``autodoc`` + * ``autodoc.import_object`` + * ``autosectionlabel.<document name>`` + * ``autosummary`` + * ``autosummary.import_cycle`` + * ``intersphinx.external`` -These options influence Math notations. + You can choose from these types. You can also give only the first + component to exclude all warnings attached to it. -.. confval:: math_number_all + .. versionadded:: 1.4 - Set this option to ``True`` if you want all displayed math to be numbered. - The default is ``False``. + .. versionchanged:: 1.5 + Added ``misc.highlighting_failure`` -.. confval:: math_eqref_format + .. versionchanged:: 1.5.1 + Added ``epub.unknown_project_files`` - A string used for formatting the labels of references to equations. - The ``{number}`` place-holder stands for the equation number. + .. versionchanged:: 1.6 + Added ``ref.footnote`` - Example: ``'Eq.{number}'`` gets rendered as, for example, ``Eq.10``. + .. versionchanged:: 2.1 + Added ``autosectionlabel.<document name>`` -.. confval:: math_numfig + .. versionchanged:: 3.3.0 + Added ``epub.duplicated_toc_entry`` - 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``. + .. versionchanged:: 4.3 + Added ``toc.excluded`` and ``toc.not_readable`` - .. versionadded:: 1.7 + .. versionadded:: 4.5 + Added ``i18n.inconsistent_references`` + + .. versionadded:: 7.1 + Added ``index``. + + .. versionadded:: 7.3 + Added ``config.cache``. + + .. versionadded:: 7.3 + Added ``toc.no_title``. + + +Builder options +=============== .. _html-options: @@ -1072,186 +1432,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 </usage/theming>`. The default is ``'alabaster'``. + The theme for HTML output. + See the :doc:`HTML theming section </usage/theming>`. .. 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 <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:: 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 ``<title>`` 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. + + .. _favicon: https://developer.mozilla.org/en-US/ + docs/Web/HTML/Attributes/rel#icon + + Example: - 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``. + .. 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 ``https://example.org/style.css``. The *attributes* is used - for attributes of ``<link>`` tag. It defaults to an empty list. + 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. - Example:: + Example: - html_css_files = ['custom.css', - 'https://example.com/css/custom.css', - ('print.css', {'media': 'print'})] + .. code-block:: python - 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()`. + html_css_files = [ + 'custom.css', + 'https://example.com/css/custom.css', + ('print.css', {'media': 'print'}), + ] + + 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: - html_js_files = ['script.js', - 'https://example.com/scripts/custom.js', - ('custom.js', {'async': 'async'})] + .. code-block:: python - 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()`. + 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 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: - html_static_path = ['_static', '_static/.htaccess'] + .. code-block:: python - Another way to do that, you can also use - :confval:`html_extra_path`. It allows to copy dotfiles under - the directories. + html_static_path = ['_static', '_static/.htaccess'] + + 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. @@ -1264,244 +1681,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. + 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. - 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']``. + 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'`. - * If a value is a single string, it specifies a custom sidebar to be added - between the ``'sourcelink.html'`` and ``'searchbox.html'`` entries. This - is for compatibility with Sphinx versions before 1.0. - - .. deprecated:: 1.7 - - a single string value for ``html_sidebars`` will be removed in 2.0 - - Builtin sidebar templates that can be rendered are: + 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 @@ -1521,98 +1992,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 @@ -1650,54 +2124,59 @@ that use Sphinx's HTMLWriter class. .. versionadded:: 1.2 .. confval:: html_scaled_image_link + :type: :code-py:`bool` + :default: :code-py:`True` - 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``. + 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. - Document authors can disable this feature manually with giving - ``no-scaled-link`` class to the image: + .. tip:: - .. code-block:: rst + To disable this feature on a per-image basis, + add the ``no-scaled-link`` class to the image directive: - .. image:: sphinx.png - :scale: 50% - :class: no-scaled-link + .. code-block:: rst + + .. 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: @@ -1705,20 +2184,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 @@ -1730,26 +2220,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. @@ -1757,388 +2256,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: - epub_guide = (('cover', 'cover.html', 'Cover Page'),) + .. code-block:: python + + 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`. Example:: + 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: + + .. 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 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. + 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. + + .. _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: @@ -2149,241 +2769,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'``. - This value can be a bool or a list of index names that should be generated, - like for :confval:`html_domain_indices`. + Example: + + .. 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:: @@ -2391,19 +3065,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_). @@ -2412,113 +3088,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 @@ -2530,42 +3233,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: @@ -2576,57 +3284,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: @@ -2636,266 +3355,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_cross_references +.. 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. - 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.2 + +.. confval:: texinfo_show_urls + :type: :code-py:`'footnote' | 'no' | 'inline'` + :default: :code-py:`'footnote'` + + Control how to display URL addresses. + The setting can have the following values: + + :code-py:`'footnote'` + Display URLs in footnotes. + :code-py:`'no'` + Do not display URLs. + :code-py:`'inline'` + Display URLs inline in parentheses. + + .. 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#', @@ -2904,33 +3632,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')), @@ -2939,81 +3712,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` - 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. + 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`. - If a server indicates when to retry (using the `Retry-After`_ header), - ``linkcheck`` always follows the server indication. + .. 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. + .. xref RemovedInSphinx80Warning + + .. 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 - and custom timeouts should be given in 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: @@ -3021,124 +3836,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 will be displayed on an individual logical line. This is a - domain-specific setting, overriding :confval:`maximum_signature_line_length`. + If a signature's length in characters exceeds the number set, + each parameter within the signature will be displayed on + an individual logical line. + + When :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:: 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. - A list of prefixes that will be ignored when sorting C++ objects in the - global index. For example ``['awesome_lib::']``. + Example: + + .. code-block:: python + + 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: - 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. + .. code-block:: python + + 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:: rst .. 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`. @@ -3148,29 +4094,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. - 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`. + .. versionadded:: 4.0 - .. versionadded:: 7.1 + .. caution:: + This feature is experimental. -Example of configuration file ------------------------------ +.. confval:: trim_doctest_flags + :type: :code-py:`bool` + :default: :code-py:`True` + + 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/domains/c.rst b/doc/usage/domains/c.rst index 3c1a41d..49aa5ca 100644 --- a/doc/usage/domains/c.rst +++ b/doc/usage/domains/c.rst @@ -24,7 +24,7 @@ The C domain (name **c**) is suited for documentation of C API. .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) Note that you don't have to backslash-escape asterisks in the signature, as - it is not parsed by the reST inliner. + it is not parsed by the reStructuredText inliner. In the description of a function you can use the following info fields (see also :ref:`info-field-lists`). @@ -128,7 +128,7 @@ The C domain (name **c**) is suited for documentation of C API. Describes a C type, either as a typedef, or the alias for an unspecified type. -.. _c-roles: +.. _c-xref-roles: Cross-referencing C constructs ------------------------------ diff --git a/doc/usage/domains/cpp.rst b/doc/usage/domains/cpp.rst index 6c9372b..57cb932 100644 --- a/doc/usage/domains/cpp.rst +++ b/doc/usage/domains/cpp.rst @@ -568,7 +568,7 @@ following fields: .. versionadded:: 4.3 The ``retval`` field type. -.. _cpp-roles: +.. _cpp-xref-roles: Cross-referencing ----------------- diff --git a/doc/usage/domains/index.rst b/doc/usage/domains/index.rst index b5d43ce..8c47134 100644 --- a/doc/usage/domains/index.rst +++ b/doc/usage/domains/index.rst @@ -1,5 +1,7 @@ .. highlight:: rst +.. _usage-domains: + ======= Domains ======= @@ -121,7 +123,7 @@ This is particularly useful for literate programming: .. py:function:: spam(eggs) :no-typesetting: - .. code:: + .. code:: python def spam(eggs): pass diff --git a/doc/usage/domains/javascript.rst b/doc/usage/domains/javascript.rst index 630b52e..ba0ff10 100644 --- a/doc/usage/domains/javascript.rst +++ b/doc/usage/domains/javascript.rst @@ -120,7 +120,7 @@ The JavaScript domain (name **js**) provides the following directives: Describes the attribute *name* of *object*. -.. _js-roles: +.. _js-xref-roles: These roles are provided to refer to the described objects: diff --git a/doc/usage/domains/python.rst b/doc/usage/domains/python.rst index 96982f1..5b98baa 100644 --- a/doc/usage/domains/python.rst +++ b/doc/usage/domains/python.rst @@ -124,8 +124,9 @@ The following directives are provided for module and class contents: .. rst:directive:: .. py:data:: name Describes global data in a module, including both variables and values used - as "defined constants." Class and object attributes are not documented - using this environment. + as "defined constants." + Consider using :rst:dir:`py:type` for type aliases instead + and :rst:dir:`py:attribute` for class variables and instance attributes. .. rubric:: options @@ -259,6 +260,7 @@ The following directives are provided for module and class contents: Describes an object data attribute. The description should include information about the type of the data to be expected and whether it may be changed directly. + Type aliases should be documented with :rst:dir:`py:type`. .. rubric:: options @@ -315,6 +317,55 @@ The following directives are provided for module and class contents: Describe the location where the object is defined. The default value is the module specified by :rst:dir:`py:currentmodule`. +.. rst:directive:: .. py:type:: name + + Describe a :ref:`type alias <python:type-aliases>`. + + The type that the alias represents should be described + with the :rst:dir:`!canonical` option. + This directive supports an optional description body. + + For example: + + .. code-block:: rst + + .. py:type:: UInt64 + + Represent a 64-bit positive integer. + + will be rendered as follows: + + .. py:type:: UInt64 + :no-contents-entry: + :no-index-entry: + + Represent a 64-bit positive integer. + + .. rubric:: options + + .. rst:directive:option:: canonical + :type: text + + The canonical type represented by this alias, for example: + + .. code-block:: rst + + .. py:type:: StrPattern + :canonical: str | re.Pattern[str] + + Represent a regular expression or a compiled pattern. + + This is rendered as: + + .. py:type:: StrPattern + :no-contents-entry: + :no-index-entry: + :canonical: str | re.Pattern[str] + + Represent a regular expression or a compiled pattern. + + .. versionadded:: 7.4 + .. rst:directive:: .. py:method:: name(parameters) .. py:method:: name[type parameters](parameters) @@ -494,7 +545,7 @@ It is customary to put the opening bracket before the comma. Python 3.12 introduced *type parameters*, which are type variables declared directly within the class or function definition: -.. code:: python +.. code-block:: python class AnimalList[AnimalT](list[AnimalT]): ... @@ -504,7 +555,7 @@ declared directly within the class or function definition: The corresponding reStructuredText documentation would be: -.. code:: rst +.. code-block:: rst .. py:class:: AnimalList[AnimalT] @@ -522,7 +573,8 @@ Info field lists meta fields are added. -Inside Python object description directives, reST field lists with these fields +Inside Python object description directives, +reStructuredText field lists with these fields are recognized and formatted nicely: * ``param``, ``parameter``, ``arg``, ``argument``, ``key``, ``keyword``: @@ -604,7 +656,7 @@ word "or":: :vartype a_var: str or int :rtype: float or str -.. _python-roles: +.. _python-xref-roles: Cross-referencing Python objects -------------------------------- @@ -649,6 +701,10 @@ a matching identifier is found: .. note:: The role is also able to refer to property. +.. rst:role:: py:type + + Reference a type alias. + .. rst:role:: py:exc Reference an exception. A dotted name may be used. diff --git a/doc/usage/domains/restructuredtext.rst b/doc/usage/domains/restructuredtext.rst index 3a936a6..639b686 100644 --- a/doc/usage/domains/restructuredtext.rst +++ b/doc/usage/domains/restructuredtext.rst @@ -10,9 +10,10 @@ The reStructuredText domain (name **rst**) provides the following directives: .. rst:directive:: .. rst:directive:: name - Describes a reST directive. The *name* can be a single directive name or - actual directive syntax (`..` prefix and `::` suffix) with arguments that - will be rendered differently. For example:: + Describes a reStructuredText directive. + The *name* can be a single directive name or actual directive syntax + (`..` prefix and `::` suffix) with arguments that will be rendered differently. + For example:: .. rst:directive:: foo @@ -38,7 +39,7 @@ The reStructuredText domain (name **rst**) provides the following directives: .. rst:directive:: .. rst:directive:option:: name - Describes an option for reST directive. The *name* can be a single option + Describes an option for reStructuredText directive. The *name* can be a single option name or option name with arguments which separated with colon (``:``). For example:: @@ -77,7 +78,7 @@ The reStructuredText domain (name **rst**) provides the following directives: .. rst:directive:: .. rst:role:: name - Describes a reST role. For example:: + Describes a reStructuredText role. For example:: .. rst:role:: foo @@ -91,7 +92,7 @@ The reStructuredText domain (name **rst**) provides the following directives: Foo description. -.. _rst-roles: +.. _rst-xref-roles: These roles are provided to refer to the described objects: diff --git a/doc/usage/domains/standard.rst b/doc/usage/domains/standard.rst index 59b7e72..a676a2d 100644 --- a/doc/usage/domains/standard.rst +++ b/doc/usage/domains/standard.rst @@ -42,6 +42,44 @@ There is a set of directives allowing documenting command-line programs: ``cmdoption`` directive is a deprecated alias for the ``option`` directive. +.. rst:directive:: .. confval:: name + + Describes a configuration value or setting that the documented + code or program uses or defines. + Referenceable by :rst:role:`confval`. + + .. rst:directive:option:: type + :type: text + + Describes the type of the configuration value. + This is optional, and if specified will be interpreted as reStructuredText. + + .. rst:directive:option:: default + :type: text + + Describes the default value of the configuration value. + This is optional, and if specified will be interpreted as reStructuredText. + + Example: + + .. code-block:: rst + + .. confval:: the_answer + :type: ``int`` (a *number*) + :default: **42** + + This is a setting that controls the value of the answer. + + will be rendered as follows: + + .. confval:: the_answer + :no-contents-entry: + :no-index-entry: + :type: ``int`` (a *number*) + :default: **42** + + This is a setting that controls the value of the answer. + .. rst:directive:: .. envvar:: name Describes an environment variable that the documented code or program uses diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index c920de8..a2a093f 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/doc/usage/extensions/autodoc.rst @@ -1,4 +1,6 @@ -.. highlight:: rest +.. highlight:: rst + +.. _ext-autodoc: :mod:`sphinx.ext.autodoc` -- Include documentation from docstrings ================================================================== @@ -12,13 +14,6 @@ This extension can import the modules you are documenting, and pull in documentation from docstrings in a semi-automatic way. -.. note:: - - For Sphinx (actually, the Python interpreter that executes Sphinx) to find - your module, it must be importable. That means that the module or the - package must be in one of the directories on :data:`sys.path` -- adapt your - :data:`sys.path` in the configuration file accordingly. - .. warning:: :mod:`~sphinx.ext.autodoc` **imports** the modules to be documented. If any @@ -43,6 +38,68 @@ docstrings to correct reStructuredText before :mod:`autodoc` processes them. .. _Google: https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings .. _NumPy: https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard +Getting started +--------------- + +Setup +..... +Activate the plugin by adding ``'sphinx.ext.autodoc'`` to the :confval:`extensions` +in your :file:`conf.py`:: + + extensions = [ + ... + 'sphinx.ext.autodoc', + ] + +Ensuring the code can be imported +................................. + +:mod:`~sphinx.ext.autodoc` analyses the code and docstrings by introspection after +importing the modules. For importing to work, you have to make sure that your +modules can be found by Sphinx and that dependencies can be resolved (if your +module does ``import foo``, but ``foo`` is not available in the python environment +that Sphinx runs in, your module import will fail). + +There are two ways to ensure this: + +1. Use an environment that contains your package and Sphinx. This can e.g. be your + local dev environment (with an editable install), or an environment in CI in + which you install Sphinx and your package. The regular installation process + ensures that your package can be found by Sphinx and that all dependencies are + available. + +2. It is alternatively possible to patch the Sphinx run so that it can operate + directly on the sources; e.g. if you want to be able to do a Sphinx build from a + source checkout. + + - Patch :data:`sys.path` in your Sphinx :file:`conf.py` to include the folder of + your sources. E.g. if you have a repository structure with :file:`doc/conf.py` + and your package is at :file:`src/mypackage`, then you should add:: + + sys.path.insert(0, os.path.abspath('../src')) + + to your :file:`conf.py`. + + - To cope with missing dependencies, specify the missing modules in + :confval:`autodoc_mock_imports`. + +Usage +..... + +You can now use the :ref:`autodoc-directives` to add formatted documentation for +Python code elements like functions, classes, modules, etc. For example, to document +the function ``io.open()``, reading its signature and docstring from the source file, +you'd write :: + + .. autofunction:: io.open + +You can also document whole classes or even modules automatically, using member +options for the auto directives, like :: + + .. automodule:: io + :members: + +.. _autodoc-directives: Directives ---------- @@ -271,7 +328,7 @@ inserting them into the page source under a suitable :rst:dir:`py:module`, once by specifying the option to :rst:dir:`automodule` directive. Note: this will lead to markup errors if the inherited members come from a - module whose docstrings are not reST formatted. + module whose docstrings are not reStructuredText formatted. .. versionadded:: 0.3 @@ -688,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 @@ -816,8 +873,8 @@ needed docstring processing in event :event:`autodoc-process-docstring`: .. versionadded:: 4.1 .. versionchanged:: 4.3 - ``bases`` can contain a string as a base class name. It will be processed - as reST mark-up'ed text. + ``bases`` can contain a string as a base class name. + It will be processed as reStructuredText. Skipping members diff --git a/doc/usage/extensions/autosectionlabel.rst b/doc/usage/extensions/autosectionlabel.rst index b5b9b51..29b1c2a 100644 --- a/doc/usage/extensions/autosectionlabel.rst +++ b/doc/usage/extensions/autosectionlabel.rst @@ -1,4 +1,4 @@ -.. highlight:: rest +.. highlight:: rst :mod:`sphinx.ext.autosectionlabel` -- Allow reference sections using its title ============================================================================== @@ -51,6 +51,6 @@ Debugging --------- The ``WARNING: undefined label`` indicates that your reference in -:rst:role:`ref` is mis-spelled. Invoking :program:`sphinx-build` with ``-vv`` +:rst:role:`ref` is mis-spelled. Invoking :program:`sphinx-build` with ``-vvv`` (see :option:`-v`) will print all section names and the labels that have been generated for them. This output can help finding the right reference label. diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst index a18460b..0a25d8d 100644 --- a/doc/usage/extensions/autosummary.rst +++ b/doc/usage/extensions/autosummary.rst @@ -1,4 +1,4 @@ -.. highlight:: rest +.. highlight:: rst :mod:`sphinx.ext.autosummary` -- Generate autodoc summaries =========================================================== diff --git a/doc/usage/extensions/coverage.rst b/doc/usage/extensions/coverage.rst index b9c493b..75ffc0f 100644 --- a/doc/usage/extensions/coverage.rst +++ b/doc/usage/extensions/coverage.rst @@ -6,15 +6,64 @@ This extension features one additional builder, the :class:`CoverageBuilder`. -.. class:: CoverageBuilder +.. todo:: Write this section. - To use this builder, activate the coverage extension in your configuration - file and give ``-M coverage`` on the command line. +.. note:: -.. todo:: Write this section. + The :doc:`sphinx-apidoc </man/sphinx-apidoc>` command can be used to + automatically generate API documentation for all code in a project, + avoiding the need to manually author these documents and keep them up-to-date. + +.. warning:: + + :mod:`~sphinx.ext.coverage` **imports** the modules to be documented. + If any modules have side effects on import, + these will be executed by the coverage builder when ``sphinx-build`` is run. + + If you document scripts (as opposed to library modules), + make sure their main routine is protected by a + ``if __name__ == '__main__'`` condition. + +.. note:: + + For Sphinx (actually, the Python interpreter that executes Sphinx) + to find your module, it must be importable. + That means that the module or the package must be in + one of the directories on :data:`sys.path` -- adapt your :data:`sys.path` + in the configuration file accordingly. + +To use this builder, activate the coverage extension in your configuration file +and run ``sphinx-build -M coverage`` on the command line. + + +Builder +------- + +.. py:class:: CoverageBuilder + + +Configuration +------------- + +Several configuration values can be used to specify +what the builder should check: + +.. confval:: coverage_modules + :type: ``list[str]`` + :default: ``[]`` + + List of Python packages or modules to test coverage for. + When this is provided, Sphinx will introspect each package + or module provided in this list as well + as all sub-packages and sub-modules found in each. + When this is not provided, Sphinx will only provide coverage + for Python packages and modules that it is aware of: + that is, any modules documented using the :rst:dir:`py:module` directive + provided in the :doc:`Python domain </usage/domains/python>` + or the :rst:dir:`automodule` directive provided by the + :mod:`~sphinx.ext.autodoc` extension. -Several configuration values can be used to specify what the builder -should check: + .. versionadded:: 7.4 .. confval:: coverage_ignore_modules diff --git a/doc/usage/extensions/doctest.rst b/doc/usage/extensions/doctest.rst index 1848e1f..a5fc2c7 100644 --- a/doc/usage/extensions/doctest.rst +++ b/doc/usage/extensions/doctest.rst @@ -1,4 +1,4 @@ -.. highlight:: rest +.. highlight:: rst :mod:`sphinx.ext.doctest` -- Test snippets in the documentation =============================================================== @@ -344,12 +344,12 @@ The doctest extension uses the following configuration values: .. confval:: doctest_test_doctest_blocks - If this is a nonempty string (the default is ``'default'``), standard reST - doctest blocks will be tested too. They will be assigned to the group name - given. + If this is a nonempty string (the default is ``'default'``), + standard reStructuredText doctest blocks will be tested too. + They will be assigned to the group name given. - reST doctest blocks are simply doctests put into a paragraph of their own, - like so:: + reStructuredText doctest blocks are simply doctests + put into a paragraph of their own, like so:: Some documentation text. @@ -378,8 +378,8 @@ The doctest extension uses the following configuration values: with the :mod:`~sphinx.ext.autodoc` extension without marking them up with a special directive. - Note though that you can't have blank lines in reST doctest blocks. They - will be interpreted as one block ending and another one starting. Also, - removal of ``<BLANKLINE>`` and ``# doctest:`` options only works in + Note though that you can't have blank lines in reStructuredText doctest blocks. + They will be interpreted as one block ending and another one starting. + Also, removal of ``<BLANKLINE>`` and ``# doctest:`` options only works in :rst:dir:`doctest` blocks, though you may set :confval:`trim_doctest_flags` to achieve that in all code blocks with Python console content. diff --git a/doc/usage/extensions/graphviz.rst b/doc/usage/extensions/graphviz.rst index 231bd36..0cd7cac 100644 --- a/doc/usage/extensions/graphviz.rst +++ b/doc/usage/extensions/graphviz.rst @@ -1,4 +1,4 @@ -.. highlight:: rest +.. highlight:: rst :mod:`sphinx.ext.graphviz` -- Add Graphviz graphs ================================================= @@ -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/extensions/ifconfig.rst b/doc/usage/extensions/ifconfig.rst index 837c0b3..17cdbc0 100644 --- a/doc/usage/extensions/ifconfig.rst +++ b/doc/usage/extensions/ifconfig.rst @@ -1,4 +1,4 @@ -.. highlight:: rest +.. highlight:: rst :mod:`sphinx.ext.ifconfig` -- Include content based on configuration ==================================================================== diff --git a/doc/usage/extensions/inheritance.rst b/doc/usage/extensions/inheritance.rst index 33284b5..90bbcc3 100644 --- a/doc/usage/extensions/inheritance.rst +++ b/doc/usage/extensions/inheritance.rst @@ -1,4 +1,4 @@ -.. highlight:: rest +.. highlight:: rst :mod:`sphinx.ext.inheritance_diagram` -- Include inheritance diagrams ===================================================================== diff --git a/doc/usage/extensions/intersphinx.rst b/doc/usage/extensions/intersphinx.rst index e81719f..f64b596 100644 --- a/doc/usage/extensions/intersphinx.rst +++ b/doc/usage/extensions/intersphinx.rst @@ -1,3 +1,5 @@ +.. _ext-intersphinx: + :mod:`sphinx.ext.intersphinx` -- Link to other projects' documentation ====================================================================== @@ -143,7 +145,7 @@ linking: Example: - .. code:: python + .. code-block:: python intersphinx_mapping = {'https://docs.python.org/': None} diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst index 251d721..7d48d3a 100644 --- a/doc/usage/extensions/math.rst +++ b/doc/usage/extensions/math.rst @@ -1,4 +1,4 @@ -.. highlight:: rest +.. highlight:: rst .. _math-support: diff --git a/doc/usage/installation.rst b/doc/usage/installation.rst index 13dc6a9..7be6889 100644 --- a/doc/usage/installation.rst +++ b/doc/usage/installation.rst @@ -2,30 +2,101 @@ Installing Sphinx ================= -.. contents:: - :depth: 1 +Sphinx is a Python application. It can be installed in one of the ways described +below. + +.. contents:: Installation methods + :depth: 2 :local: :backlinks: none .. highlight:: console -Overview --------- +After installation, you can check that Sphinx is available by running :: + + $ sphinx-build --version + +This should print out the Sphinx version number. + + +.. tip:: + + For local development, it is + generally recommended to install Sphinx into a non-global environment + (using for example `venv`__ or `conda`__ environments). + This will allow for the use of separate sphinx versions and third-party extensions + for each sphinx project. + + __ https://docs.python.org/3/library/venv.html + __ https://conda.io/projects/conda/en/latest/user-guide/getting-started.html + + +.. _install-pypi: + +PyPI package +------------ + +Sphinx packages are published on the `Python Package Index +<https://pypi.org/project/Sphinx/>`_ (PyPI). The preferred tool for installing +packages from PyPI is :command:`pip`, which is included in all modern versions of +Python. + +Run the following command:: + + $ pip install -U sphinx + +.. tip:: + + To avoid issues when rebuilding your environment, + it is advisable to pin sphinx and third-party extension + versions in a `requirements.txt file`__:: + + $ pip install -r requirements.txt + + Or, if writing documentation for a Python package, + place the dependencies in the `pyproject.toml file`__:: + + $ pip install .[docs] -Sphinx is written in `Python`__ and supports Python 3.9+. It builds upon the -shoulders of many third-party libraries such as `Docutils`__ and `Jinja`__, -which are installed when Sphinx is installed. + __ https://pip.pypa.io/en/stable/reference/requirements-file-format/ + __ https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#dependencies-optional-dependencies -__ https://docs.python-guide.org/ -__ https://docutils.sourceforge.io/ -__ https://jinja.palletsprojects.com/ +.. _install-conda: +Conda package +------------- +To work with :command:`conda`, you need a conda-based Python distribution such as +`anaconda`__, `miniconda`__, `miniforge`__ or `micromamba`__. + +__ https://docs.anaconda.com/anaconda/ +__ https://docs.anaconda.com/miniconda/ +__ https://github.com/conda-forge/miniforge/ +__ https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html + + +Sphinx is available both via the *anaconda main* channel (maintained by Anaconda +Inc.) + +:: + + $ conda install sphinx + +as well as via the *conda-forge* community channel :: + + $ conda install -c conda-forge sphinx + +OS-specific package manager +--------------------------- + +You may install a global version of Sphinx into your system using OS-specific +package managers. However, be aware that this is less flexible and you may run into +compatibility issues if you want to work across different projects. Linux ------ +~~~~~ Debian/Ubuntu -~~~~~~~~~~~~~ +""""""""""""" Install either ``python3-sphinx`` using :command:`apt-get`: @@ -36,7 +107,7 @@ Install either ``python3-sphinx`` using :command:`apt-get`: If it not already present, this will install Python for you. RHEL, CentOS -~~~~~~~~~~~~ +"""""""""""" Install ``python-sphinx`` using :command:`yum`: @@ -47,7 +118,7 @@ Install ``python-sphinx`` using :command:`yum`: If it not already present, this will install Python for you. Other distributions -~~~~~~~~~~~~~~~~~~~ +""""""""""""""""""" Most Linux distributions have Sphinx in their package repositories. Usually the package is called ``python3-sphinx``, ``python-sphinx`` or ``sphinx``. Be @@ -55,19 +126,16 @@ aware that there are at least two other packages with ``sphinx`` in their name: a speech recognition toolkit (*CMU Sphinx*) and a full-text search database (*Sphinx search*). - macOS ------ +~~~~~ -Sphinx can be installed using `Homebrew`__, `MacPorts`__, or as part of -a Python distribution such as `Anaconda`__. +Sphinx can be installed using `Homebrew`__, `MacPorts`__. __ https://brew.sh/ __ https://www.macports.org/ -__ https://www.anaconda.com/download Homebrew -~~~~~~~~ +"""""""" :: @@ -78,7 +146,7 @@ For more information, refer to the `package overview`__. __ https://formulae.brew.sh/formula/sphinx-doc MacPorts -~~~~~~~~ +"""""""" Install either ``python3x-sphinx`` using :command:`port`: @@ -97,23 +165,15 @@ For more information, refer to the `package overview`__. __ https://www.macports.org/ports.php?by=library&substr=py39-sphinx -Anaconda -~~~~~~~~ - -:: - - $ conda install sphinx - Windows -------- +~~~~~~~ -Sphinx can be install using `Chocolatey`__ or -:ref:`installed manually <windows-other-method>`. +Sphinx can be install using `Chocolatey`__. __ https://chocolatey.org/ Chocolatey -~~~~~~~~~~ +"""""""""" :: @@ -127,89 +187,6 @@ For more information, refer to the `chocolatey page`__. __ https://chocolatey.org/packages/sphinx/ -.. _windows-other-method: - -Other Methods -~~~~~~~~~~~~~ - -Most Windows users do not have Python installed by default, so we begin with -the installation of Python itself. To check if you already have Python -installed, open the *Command Prompt* (:kbd:`⊞Win-r` and type :command:`cmd`). -Once the command prompt is open, type :command:`python --version` and press -Enter. If Python is installed, you will see the version of Python printed to -the screen. If you do not have Python installed, refer to the `Hitchhikers -Guide to Python's`__ Python on Windows installation guides. You must install -`Python 3`__. - -Once Python is installed, you can install Sphinx using :command:`pip`. Refer -to the :ref:`pip installation instructions <install-pypi>` below for more -information. - -__ https://docs.python-guide.org/ -__ https://docs.python-guide.org/starting/install3/win/ - - -.. _install-pypi: - -Installation from PyPI ----------------------- - -Sphinx packages are published on the `Python Package Index -<https://pypi.org/project/Sphinx/>`_. The preferred tool for installing -packages from *PyPI* is :command:`pip`. This tool is provided with all modern -versions of Python. - -On Linux or MacOS, you should open your terminal and run the following command. - -:: - - $ pip install -U sphinx - -On Windows, you should open *Command Prompt* (:kbd:`⊞Win-r` and type -:command:`cmd`) and run the same command. - -.. code-block:: doscon - - C:\> pip install -U sphinx - -After installation, type :command:`sphinx-build --version` on the command -prompt. If everything worked fine, you will see the version number for the -Sphinx package you just installed. - -Installation from *PyPI* also allows you to install the latest development -release. You will not generally need (or want) to do this, but it can be -useful if you see a possible bug in the latest stable release. To do this, use -the ``--pre`` flag. - -:: - - $ pip install -U --pre sphinx - -Using virtual environments -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When installing Sphinx using pip, -it is highly recommended to use *virtual environments*, -which isolate the installed packages from the system packages, -thus removing the need to use administrator privileges. -To create a virtual environment in the ``.venv`` directory, -use the following command. - -:: - - $ python -m venv .venv - -.. seealso:: :mod:`venv` -- creating virtual environments - -.. warning:: - - Note that in some Linux distributions, such as Debian and Ubuntu, - this might require an extra installation step as follows. - - .. code-block:: console - - $ apt-get install python3-venv - Docker ------ @@ -251,6 +228,17 @@ For more details, please read `README file`__ of docker images. .. __: https://hub.docker.com/r/sphinxdoc/sphinx +Installation of the latest development release +---------------------------------------------- + +You can install the latest development from *PyPI* using the ``--pre`` flag:: + + $ pip install -U --pre sphinx + +.. warning:: + + You will not generally need (or want) to do this, but it can be + useful if you see a possible bug in the latest stable release. Installation from source ------------------------ diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst index fcbfa80..774a581 100644 --- a/doc/usage/quickstart.rst +++ b/doc/usage/quickstart.rst @@ -54,7 +54,8 @@ to contain the root of the "table of contents tree" (or *toctree*). This is one of the main things that Sphinx adds to reStructuredText, a way to connect multiple files to a single hierarchy of documents. -.. sidebar:: reStructuredText directives +.. admonition:: reStructuredText directives + :class: note ``toctree`` is a reStructuredText :dfn:`directive`, a very versatile piece of markup. Directives can have arguments, options and content. @@ -95,7 +96,9 @@ documents to include are given as :term:`document name`\ s, which in short means that you leave off the file name extension and use forward slashes (``/``) as directory separators. -|more| Read more about :ref:`the toctree directive <toctree-directive>`. +.. seealso:: + + Read more about :ref:`the toctree directive <toctree-directive>`. You can now create the files you listed in the ``toctree`` and add content, and their section titles will be inserted (up to the ``maxdepth`` level) at the @@ -118,8 +121,11 @@ for this document -- use the "Show Source" link in the sidebar. .. todo:: Update the below link when we add new guides on these. -|more| See :doc:`/usage/restructuredtext/index` for a more in-depth -introduction to reStructuredText, including markup added by Sphinx. +.. seealso:: + + :doc:`/usage/restructuredtext/index` + for a more in-depth introduction to reStructuredText, + including markup added by Sphinx. Running the build @@ -137,8 +143,10 @@ directory in which you want to place the built documentation. The :option:`-M <sphinx-build -M>` option selects a builder; in this example Sphinx will build HTML files. -|more| Refer to the :doc:`sphinx-build man page </man/sphinx-build>` for all -options that :program:`sphinx-build` supports. +.. seealso:: + + Refer to the :doc:`sphinx-build man page </man/sphinx-build>` + for all options that :program:`sphinx-build` supports. However, :program:`sphinx-quickstart` script creates a :file:`Makefile` and a :file:`make.bat` which make life even easier for you. These can be executed by @@ -220,8 +228,10 @@ Each domain will have special rules for how the signatures can look like, and make the formatted output look pretty, or add specific features like links to parameter types, e.g. in the C/C++ domains. -|more| See :doc:`/usage/domains/index` for all the available domains -and their directives/roles. +.. seealso:: + + :doc:`/usage/domains/index` + for all the available domains and their directives/roles. Basic configuration @@ -245,8 +255,10 @@ Keep in mind that the file uses Python syntax for strings, numbers, lists and so on. The file is saved in UTF-8 by default, as indicated by the encoding declaration in the first line. -|more| See :doc:`/usage/configuration` for documentation of all available -config values. +.. seealso:: + + :doc:`/usage/configuration` + for documentation of all available config values. .. todo:: Move this entire doc to a different section @@ -259,42 +271,10 @@ source files, in documentation strings. Sphinx supports the inclusion of docstrings from your modules with an :dfn:`extension` (an extension is a Python module that provides additional features for Sphinx projects) called *autodoc*. -In order to use *autodoc*, you need to activate it in :file:`conf.py` by -putting the string ``'sphinx.ext.autodoc'`` into the list assigned to the -:confval:`extensions` config value:: - - extensions = ['sphinx.ext.autodoc'] - -Then, you have a few additional directives at your disposal. For example, to -document the function ``io.open()``, reading its signature and -docstring from the source file, you'd write this:: - - .. autofunction:: io.open - -You can also document whole classes or even modules automatically, using member -options for the auto directives, like :: +.. seealso:: - .. automodule:: io - :members: - -*autodoc* needs to import your modules in order to extract the docstrings. -Therefore, you must add the appropriate path to :py:data:`sys.path` in your -:file:`conf.py`. - -.. warning:: - - :mod:`~sphinx.ext.autodoc` **imports** the modules to be documented. If any - modules have side effects on import, these will be executed by ``autodoc`` - when ``sphinx-build`` is run. - - If you document scripts (as opposed to library modules), make sure their - main routine is protected by a ``if __name__ == '__main__'`` condition. - -|more| See :mod:`sphinx.ext.autodoc` for the complete description of the -features of autodoc. - - -.. todo:: Move this doc to another section + :mod:`sphinx.ext.autodoc` + for the complete description of the features of autodoc. Intersphinx ----------- @@ -322,8 +302,10 @@ download the list of valid targets). Intersphinx also works for some other :term:`domain`\'s roles including ``:ref:``, however it doesn't work for ``:doc:`` as that is non-domain role. -|more| See :mod:`sphinx.ext.intersphinx` for the complete description of the -features of intersphinx. +.. seealso:: + + :mod:`sphinx.ext.intersphinx` + for the complete description of the features of intersphinx. More topics to be covered @@ -342,7 +324,3 @@ More topics to be covered .. [#] This is the usual layout. However, :file:`conf.py` can also live in another directory, the :term:`configuration directory`. Refer to the :doc:`sphinx-build man page </man/sphinx-build>` for more information. - -.. |more| image:: /_static/more.png - :align: middle - :alt: more info diff --git a/doc/usage/referencing.rst b/doc/usage/referencing.rst index c2ad715..5761166 100644 --- a/doc/usage/referencing.rst +++ b/doc/usage/referencing.rst @@ -12,9 +12,10 @@ text will be the same as *target*. There are some additional facilities, however, that make cross-referencing roles more versatile: -* You may supply an explicit title and reference target, like in reST direct - hyperlinks: ``:role:`title <target>``` will refer to *target*, but the link - text will be *title*. +* You may supply an explicit title and reference target, + like in reStructuredText direct hyperlinks: + ``:role:`title <target>``` will refer to *target*, + but the link text will be *title*. * If you prefix the content with ``!``, no reference/hyperlink will be created. @@ -75,11 +76,11 @@ Cross-referencing objects These roles are described with their respective domains: -* :ref:`Python <python-roles>` -* :ref:`C <c-roles>` -* :ref:`C++ <cpp-roles>` -* :ref:`JavaScript <js-roles>` -* :ref:`ReST <rst-roles>` +* :ref:`Python <python-xref-roles>` +* :ref:`C <c-xref-roles>` +* :ref:`C++ <cpp-xref-roles>` +* :ref:`JavaScript <js-xref-roles>` +* :ref:`reStructuredText <rst-xref-roles>` .. _ref-role: @@ -89,10 +90,11 @@ Cross-referencing arbitrary locations .. rst:role:: ref - To support cross-referencing to arbitrary locations in any document, the - standard reST labels are used. For this to work label names must be unique - throughout the entire documentation. There are two ways in which you can - refer to labels: + To support cross-referencing to arbitrary locations in any document, + the standard reStructuredText labels are used. + For this to work label names must be unique + throughout the entire documentation. + There are two ways in which you can refer to labels: * If you place a label directly before a section title, you can reference to it with ``:ref:`label-name```. For example:: @@ -165,8 +167,9 @@ Referencing downloadable files .. rst:role:: download - This role lets you link to files within your source tree that are not reST - documents that can be viewed, but files that can be downloaded. + This role lets you link to files within your source tree + that are not reStructuredText documents that can be viewed, + but files that can be downloaded. When you use this role, the referenced file is automatically marked for inclusion in the output when building (obviously, for HTML output only). @@ -202,8 +205,9 @@ Cross-referencing figures by figure number .. rst:role:: numref - Link to the specified figures, tables, code-blocks and sections; the standard - reST labels are used. When you use this role, it will insert a reference to + Link to the specified figures, tables, code-blocks and sections; + the standard reStructuredText labels are used. + When you use this role, it will insert a reference to the figure with link text by its figure number like "Fig. 1.1". If an explicit link text is given (as usual: ``:numref:`Image of Sphinx (Fig. @@ -222,6 +226,13 @@ Cross-referencing other items of interest The following roles do possibly create a cross-reference, but do not refer to objects: +.. rst:role:: confval + + A configuration value or setting. + Index entries are generated. + Also generates a link to the matching :rst:dir:`confval` directive, + if it exists. + .. rst:role:: envvar An environment variable. Index entries are generated. Also generates a link diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst index 7aab544..5354748 100644 --- a/doc/usage/restructuredtext/basics.rst +++ b/doc/usage/restructuredtext/basics.rst @@ -9,24 +9,26 @@ reStructuredText Primer reStructuredText is the default plaintext markup language used by Sphinx. This section is a brief introduction to reStructuredText (reST) concepts and syntax, intended to provide authors with enough information to author documents -productively. Since reST was designed to be a simple, unobtrusive markup +productively. Since reStructuredText was designed to be a simple, unobtrusive markup language, this will not take too long. .. seealso:: The authoritative `reStructuredText User Documentation - <https://docutils.sourceforge.io/rst.html>`_. The "ref" links in this - document link to the description of the individual constructs in the reST - reference. + <https://docutils.sourceforge.io/rst.html>`_. + The "ref" links in this document link to the description of + the individual constructs in the reStructuredText reference. Paragraphs ---------- -The paragraph (:duref:`ref <paragraphs>`) is the most basic block in a reST -document. Paragraphs are simply chunks of text separated by one or more blank -lines. As in Python, indentation is significant in reST, so all lines of the -same paragraph must be left-aligned to the same level of indentation. +The paragraph (:duref:`ref <paragraphs>`) is the most basic block +in a reStructuredText document. +Paragraphs are simply chunks of text separated by one or more blank lines. +As in Python, indentation is significant in reStructuredText, +so all lines of the same paragraph must be left-aligned +to the same level of indentation. .. _rst-inline-markup: @@ -34,7 +36,7 @@ same paragraph must be left-aligned to the same level of indentation. Inline markup ------------- -The standard reST inline markup is quite simple: use +The standard reStructuredText inline markup is quite simple: use * one asterisk: ``*text*`` for emphasis (italics), * two asterisks: ``**text**`` for strong emphasis (boldface), and @@ -53,7 +55,7 @@ Be aware of some restrictions of this markup: These restrictions may be lifted in future versions of the docutils. It is also possible to replace or expand upon some of this inline markup with -roles. Refer to :ref:`rst-roles-alt` for more information. +roles. Refer to :ref:`rst-roles` for more information. Lists and Quote-like blocks @@ -220,8 +222,8 @@ You can also separate the link and the target definition (:duref:`ref Internal links ~~~~~~~~~~~~~~ -Internal linking is done via a special reST role provided by Sphinx, see the -section on specific markup, :ref:`ref-role`. +Internal linking is done via a special reStructuredText role provided by Sphinx, +see the section on specific markup, :ref:`ref-role`. .. _rst-sections: @@ -250,7 +252,7 @@ follow: * ``^`` for subsubsections * ``"`` for paragraphs -Of course, you are free to use your own marker characters (see the reST +Of course, you are free to use your own marker characters (see the reStructuredText documentation), and use a deeper nesting level, but keep in mind that most target formats (HTML, LaTeX) have a limited supported nesting depth. @@ -281,10 +283,7 @@ at the beginning of documents. Refer to :doc:`field-lists` for more information. -.. TODO This ref should be 'rst-roles', but that already exists. Rename the -.. other ones - -.. _rst-roles-alt: +.. _rst-roles: Roles ----- @@ -311,8 +310,8 @@ Refer to :doc:`roles` for roles added by Sphinx. Explicit Markup --------------- -"Explicit markup" (:duref:`ref <explicit-markup-blocks>`) is used in reST for -most constructs that need special handling, such as footnotes, +"Explicit markup" (:duref:`ref <explicit-markup-blocks>`) is used in +reStructuredText for most constructs that need special handling, such as footnotes, specially-highlighted paragraphs, comments, and generic directives. An explicit markup block begins with a line starting with ``..`` followed by @@ -328,8 +327,8 @@ Directives ---------- A directive (:duref:`ref <directives>`) is a generic block of explicit markup. -Along with roles, it is one of the extension mechanisms of reST, and Sphinx -makes heavy use of it. +Along with roles, it is one of the extension mechanisms of reStructuredText, +and Sphinx makes heavy use of it. Docutils supports the following directives: @@ -380,6 +379,12 @@ Docutils supports the following directives: When the default domain contains a ``class`` directive, this directive will be shadowed. Therefore, Sphinx re-exports it as ``rst-class``. + .. tip:: + + If you want to add a class to a directive, + you may consider the ``:class:`` :dudir:`option <common-options>` instead, + which is supported by most directives and allows for a more compact notation. + * HTML specifics: - :dudir:`meta` @@ -444,7 +449,7 @@ it does not start with a space. Images ------ -reST supports an image directive (:dudir:`ref <image>`), used like so:: +reStructuredText supports an image directive (:dudir:`ref <image>`), used like so:: .. image:: gnu.png (options) @@ -510,9 +515,9 @@ footnotes without names (``[#]_``). Citations --------- -Standard reST citations (:duref:`ref <citations>`) are supported, with the -additional feature that they are "global", i.e. all citations can be referenced -from all files. Use them like so:: +Standard reStructuredText citations (:duref:`ref <citations>`) are supported, +with the additional feature that they are "global", +i.e. all citations can be referenced from all files. Use them like so:: Lorem ipsum [Ref]_ dolor sit amet. @@ -525,9 +530,9 @@ numeric or begins with ``#``. Substitutions ------------- -reST supports "substitutions" (:duref:`ref <substitution-definitions>`), which -are pieces of text and/or markup referred to in the text by ``|name|``. They -are defined like footnotes with explicit markup blocks, like this:: +reStructuredText supports "substitutions" (:duref:`ref <substitution-definitions>`), +which are pieces of text and/or markup referred to in the text by ``|name|``. +They are defined like footnotes with explicit markup blocks, like this:: .. |name| replace:: replacement *text* @@ -536,8 +541,8 @@ or this:: .. |caution| image:: warning.png :alt: Warning! -See the :duref:`reST reference for substitutions <substitution-definitions>` -for details. +See the :duref:`reStructuredText reference for substitutions +<substitution-definitions>` for details. .. index:: ! pair: global; substitutions @@ -584,7 +589,7 @@ directive:: will generate the following HTML output: -.. code:: html +.. code-block:: html <meta name="description" content="The Sphinx documentation builder"> <meta name="keywords" content="Sphinx, documentation, builder"> @@ -612,7 +617,7 @@ Source encoding --------------- Since the easiest way to include special characters like em dashes or copyright -signs in reST is to directly write them as Unicode characters, one has to +signs in reStructuredText is to directly write them as Unicode characters, one has to specify an encoding. Sphinx assumes source files to be encoded in UTF-8 by default; you can change this with the :confval:`source_encoding` config value. @@ -620,7 +625,8 @@ default; you can change this with the :confval:`source_encoding` config value. Gotchas ------- -There are some problems one commonly runs into while authoring reST documents: +There are some problems one commonly runs into +while authoring reStructuredText documents: * **Separation of inline markup:** As said above, inline markup spans must be separated from the surrounding text by non-word characters, you have to use a diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst index ff42524..19079d2 100644 --- a/doc/usage/restructuredtext/directives.rst +++ b/doc/usage/restructuredtext/directives.rst @@ -24,10 +24,11 @@ Table of contents .. index:: pair: table of; contents -Since reST does not have facilities to interconnect several documents, or split -documents into multiple output files, Sphinx uses a custom directive to add -relations between the single files the documentation is made of, as well as -tables of contents. The ``toctree`` directive is the central element. +Since reStructuredText does not have facilities to interconnect several documents, +or split documents into multiple output files, +Sphinx uses a custom directive to add relations between +the single files the documentation is made of, as well as tables of contents. +The ``toctree`` directive is the central element. .. note:: @@ -37,7 +38,7 @@ tables of contents. The ``toctree`` directive is the central element. .. note:: To create table of contents for current document (.rst file), use the - standard reST :dudir:`contents directive <table-of-contents>`. + standard reStructuredText :dudir:`contents directive <table-of-contents>`. .. rst:directive:: toctree @@ -49,8 +50,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. @@ -79,7 +80,7 @@ tables of contents. The ``toctree`` directive is the central element. Document titles in the :rst:dir:`toctree` will be automatically read from the title of the referenced document. If that isn't what you want, you can - specify an explicit title and target using a similar syntax to reST + specify an explicit title and target using a similar syntax to reStructuredText hyperlinks (and Sphinx's :ref:`cross-referencing syntax <xref-syntax>`). This looks like:: @@ -124,6 +125,14 @@ tables of contents. The ``toctree`` directive is the central element. foo + As with :dudir:`most directives <common-options>`, + you can use the ``class`` option to assign `class attributes`_:: + + .. toctree:: + :class: custom-toc + + .. _class attributes: https://docutils.sourceforge.io/docs/ref/doctree.html#classes + If you want only the titles of documents in the tree to show up, not other headings of the same level, you can use the ``titlesonly`` option:: @@ -223,150 +232,327 @@ tables of contents. The ``toctree`` directive is the central element. Special names ^^^^^^^^^^^^^ +.. index:: pair: genindex; toctree + pair: modindex; toctree + pair: search; toctree + Sphinx reserves some document names for its own use; you should not try to create documents with these names -- it will cause problems. The special document names (and pages generated for them) are: -* ``genindex``, ``modindex``, ``search`` +* ``genindex`` - These are used for the general index, the Python module index, and the search - page, respectively. + This is used for the general index, + which is populated with entries from :rst:dir:`index` directives + and all index-generating :ref:`object descriptions <basic-domain-markup>`. + For example, see Sphinx's :ref:`genindex`. - The general index is populated with entries from modules, all - index-generating :ref:`object descriptions <basic-domain-markup>`, and from - :rst:dir:`index` directives. +* ``modindex`` - The Python module index contains one entry per :rst:dir:`py:module` - directive. + This is used for the Python module index, + which contains one entry per :rst:dir:`py:module` directive. + For example, see Sphinx's :ref:`py-modindex`. - The search page contains a form that uses the generated JSON search index and - JavaScript to full-text search the generated documents for search words; it - should work on every major browser that supports modern JavaScript. +* ``search`` -* every name beginning with ``_`` + This is used for the search page, + which contains a form that uses the generated JSON search index and JavaScript + to full-text search the generated documents for search words; + it works on every major browser. + For example, see Sphinx's :ref:`search`. - Though few such names are currently used by Sphinx, you should not - create documents or document-containing directories with such names. (Using - ``_`` as a prefix for a custom template directory is fine.) +* Every name beginning with ``_`` -.. warning:: + Though few such names are currently used by Sphinx, + you should not create documents or document-containing directories with such names. + (Using ``_`` as a prefix for a custom template directory is fine.) - Be careful with unusual characters in filenames. Some formats may interpret - these characters in unexpected ways: +.. warning:: - * Do not use the colon ``:`` for HTML based formats. Links to other parts - may not work. + Be careful with unusual characters in filenames. + Some formats may interpret these characters in unexpected ways: - * Do not use the plus ``+`` for the ePub format. Some resources may not be - found. + * Do not use the colon ``:`` for HTML based formats. + Links to other parts may not work. + * Do not use the plus ``+`` for the ePub format. + Some resources may not be found. Paragraph-level markup ---------------------- -.. index:: note, warning - pair: changes; in version - These directives create short paragraphs and can be used inside information units as well as normal text. + +Admonitions, messages, and warnings +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: admonition, admonitions + pair: attention; admonition + pair: caution; admonition + pair: danger; admonition + pair: error; admonition + pair: hint; admonition + pair: important; admonition + pair: note; admonition + pair: tip; admonition + pair: warning; admonition + +The admonition directives create 'admonition' elements, +a standardised system of communicating different types of information, +from a helpful :rst:dir:`tip` to matters of paramount :rst:dir:`danger`. +These directives can be used anywhere an ordinary body element can, +and can contain arbitrary body elements. +There are nine specific named admonitions +and the generic :rst:dir:`admonition` directive. + +.. rst:directive:: .. attention:: + + Information that requires the reader's attention. + The content of the directive should be written in complete sentences + and include all appropriate punctuation. + + Example: + + .. attention:: + + Please may I have your attention. + +.. rst:directive:: .. caution:: + + Information with regard to which the reader should exercise care. + The content of the directive should be written in complete sentences + and include all appropriate punctuation. + + Example: + + .. caution:: + + Exercise due caution. + +.. rst:directive:: .. danger:: + + Information which may lead to near and present danger if not heeded. + The content of the directive should be written in complete sentences + and include all appropriate punctuation. + + Example: + + .. danger:: + + Let none think to fly the danger for soon or late love is his own avenger. + +.. rst:directive:: .. error:: + + Information relating to failure modes of some description. + The content of the directive should be written in complete sentences + and include all appropriate punctuation. + + Example: + + .. error:: + + ERROR 418: I'm a teapot. + +.. rst:directive:: .. hint:: + + Information that is helpful to the reader. + The content of the directive should be written in complete sentences + and include all appropriate punctuation. + + Example: + + .. hint:: + + Look under the flowerpot. + +.. rst:directive:: .. important:: + + Information that is of paramount importance + and which the reader must not ignore. + The content of the directive should be written in complete sentences + and include all appropriate punctuation. + + Example: + + .. important:: + + This is a statement of paramount importance. + .. rst:directive:: .. note:: - An especially important bit of information about an API that a user should be - aware of when using whatever bit of API the note pertains to. The content of - the directive should be written in complete sentences and include all - appropriate punctuation. + An especially important bit of information that the reader should know. + The content of the directive should be written in complete sentences + and include all appropriate punctuation. - Example:: + Example: + + .. note:: + + This function is not suitable for sending tins of spam. + +.. rst:directive:: .. tip:: - .. note:: + Some useful tidbit of information for the reader. + The content of the directive should be written in complete sentences + and include all appropriate punctuation. - This function is not suitable for sending spam e-mails. + Example: + + .. tip:: + + Remember your sun cream! .. rst:directive:: .. warning:: - An important bit of information about an API that a user should be very aware - of when using whatever bit of API the warning pertains to. The content of - the directive should be written in complete sentences and include all - appropriate punctuation. This differs from :rst:dir:`note` in that it is - recommended over :rst:dir:`note` for information regarding security. + An important bit of information that the reader should be very aware of. + The content of the directive should be written in complete sentences + and include all appropriate punctuation. + + Example: -.. rst:directive:: .. versionadded:: version + .. warning:: + + Beware of the dog. + +.. rst:directive:: .. admonition:: title + + A generic admonition, with an optional title. + The content of the directive should be written in complete sentences + and include all appropriate punctuation. + + Example: + + .. admonition:: This is a title + + This is the content of the admonition. + + +.. rst:directive:: seealso + + Many sections include a list of references to module documentation or + external documents. + These lists are created using the :rst:dir:`seealso` directive. + + The :rst:dir:`!seealso` directive is typically placed in a section + just before any subsections. + The content of the :rst:dir:`seealso` directive should be + either a single line or a reStructuredText `definition list`_. - This directive documents the version of the project which added the described - feature to the library or C API. When this applies to an entire module, it - should be placed at the top of the module section before any prose. + .. _definition list: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#definition-lists + + Example:: + + .. seealso:: + + Python's :py:mod:`zipfile` module + Documentation of Python's standard :py:mod:`zipfile` module. + + `GNU tar manual, Basic Tar Format <https://example.org>`_ + Documentation for tar archive files, including GNU tar extensions. + + .. seealso:: + + Module :py:mod:`zipfile` + Documentation of the :py:mod:`zipfile` standard module. + + `GNU tar manual, Basic Tar Format <https://example.org>`_ + Documentation for tar archive files, including GNU tar extensions. + + +Describing changes between versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: pair: added; in version + pair: changes; in version + pair: removed; in version + +.. rst:directive:: .. versionadded:: version [brief explanation] + + This directive documents the version of the project + which added the described feature. + When this applies to an entire module or component, + it should be placed at the top of the relevant section before any prose. The first argument must be given and is the version in question; you can add a second argument consisting of a *brief* explanation of the change. + .. attention:: + There must be no blank line between the directive head and the explanation; + this is to make these blocks visually continuous in the markup. + Example:: .. versionadded:: 2.5 The *spam* parameter. - Note that there must be no blank line between the directive head and the - explanation; this is to make these blocks visually continuous in the markup. + .. versionadded:: 2.5 + The *spam* parameter. -.. rst:directive:: .. versionchanged:: version +.. rst:directive:: .. versionchanged:: version [brief explanation] Similar to :rst:dir:`versionadded`, but describes when and what changed in the named feature in some way (new parameters, changed side effects, etc.). -.. rst:directive:: .. deprecated:: version + Example:: - Similar to :rst:dir:`versionchanged`, but describes when the feature was - deprecated. An explanation can also be given, for example to inform the - reader what should be used instead. Example:: + .. versionchanged:: 2.8 + The *spam* parameter is now of type *boson*. - .. deprecated:: 3.1 - Use :func:`spam` instead. + .. versionchanged:: 2.8 + The *spam* parameter is now of type *boson*. -.. rst:directive:: .. versionremoved:: version +.. rst:directive:: .. deprecated:: version [brief explanation] + + Similar to :rst:dir:`versionadded`, but describes when the feature was + deprecated. + A *brief* explanation can also be given, + for example to tell the reader what to use instead. - Similar to :rst:dir:`versionadded`, but describes when the feature was removed. - An explanation may be provided to inform the reader what to use instead, - or why the feature was removed. Example:: - .. versionremoved:: 4.0 - The :func:`spam` function is more flexible, and should be used instead. + .. deprecated:: 3.1 + Use :py:func:`spam` instead. - .. versionadded:: 7.3 + .. deprecated:: 3.1 + Use :py:func:`!spam` instead. -.. rst:directive:: seealso +.. rst:directive:: .. versionremoved:: version [brief explanation] - Many sections include a list of references to module documentation or - external documents. These lists are created using the :rst:dir:`seealso` - directive. + Similar to :rst:dir:`versionadded`, but describes when the feature was removed. + An explanation may be provided to tell the reader what to use instead, + or why the feature was removed. - The :rst:dir:`seealso` directive is typically placed in a section just before - any subsections. For the HTML output, it is shown boxed off from the main - flow of the text. + .. versionadded:: 7.3 - The content of the :rst:dir:`seealso` directive should be a reST definition - list. Example:: + Example:: - .. seealso:: + .. versionremoved:: 4.0 + The :py:func:`spam` function is more flexible, and should be used instead. - Module :py:mod:`zipfile` - Documentation of the :py:mod:`zipfile` standard module. + .. versionremoved:: 4.0 + The :py:func:`!spam` function is more flexible, and should be used instead. - `GNU tar manual, Basic Tar Format <https://link>`_ - Documentation for tar archive files, including GNU tar extensions. - There's also a "short form" allowed that looks like this:: +Presentational +^^^^^^^^^^^^^^ + +.. rst:directive:: .. rubric:: title - .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile` + A rubric is like an informal heading that doesn't correspond to the document's structure, + i.e. it does not create a table of contents node. - .. versionadded:: 0.5 - The short form. + .. rst:directive:option:: heading-level: n + :type: number from 1 to 6 -.. rst:directive:: .. rubric:: title + .. versionadded:: 7.4.1 - This directive creates a paragraph heading that is not used to create a - table of contents node. + Use this option to specify the heading level of the rubric. + In this case the rubric will be rendered as ``<h1>`` to ``<h6>`` for HTML output, + or as the corresponding non-numbered sectioning command for LaTeX + (see :confval:`latex_toplevel_sectioning`). .. note:: @@ -377,10 +563,7 @@ units as well as normal text. .. rst:directive:: centered - This directive creates a centered boldfaced line of text. Use it as - follows:: - - .. centered:: LICENSE AGREEMENT + This directive creates a centered boldfaced line of text. .. deprecated:: 1.1 This presentation-only directive is a legacy from older versions. @@ -419,8 +602,8 @@ Showing code examples There are multiple ways to show syntax-highlighted literal code blocks in Sphinx: -* using :ref:`reST doctest blocks <rst-doctest-blocks>`; -* using :ref:`reST literal blocks <rst-literal-blocks>`, optionally in +* using :ref:`reStructuredText doctest blocks <rst-doctest-blocks>`; +* using :ref:`reStructuredText literal blocks <rst-literal-blocks>`, optionally in combination with the :rst:dir:`highlight` directive; * using the :rst:dir:`code-block` directive; * and using the :rst:dir:`literalinclude` directive. @@ -503,6 +686,7 @@ __ https://pygments.org/docs/lexers .. rst:directive:: .. code-block:: [language] .. sourcecode:: [language] + .. code:: [language] Example:: @@ -802,8 +986,8 @@ Glossary .. rst:directive:: .. glossary:: - This directive must contain a reST definition-list-like markup with terms and - definitions. The definitions will then be referenceable with the + This directive must contain a reStructuredText definition-list-like markup + with terms and definitions. The definitions will then be referenceable with the :rst:role:`term` role. Example:: .. glossary:: @@ -934,7 +1118,7 @@ mainly contained in information units, such as the language reference. (this notation is also used below to describe what entries are created). Examples: - .. code:: reStructuredText + .. code-block:: rst .. index:: single: execution single: execution; context @@ -947,7 +1131,7 @@ mainly contained in information units, such as the language reference. The pair of values must be separated by a semicolon. Example: - .. code:: reStructuredText + .. code-block:: rst .. index:: pair: loop; statement @@ -957,7 +1141,7 @@ mainly contained in information units, such as the language reference. All three values must be separated by a semicolon. Example: - .. code:: reStructuredText + .. code-block:: rst .. index:: triple: module; search; path @@ -967,7 +1151,7 @@ mainly contained in information units, such as the language reference. A shortcut to create an index entry that refers to another entry. Example: - .. code:: reStructuredText + .. code-block:: rst .. index:: see: entry; other @@ -1034,7 +1218,7 @@ mainly contained in information units, such as the language reference. case, the "target" part can be a full entry as described for the directive above. For example:: - This is a normal reST :index:`paragraph` that contains several + This is a normal reStructuredText :index:`paragraph` that contains several :index:`index entries <pair: index; entry>`. .. versionadded:: 1.1 @@ -1052,10 +1236,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 @@ -1287,8 +1472,8 @@ the definition of the symbol. There is this directive: an explicit title can be given (e.g., "``myTitle <myGroup:sum>``"), or the target can be prefixed with a tilde (e.g., "``~myGroup:sum``"). - Note that no further reST parsing is done in the production, so that you - don't have to escape ``*`` or ``|`` characters. + Note that no further reStructuredText parsing is done in the production, + so that you don't have to escape ``*`` or ``|`` characters. The following is an example taken from the Python Reference Manual:: diff --git a/doc/usage/restructuredtext/field-lists.rst b/doc/usage/restructuredtext/field-lists.rst index 62dad5c..d352633 100644 --- a/doc/usage/restructuredtext/field-lists.rst +++ b/doc/usage/restructuredtext/field-lists.rst @@ -48,9 +48,9 @@ At the moment, these metadata fields are recognized: .. note:: - This metadata effects to the depth of local toctree. But it does not - effect to the depth of *global* toctree. So this would not be change - the sidebar of some themes which uses global one. + This metadata affects the depth of the local toctree. But it does not + affect the depth of the *global* toctree. So this does not change + the sidebar of themes that use the global toctree. .. versionadded:: 0.4 diff --git a/doc/usage/restructuredtext/index.rst b/doc/usage/restructuredtext/index.rst index 0fe311e..ada40c5 100644 --- a/doc/usage/restructuredtext/index.rst +++ b/doc/usage/restructuredtext/index.rst @@ -8,9 +8,8 @@ reStructuredText (reST) is the default plaintext markup language used by both Docutils and Sphinx. Docutils provides the basic reStructuredText syntax, while Sphinx extends this to support additional functionality. -The below guides go through the most important aspects of reST. For the -authoritative reStructuredText reference, refer to the `docutils -documentation`__. +The below guides go through the most important aspects of reStructuredText. +For the authoritative reference, refer to the `docutils documentation`__. __ https://docutils.sourceforge.io/rst.html diff --git a/doc/usage/restructuredtext/roles.rst b/doc/usage/restructuredtext/roles.rst index b21a2b7..ea5d99c 100644 --- a/doc/usage/restructuredtext/roles.rst +++ b/doc/usage/restructuredtext/roles.rst @@ -268,7 +268,7 @@ The following roles generate external links: For example: :rfc:`2324` Note that there are no special roles for including hyperlinks as you can use -the standard reST markup for that purpose. +the standard reStructuredText markup for that purpose. .. _default-substitutions: diff --git a/doc/usage/theming.rst b/doc/usage/theming.rst index be46cab..135c2f5 100644 --- a/doc/usage/theming.rst +++ b/doc/usage/theming.rst @@ -22,7 +22,7 @@ Themes This section provides information about using pre-existing HTML themes. If you wish to create your own theme, refer to - :doc:`/development/theming`. + :ref:`extension-html-theme`. Sphinx supports changing the appearance of its HTML output via *themes*. A theme is a collection of HTML templates, stylesheet(s) and other static files. @@ -81,7 +81,7 @@ zipfile-based theme:: html_theme = "dotted" For more information on the design of themes, including information about -writing your own themes, refer to :doc:`/development/theming`. +writing your own themes, refer to :ref:`extension-html-theme`. .. _builtin-themes: |
