diff options
Diffstat (limited to 'doc')
142 files changed, 26560 insertions, 0 deletions
diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..84eafdb --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,20 @@ +# Makefile for Sphinx documentation +# +PYTHON ?= python3 + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = $(PYTHON) ../sphinx/cmd/build.py +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/_static/Makefile b/doc/_static/Makefile new file mode 100644 index 0000000..8c880bc --- /dev/null +++ b/doc/_static/Makefile @@ -0,0 +1,6 @@ +translation.png: translation.puml + plantuml -tpng $< +translation.svg: translation.puml + plantuml -tsvg $< +clean: + rm -f translation.png translation.svg diff --git a/doc/_static/bookcover.png b/doc/_static/bookcover.png Binary files differnew file mode 100644 index 0000000..0a8167f --- /dev/null +++ b/doc/_static/bookcover.png diff --git a/doc/_static/conf.py.txt b/doc/_static/conf.py.txt new file mode 100644 index 0000000..c5e75e0 --- /dev/null +++ b/doc/_static/conf.py.txt @@ -0,0 +1,346 @@ +# 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/favicon.svg b/doc/_static/favicon.svg new file mode 100644 index 0000000..c3e1acd --- /dev/null +++ b/doc/_static/favicon.svg @@ -0,0 +1,8 @@ +<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"> + <style> + @media (prefers-color-scheme: dark) { + svg { fill: white; } + } + </style> + <path d="m 67.780707,71.526216 c 0,-2.720856 0.735772,-7.633735 1.635035,-10.917507 2.076574,-7.582764 3.222746,-16.97568 2.071477,-16.97568 -0.485619,0 -3.994408,3.173002 -7.797313,7.051115 -14.448869,14.734603 -29.952812,23.068339 -42.915946,23.068339 -7.400211,0 -12.4298817,-1.871115 -17.2867007,-6.430912 -2.94436186,-2.764297 -3.47532146,-4.129685 -3.47532146,-8.936928 0,-4.94488 0.4862322,-6.108589 3.78321146,-9.054437 2.987989,-2.669773 4.875111,-3.380296 8.9779137,-3.380296 3.163221,0.711278 5.032659,0.664017 6.063532,1.917191 1.045041,1.231842 1.406892,5.262673 0.143323,7.623675 -0.674746,1.260763 -2.435471,2.043539 -4.5966,2.043539 -2.040303,0 -3.203991,-0.483702 -2.786976,-1.15844 1.31395,-2.126021 -0.560952,-3.566616 -2.9664067,-2.279256 -2.907025,1.555792 -2.957418,7.069066 -0.08839,9.665535 4.0345357,3.651203 15.1912207,5.023925 21.9019857,2.694828 7.250749,-2.516503 16.739014,-8.578986 24.30831,-15.531674 l 6.657407,-6.115083 -8.688303,-0.05007 C 43.622519,44.707714 37.702703,43.621524 18.54695,38.489741 12.175528,36.782852 6.0502733,35.306342 4.9352743,35.208608 3.6710803,35.097791 2.841723,34.067882 2.9080043,32.476074 3.0199286,29.788108 4.4800823,27.78768 6.2067673,27.033038 7.2437505,26.579828 14.43583,25.894406 22.0605,23.866486 c 29.699148,-7.899023 31.502043,-6.781254 51.28707,-1.772167 6.461504,1.635896 13.942408,3.414988 17.256961,3.474566 5.106245,0.09178 6.211825,0.514653 7.240255,2.76932 0.66758,1.46355 1.21378,2.858905 1.21378,3.10079 0,0.241884 -2.89333,1.764397 -6.429613,3.383363 -12.984983,5.944723 -17.083271,9.093943 -12.855172,15.130399 1.753219,2.503069 1.718037,2.768923 -0.57922,4.37799 -1.345193,0.942203 -2.457238,2.856456 -2.471232,4.253898 -0.03777,3.776976 -2.424786,11.884847 -5.893734,15.080164 l -3.048923,2.808424 z m 6.632814,-34.658372 c 5.169656,-1.440693 8.302047,-3.07045 14.72913,-6.500861 -5.292267,-1.548658 -18.570782,-3.724097 -18.570782,-3.724097 -9.796513,-1.964547 -8.76916,-1.865132 -9.21348,0.29669 -0.176673,0.859598 -0.702644,2.763948 -1.872329,4.596663 -2.251474,3.527711 -10.489307,4.271075 -15.214327,2.009703 -1.482367,-0.709454 -2.971272,-3.416276 -2.950606,-5.336922 0.02911,-2.705486 -1.505386,-3.336055 -2.486689,-2.975309 -0.796428,0.292781 -3.384665,0.330004 -9.071284,1.864262 -18.784765,5.068157 -21.3552119,4.487473 -9.110967,6.223299 1.472409,0.208739 9.252992,2.381926 13.052028,3.39412 9.318588,2.482796 11.064717,2.665087 23.125496,2.414247 8.385835,-0.174409 11.891174,-0.675356 17.58381,-2.261795 z M 3.0589449,14.916483 C 3.2921927,12.514245 3.424378,11.992797 10.100599,10.647894 13.924923,9.8774962 23.355266,7.3808108 31.056903,5.0997052 c 17.703937,-5.2436279 22.73392,-5.2565016 41.092202,-0.105175 7.923233,2.2232606 16.798382,4.047803 19.72254,4.054541 4.567242,0.01054 6.941892,2.0284768 6.941892,2.0284768 2.101843,4.825342 1.718463,5.158474 -6.484103,5.158474 -5.714193,0 -10.641875,-0.963081 -18.245438,-3.565943 C 68.300078,10.69012 60.060462,8.8316882 55.557963,8.4915615 47.342337,7.8709375 47.353713,7.8687835 21.963188,14.855617 17.503192,16.082896 11.34213,17.454164 8.2719268,17.902883 l -5.5821654,0.81585 z" /> +</svg> diff --git a/doc/_static/more.png b/doc/_static/more.png Binary files differnew file mode 100644 index 0000000..97553a8 --- /dev/null +++ b/doc/_static/more.png diff --git a/doc/_static/sphinx.png b/doc/_static/sphinx.png Binary files differnew file mode 100644 index 0000000..0a103cd --- /dev/null +++ b/doc/_static/sphinx.png diff --git a/doc/_static/themes/agogo.png b/doc/_static/themes/agogo.png Binary files differnew file mode 100644 index 0000000..5a09cb9 --- /dev/null +++ b/doc/_static/themes/agogo.png diff --git a/doc/_static/themes/alabaster.png b/doc/_static/themes/alabaster.png Binary files differnew file mode 100644 index 0000000..4a49c1a --- /dev/null +++ b/doc/_static/themes/alabaster.png diff --git a/doc/_static/themes/bizstyle.png b/doc/_static/themes/bizstyle.png Binary files differnew file mode 100644 index 0000000..e19fb6b --- /dev/null +++ b/doc/_static/themes/bizstyle.png diff --git a/doc/_static/themes/classic.png b/doc/_static/themes/classic.png Binary files differnew file mode 100644 index 0000000..3b3c9cb --- /dev/null +++ b/doc/_static/themes/classic.png diff --git a/doc/_static/themes/fullsize/agogo.png b/doc/_static/themes/fullsize/agogo.png Binary files differnew file mode 100644 index 0000000..106a16c --- /dev/null +++ b/doc/_static/themes/fullsize/agogo.png diff --git a/doc/_static/themes/fullsize/alabaster.png b/doc/_static/themes/fullsize/alabaster.png Binary files differnew file mode 100644 index 0000000..5eca209 --- /dev/null +++ b/doc/_static/themes/fullsize/alabaster.png diff --git a/doc/_static/themes/fullsize/bizstyle.png b/doc/_static/themes/fullsize/bizstyle.png Binary files differnew file mode 100644 index 0000000..5860647 --- /dev/null +++ b/doc/_static/themes/fullsize/bizstyle.png diff --git a/doc/_static/themes/fullsize/classic.png b/doc/_static/themes/fullsize/classic.png Binary files differnew file mode 100644 index 0000000..269dab2 --- /dev/null +++ b/doc/_static/themes/fullsize/classic.png diff --git a/doc/_static/themes/fullsize/haiku.png b/doc/_static/themes/fullsize/haiku.png Binary files differnew file mode 100644 index 0000000..707d2bf --- /dev/null +++ b/doc/_static/themes/fullsize/haiku.png diff --git a/doc/_static/themes/fullsize/nature.png b/doc/_static/themes/fullsize/nature.png Binary files differnew file mode 100644 index 0000000..00730c0 --- /dev/null +++ b/doc/_static/themes/fullsize/nature.png diff --git a/doc/_static/themes/fullsize/pyramid.png b/doc/_static/themes/fullsize/pyramid.png Binary files differnew file mode 100644 index 0000000..3b9d04d --- /dev/null +++ b/doc/_static/themes/fullsize/pyramid.png diff --git a/doc/_static/themes/fullsize/scrolls.png b/doc/_static/themes/fullsize/scrolls.png Binary files differnew file mode 100644 index 0000000..8a1c1fa --- /dev/null +++ b/doc/_static/themes/fullsize/scrolls.png diff --git a/doc/_static/themes/fullsize/sphinx_rtd_theme.png b/doc/_static/themes/fullsize/sphinx_rtd_theme.png Binary files differnew file mode 100644 index 0000000..95cff4c --- /dev/null +++ b/doc/_static/themes/fullsize/sphinx_rtd_theme.png diff --git a/doc/_static/themes/fullsize/sphinxdoc.png b/doc/_static/themes/fullsize/sphinxdoc.png Binary files differnew file mode 100644 index 0000000..eb498e3 --- /dev/null +++ b/doc/_static/themes/fullsize/sphinxdoc.png diff --git a/doc/_static/themes/fullsize/traditional.png b/doc/_static/themes/fullsize/traditional.png Binary files differnew file mode 100644 index 0000000..07ad008 --- /dev/null +++ b/doc/_static/themes/fullsize/traditional.png diff --git a/doc/_static/themes/haiku.png b/doc/_static/themes/haiku.png Binary files differnew file mode 100644 index 0000000..4530deb --- /dev/null +++ b/doc/_static/themes/haiku.png diff --git a/doc/_static/themes/nature.png b/doc/_static/themes/nature.png Binary files differnew file mode 100644 index 0000000..ad39b32 --- /dev/null +++ b/doc/_static/themes/nature.png diff --git a/doc/_static/themes/pyramid.png b/doc/_static/themes/pyramid.png Binary files differnew file mode 100644 index 0000000..72749dd --- /dev/null +++ b/doc/_static/themes/pyramid.png diff --git a/doc/_static/themes/scrolls.png b/doc/_static/themes/scrolls.png Binary files differnew file mode 100644 index 0000000..1a11737 --- /dev/null +++ b/doc/_static/themes/scrolls.png diff --git a/doc/_static/themes/sphinx_rtd_theme.png b/doc/_static/themes/sphinx_rtd_theme.png Binary files differnew file mode 100644 index 0000000..7c3b7ae --- /dev/null +++ b/doc/_static/themes/sphinx_rtd_theme.png diff --git a/doc/_static/themes/sphinxdoc.png b/doc/_static/themes/sphinxdoc.png Binary files differnew file mode 100644 index 0000000..587363e --- /dev/null +++ b/doc/_static/themes/sphinxdoc.png diff --git a/doc/_static/themes/traditional.png b/doc/_static/themes/traditional.png Binary files differnew file mode 100644 index 0000000..9820fd0 --- /dev/null +++ b/doc/_static/themes/traditional.png diff --git a/doc/_static/translation.png b/doc/_static/translation.png Binary files differnew file mode 100644 index 0000000..002b3d1 --- /dev/null +++ b/doc/_static/translation.png diff --git a/doc/_static/translation.puml b/doc/_static/translation.puml new file mode 100644 index 0000000..7b8fc9f --- /dev/null +++ b/doc/_static/translation.puml @@ -0,0 +1,16 @@ +@startuml +file "SphinxProject" +file ".rst" +database ".pot" +database ".po" +database ".mo" +actor translator +file TranslatedBuild +translator -l-> .po +SphinxProject -r-> .rst +.rst -r-> .pot : sphinx-build gettext +.pot -r-> .po : Pootle +.po -d-> .mo : msgfmt +.mo -l-> TranslatedBuild +.rst -d-> TranslatedBuild : "sphinx-build -Dlanguage=" +@enduml diff --git a/doc/_static/translation.svg b/doc/_static/translation.svg new file mode 100644 index 0000000..4e3ab5a --- /dev/null +++ b/doc/_static/translation.svg @@ -0,0 +1,42 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentScriptType="application/ecmascript" contentStyleType="text/css" height="223px" preserveAspectRatio="none" style="width:637px;height:223px;" version="1.1" viewBox="0 0 637 223" width="637px" zoomAndPan="magnify"><defs><filter height="300%" id="fh7abla96c8rb" width="300%" x="-1" y="-1"><feGaussianBlur result="blurOut" stdDeviation="2.0"/><feColorMatrix in="blurOut" result="blurOut2" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .4 0"/><feOffset dx="4.0" dy="4.0" in="blurOut2" result="blurOut3"/><feBlend in="SourceGraphic" in2="blurOut3" mode="normal"/></filter></defs><g><!--MD5=[631d54569d64dd7be7afb1602a233020] +entity SphinxProject--><polygon fill="#FEFECE" filter="url(#fh7abla96c8rb)" points="6,30.5,6,66.7969,120,66.7969,120,40.5,110,30.5,6,30.5" style="stroke: #000000; stroke-width: 1.5;"/><path d="M110,30.5 L110,40.5 L120,40.5 " fill="#FEFECE" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="94" x="16" y="53.4951">SphinxProject</text><!--MD5=[61096c0d57626e43fed95496d4441932] +entity .rst--><polygon fill="#FEFECE" filter="url(#fh7abla96c8rb)" points="155,30.5,155,66.7969,197,66.7969,197,40.5,187,30.5,155,30.5" style="stroke: #000000; stroke-width: 1.5;"/><path d="M187,30.5 L187,40.5 L197,40.5 " fill="#FEFECE" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="22" x="165" y="53.4951">.rst</text><!--MD5=[08ed079d9b091f9ed2d220f9f6abc033] +entity .pot--><path d="M359.5,36 C359.5,26 383,26 383,26 C383,26 406.5,26 406.5,36 L406.5,61.2969 C406.5,71.2969 383,71.2969 383,71.2969 C383,71.2969 359.5,71.2969 359.5,61.2969 L359.5,36 " fill="#FEFECE" filter="url(#fh7abla96c8rb)" style="stroke: #000000; stroke-width: 1.5;"/><path d="M359.5,36 C359.5,46 383,46 383,46 C383,46 406.5,46 406.5,36 " fill="none" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="27" x="369.5" y="62.9951">.pot</text><!--MD5=[66eca29884632d3929c321eae20b9288] +entity .po--><path d="M483,36 C483,26 504,26 504,26 C504,26 525,26 525,36 L525,61.2969 C525,71.2969 504,71.2969 504,71.2969 C504,71.2969 483,71.2969 483,61.2969 L483,36 " fill="#FEFECE" filter="url(#fh7abla96c8rb)" style="stroke: #000000; stroke-width: 1.5;"/><path d="M483,36 C483,46 504,46 504,46 C504,46 525,46 525,36 " fill="none" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="22" x="493" y="62.9951">.po</text><!--MD5=[fad5092d1b513ed9e4cd2391fb0fb212] +entity .mo--><path d="M398,176 C398,166 421,166 421,166 C421,166 444,166 444,176 L444,201.2969 C444,211.2969 421,211.2969 421,211.2969 C421,211.2969 398,211.2969 398,201.2969 L398,176 " fill="#FEFECE" filter="url(#fh7abla96c8rb)" style="stroke: #000000; stroke-width: 1.5;"/><path d="M398,176 C398,186 421,186 421,186 C421,186 444,186 444,176 " fill="none" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="26" x="408" y="202.9951">.mo</text><!--MD5=[8f276d451ff344d4b5b89d896332ffcd] +entity translator--><ellipse cx="593" cy="17.5" fill="#FEFECE" filter="url(#fh7abla96c8rb)" rx="8" ry="8" style="stroke: #A80036; stroke-width: 1.5;"/><path d="M593,25.5 L593,52.5 M580,33.5 L606,33.5 M593,52.5 L580,67.5 M593,52.5 L606,67.5 " fill="none" filter="url(#fh7abla96c8rb)" style="stroke: #A80036; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="65" x="560.5" y="85.9951">translator</text><!--MD5=[ba0f3816bcb6df458d88626e193b44ee] +entity TranslatedBuild--><polygon fill="#FEFECE" filter="url(#fh7abla96c8rb)" points="214.5,170.5,214.5,206.7969,341.5,206.7969,341.5,180.5,331.5,170.5,214.5,170.5" style="stroke: #000000; stroke-width: 1.5;"/><path d="M331.5,170.5 L331.5,180.5 L341.5,180.5 " fill="#FEFECE" style="stroke: #000000; stroke-width: 1.5;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="107" x="224.5" y="193.4951">TranslatedBuild</text><!--MD5=[2a0f0d8c54238b3eb600ae284aca39d2] +reverse link .po to translator--><path d="M530.44,48.5 C540.43,48.5 550.43,48.5 560.43,48.5 " fill="none" id=".po<-translator" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="525.21,48.5,534.21,52.5,530.21,48.5,534.21,44.5,525.21,48.5" style="stroke: #A80036; stroke-width: 1.0;"/><!--MD5=[25ad71f3d3609323ec521914d1dc498d] +link SphinxProject to .rst--><path d="M120.38,48.5 C130.13,48.5 139.87,48.5 149.61,48.5 " fill="none" id="SphinxProject->.rst" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="154.71,48.5,145.71,44.5,149.71,48.5,145.71,52.5,154.71,48.5" style="stroke: #A80036; stroke-width: 1.0;"/><!--MD5=[1109e8764a7297dc8aca732b1794aa90] +link .rst to .pot--><path d="M197.37,48.5 C234.72,48.5 311.88,48.5 354,48.5 " fill="none" id=".rst->.pot" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="359.21,48.5,350.21,44.5,354.21,48.5,350.21,52.5,359.21,48.5" style="stroke: #A80036; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="126" x="215.25" y="41.5669">sphinx-build gettext</text><!--MD5=[c2d0ba229470f335ea07ab2ed6b28ec0] +link .pot to .po--><path d="M406.62,48.5 C427.03,48.5 456.51,48.5 477.68,48.5 " fill="none" id=".pot->.po" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="482.87,48.5,473.87,44.5,477.87,48.5,473.87,52.5,482.87,48.5" style="stroke: #A80036; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="40" x="424.75" y="41.5669">Pootle</text><!--MD5=[06651b5914fbf4764a077bbac7efe19a] +link .po to .mo--><path d="M491.03,71.06 C476.38,95.43 452.52,135.09 436.8,161.24 " fill="none" id=".po->.mo" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="434.15,165.63,442.2104,159.9705,436.7225,161.3425,435.3505,155.8546,434.15,165.63" style="stroke: #A80036; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="50" x="462" y="132.0669">msgfmt</text><!--MD5=[02fa75427086f2cebad4a5f1b2dd96dd] +reverse link TranslatedBuild to .mo--><path d="M346.94,188.5 C363.88,188.5 380.82,188.5 397.76,188.5 " fill="none" id="TranslatedBuild<-.mo" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="341.68,188.5,350.68,192.5,346.68,188.5,350.68,184.5,341.68,188.5" style="stroke: #A80036; stroke-width: 1.0;"/><!--MD5=[e72b6258a50343d4926d984a36170cf2] +link .rst to TranslatedBuild--><path d="M188.71,66.7 C207.27,91.8 241.75,138.46 262,165.86 " fill="none" id=".rst->TranslatedBuild" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="265.13,170.08,262.9905,160.4663,262.1552,166.0612,256.5604,165.226,265.13,170.08" style="stroke: #A80036; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="165" x="241" y="132.0669">sphinx-build -Dlanguage=</text><!--MD5=[30dba34f254541587149d90abdb00688] +@startuml
+file "SphinxProject"
+file ".rst"
+database ".pot"
+database ".po"
+database ".mo"
+actor translator
+file TranslatedBuild
+translator -l-> .po
+SphinxProject -r-> .rst
+.rst -r-> .pot : sphinx-build gettext
+.pot -r-> .po : Pootle
+.po -d-> .mo : msgfmt
+.mo -l-> TranslatedBuild
+.rst -d-> TranslatedBuild : "sphinx-build -Dlanguage="
+@enduml
+ +PlantUML version 1.2020.00(Sat Jan 11 12:30:53 GMT 2020) +(GPL source distribution) +Java Runtime: OpenJDK Runtime Environment +JVM: OpenJDK 64-Bit Server VM +Java Version: 1.8.0_252-b09 +Operating System: Linux +Default Encoding: UTF-8 +Language: en +Country: null +--></g></svg>
\ No newline at end of file diff --git a/doc/_static/tutorial/lumache-autosummary.png b/doc/_static/tutorial/lumache-autosummary.png Binary files differnew file mode 100644 index 0000000..ed54ea3 --- /dev/null +++ b/doc/_static/tutorial/lumache-autosummary.png diff --git a/doc/_static/tutorial/lumache-first-light.png b/doc/_static/tutorial/lumache-first-light.png Binary files differnew file mode 100644 index 0000000..fbf4aec --- /dev/null +++ b/doc/_static/tutorial/lumache-first-light.png diff --git a/doc/_static/tutorial/lumache-furo.png b/doc/_static/tutorial/lumache-furo.png Binary files differnew file mode 100644 index 0000000..c7aaee7 --- /dev/null +++ b/doc/_static/tutorial/lumache-furo.png diff --git a/doc/_static/tutorial/lumache-py-function-full.png b/doc/_static/tutorial/lumache-py-function-full.png Binary files differnew file mode 100644 index 0000000..d13b637 --- /dev/null +++ b/doc/_static/tutorial/lumache-py-function-full.png diff --git a/doc/_static/tutorial/lumache-py-function.png b/doc/_static/tutorial/lumache-py-function.png Binary files differnew file mode 100644 index 0000000..06129d5 --- /dev/null +++ b/doc/_static/tutorial/lumache-py-function.png diff --git a/doc/_templates/contents.html b/doc/_templates/contents.html new file mode 100644 index 0000000..5eefe4e --- /dev/null +++ b/doc/_templates/contents.html @@ -0,0 +1,8 @@ +{% extends "layout.html" %} +{% set title = _('Sphinx documentation contents') %} +{% block body %} +<h1>{{ _('Sphinx documentation contents') }}</h1> +<div class="toctree-wrapper compound"> +{{ toctree(includehidden=True, collapse=False, maxdepth=3) }} +</div> +{% endblock %} diff --git a/doc/_themes/sphinx13/layout.html b/doc/_themes/sphinx13/layout.html new file mode 100644 index 0000000..86a7943 --- /dev/null +++ b/doc/_themes/sphinx13/layout.html @@ -0,0 +1,60 @@ +{# Sphinx layout template for the sphinxdoc theme. #} +{%- extends "basic/layout.html" %} + +{% block extrahead %} +{{ super() }} +{%- if not embedded and pagename == 'index' %} +<style>.related { display: none; }</style> +{%- endif %} +{% endblock %} + +{% block header %} +<div class="pageheader"> +<a href="{{ pathto('index') }}"> + <img src="{{ pathto('_static/sphinxheader.png', 1) }}" alt="SPHINX" /> +</a> +</div> +{% endblock %} + +{%- block relbar1 %} +<div class="related" role="navigation" aria-label="related navigation"> + <h3>{{ _('Navigation') }}</h3> + <ul> + <li><a href="{{ pathto('index') }}">Documentation</a> »</li> + {%- for parent in parents %} + <li class="nav-item nav-item-{{ loop.index }}"><a href="{{ parent.link|e }}" {% if loop.last %}{{ accesskey("U") }}{% endif %}>{{ parent.title }}</a>{{ reldelim1 }}</li> + {%- endfor %} + <li class="nav-item nav-item-this"><a href="{{ link|e }}">{{ title }}</a></li> + </ul> +</div> +{% endblock %} + +{%- block content %} +<div class="document"> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + {%- include "searchfield.html" %} + <div class="sphinxsidebar-navigation__contents"> + <h3>{{ _('On this page') }}</h3> + {{ toc }} + </div> + <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 %} + </div> + {%- endblock %} +</div> +{%- endblock %} + +{%- block relbar2 %}{% endblock %} + +{%- block footer %} +<div class="footer" role="contentinfo"> + {{ copyright_block() }} + {% trans sphinx_version=sphinx_version|e %}Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %} +</div> +{%- endblock %} diff --git a/doc/_themes/sphinx13/static/sphinx13.css b/doc/_themes/sphinx13/static/sphinx13.css new file mode 100644 index 0000000..674d211 --- /dev/null +++ b/doc/_themes/sphinx13/static/sphinx13.css @@ -0,0 +1,362 @@ +/* Stylesheet for Sphinx's documentation */ + +/* Set master colours */ +:root { + --fonts-sans-serif: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji"; + --colour-sphinx-blue: #0A507A; + --colour-text: #333; + --colour-links-light: #057; +} + +body { + font-family: var(--fonts-sans-serif); + margin: 0 auto; + color: var(--colour-text); +} + +.pageheader { + background-color: var(--colour-sphinx-blue); + padding: 10px 15px; +} + +div.document { + display: flex; + margin: 0 0.5em; +} + +div.body { + border-left: 1px solid var(--colour-sphinx-blue); + margin: 0; + padding: 0.5em 1.75em; + min-width: 0; + max-width: 800px; +} + +div.related { + display: flex; + color: white; + background-color: var(--colour-sphinx-blue); + border-top: 1px solid #002e50; +} + +div.related ul li { + margin: 0 5px 0 0; + float: left; +} + +div.related ul li a { + padding: 0 5px 0 5px; + line-height: 1.75em; + color: white; +} + +div.related ul li a:hover { + text-shadow: 0 0 1px rgba(255, 255, 255, 0.5); +} + +div.sphinxsidebarwrapper { + padding: 0; +} + +div.sphinxsidebar { + position: sticky; + top: 0; + align-self: flex-start; + height: 100vh; + width: 250px; + overflow-y: auto; + overflow-wrap: break-word; + margin: 0; + padding-right: 15px; + padding-top: 0.5em; + font-size: 1em; +} + +div.sphinxsidebar h3 { + font-size: 1.5em; + margin-top: 0; + margin-bottom: 0.5em; + padding-top: 0.5em; +} + +div.sphinxsidebar h4 { + font-size: 1.2em; + margin-bottom: 0; +} + +div.sphinxsidebar h3, div.sphinxsidebar h4 { + margin-right: -15px; + margin-left: -15px; + padding-right: 14px; + padding-left: 14px; + color: #333; + font-weight: 300; +} + +div.sphinxsidebar h3 a { + color: #333; +} + +div.sphinxsidebar ul { + color: #444; + margin-top: 7px; + padding: 0; + line-height: 130%; +} + +div.sphinxsidebar ul ul { + margin-left: 1rem; + list-style-type: none; + font-size: .9em; +} + +/* De-dent the first list because we hide the top-level item */ +.sphinxsidebar .sphinxsidebar-navigation__contents > ul > li > ul { + margin-left: 0; +} + +div.sphinxsidebar p.caption { + font-weight: 300; + font-size: 1.2rem; +} + +div.sphinxsidebar li.current > a { + font-weight: 600; +} + +.sphinxsidebar-navigation__contents > ul > li > a { + display: none; +} + +div.sphinxsidebar #searchbox { + margin: 12px 0 20px 0; +} + +div.footer { + background-color: var(--colour-sphinx-blue); + color: #ccc; + text-shadow: 0 0 .2px rgba(255, 255, 255, 0.8); + padding: 3px 8px 3px 8px; + clear: both; + font-size: 0.8em; +} + +/* no need to make a visible link to Sphinx on the Sphinx page */ +div.footer a { + color: #ccc; +} + +/* -- body styles ----------------------------------------------------------- */ + +p { + margin: 0.8em 0 0.5em 0; +} + +a { + color: var(--colour-links-light); + text-decoration: none; +} + +div.body a { + text-decoration: underline; +} + +h1 { + margin: 10px 0 0 0; + font-size: 2.4em; + color: var(--colour-sphinx-blue); + font-weight: 300; +} + +h1 span.pre { + /* for code in titles */ + word-break: break-all; + white-space: normal; +} + +h2 { + margin: 1em 0 0.2em 0; + font-size: 1.5em; + font-weight: 300; + padding: 0; + color: #174967; +} + +h3 { + margin: 1em 0 -0.3em 0; + font-size: 1.3em; + font-weight: 300; +} + +div.body h1 a, div.body h2 a, div.body h3 a, div.body h4 a, div.body h5 a, div.body h6 a { + text-decoration: none; +} + +div.body h1 a tt, div.body h2 a tt, div.body h3 a tt, div.body h4 a tt, div.body h5 a tt, div.body h6 a tt { + color: var(--colour-sphinx-blue) !important; + font-size: inherit !important; +} + +a.headerlink { + color: var(--colour-sphinx-blue) !important; + font-size: .8em; + margin-left: 6px; + padding: 0 4px 0 4px; + text-decoration: none !important; +} + +a.headerlink:hover { + background-color: #ccc; + color: white!important; +} + +/* avoid font-size when :mod: role in headings */ +h1 code, h2 code, h3 code, h4 code { + font-size: inherit; +} + +cite, code, tt { + font-family: 'Consolas', 'DejaVu Sans Mono', + 'Bitstream Vera Sans Mono', monospace; + font-size: 1em; + letter-spacing: -0.02em; +} + +table.deprecated code.literal { + word-break: break-all; +} + +tt { + background-color: #f2f2f2; + border: 1px solid #ddd; + border-radius: 2px; + color: #333; + padding: 1px 0.2em; +} + +tt.descname, tt.descclassname, tt.xref { + border: 0; +} + +hr { + border: 1px solid #abc; + margin: 2em; +} + +a tt { + border: 0; + color: var(--colour-links-light); +} + +pre { + font-family: 'Consolas', 'Courier New', 'DejaVu Sans Mono', + 'Bitstream Vera Sans Mono', monospace; + font-size: 1em; + letter-spacing: 0.015em; + line-height: 120%; + padding: 0.5em; + border: 1px solid #ccc; + border-radius: 2px; + background-color: #f8f8f8; +} + +pre a { + color: inherit; + text-decoration: underline; +} + +td.linenos pre { + padding: 0.5em 0; +} + +div.quotebar { + background-color: #f8f8f8; + max-width: 250px; + float: right; + padding: 0px 7px; + border: 1px solid #ccc; + margin-left: 1em; +} + +blockquote.epigraph { + font-size: 1.5em; + padding-left: 1rem; + margin-left: 0; +} + +nav.contents, +div.topic, +aside.topic { + background-color: #f8f8f8; +} + +table { + border-collapse: collapse; + margin: 0 -0.5em 0 -0.5em; +} + +table td, table th { + padding: 0.2em 0.5em 0.2em 0.5em; +} + +div.admonition, div.warning { + font-size: 0.9em; + margin: 1em 0 1em 0; + border: 1px solid #86989B; + border-radius: 2px; + background-color: #f7f7f7; + padding: 1rem; +} + +div.admonition > p, div.warning > p { + margin: 0; + padding: 0; +} + +div.admonition > pre, div.warning > pre { + margin: 0.4em 1em 0.4em 1em; +} + +div.admonition > p.admonition-title, +div.warning > p.admonition-title { + font-weight: bold; +} + +div.warning { + border: 1px solid #940000; +} + +div.admonition > ul, +div.admonition > ol, +div.warning > ul, +div.warning > ol { + margin: 0.1em 0.5em 0.5em 3em; + padding: 0; +} + +div.admonition div.highlight { + background: none; +} + +.viewcode-back { + font-family: var(--fonts-sans-serif); +} + +div.viewcode-block:target { + background-color: #f4debf; + border-top: 1px solid #ac9; + border-bottom: 1px solid #ac9; +} + + +/* media queries */ + +/* Reduce padding & margins for smaller screens */ +@media (max-width: 750px) { + .sphinxsidebar { + display: none; + } + div.body { + border-left: none; + } +} diff --git a/doc/_themes/sphinx13/static/sphinxheader.png b/doc/_themes/sphinx13/static/sphinxheader.png Binary files differnew file mode 100644 index 0000000..845da4a --- /dev/null +++ b/doc/_themes/sphinx13/static/sphinxheader.png diff --git a/doc/_themes/sphinx13/theme.conf b/doc/_themes/sphinx13/theme.conf new file mode 100644 index 0000000..78bb78f --- /dev/null +++ b/doc/_themes/sphinx13/theme.conf @@ -0,0 +1,4 @@ +[theme] +inherit = basic +pygments_style = default +sidebars = diff --git a/doc/authors.rst b/doc/authors.rst new file mode 100644 index 0000000..411835b --- /dev/null +++ b/doc/authors.rst @@ -0,0 +1,9 @@ +:tocdepth: 2 + +.. _authors: + +============== +Sphinx authors +============== + +.. include:: ../AUTHORS diff --git a/doc/changes.rst b/doc/changes.rst new file mode 100644 index 0000000..96853fe --- /dev/null +++ b/doc/changes.rst @@ -0,0 +1,22 @@ +:tocdepth: 1 + +.. default-role:: any + +.. _changes: + +========= +Changelog +========= + +.. raw:: latex + + \addtocontents{toc}{\protect\setcounter{tocdepth}{1}}% + \makeatletter + \addtocontents{toc}% + {\def\string\l@section{\string\@dottedtocline{1}{1.5em}{3.3em}}} + \addtocontents{toc}% + {\def\string\l@subsection{\string\@dottedtocline{2}{4.8em}{4em}}} + \makeatother + + +.. include:: ../CHANGES diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..d4915aa --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,244 @@ +# Sphinx documentation build configuration file + +import os +import re +import time + +import sphinx + +os.environ['SPHINX_AUTODOC_RELOAD_MODULES'] = '1' + +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', + 'sphinx.ext.autosummary', 'sphinx.ext.extlinks', + 'sphinx.ext.intersphinx', + 'sphinx.ext.viewcode', 'sphinx.ext.inheritance_diagram', + 'sphinx.ext.coverage'] +coverage_statistics_to_report = coverage_statistics_to_stdout = True +templates_path = ['_templates'] +exclude_patterns = ['_build'] + +project = 'Sphinx' +copyright = f'2007-{time.strftime("%Y")}, the Sphinx developers' +version = sphinx.__display_version__ +release = version +show_authors = True + +html_theme = 'sphinx13' +html_theme_path = ['_themes'] +html_css_files = [ + # 'basic.css', # included through inheritance from the basic theme + 'sphinx13.css', +] +modindex_common_prefix = ['sphinx.'] +html_static_path = ['_static'] +html_title = 'Sphinx documentation' +html_additional_pages = {'contents': 'contents.html'} +html_use_opensearch = 'https://www.sphinx-doc.org/en/master' +html_baseurl = 'https://www.sphinx-doc.org/en/master/' +html_favicon = '_static/favicon.svg' + +htmlhelp_basename = 'Sphinxdoc' + +epub_theme = 'epub' +epub_basename = 'sphinx' +epub_author = 'the Sphinx developers' +epub_publisher = 'https://www.sphinx-doc.org/' +epub_uid = 'web-site' +epub_scheme = 'url' +epub_identifier = epub_publisher +epub_pre_files = [('index.xhtml', 'Welcome')] +epub_post_files = [('usage/installation.xhtml', 'Installing Sphinx'), + ('develop.xhtml', 'Sphinx development')] +epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js', + '_static/searchtools.js', + '_static/sphinx_highlight.js', + '_static/basic.css', + '_static/language_data.js', + 'search.html', '_static/websupport.js'] +epub_fix_images = False +epub_max_image_width = 0 +epub_show_urls = 'inline' +epub_use_index = False +epub_description = 'Sphinx documentation generator system manual' + +latex_documents = [('index', 'sphinx.tex', 'Sphinx Documentation', + 'the Sphinx developers', 'manual', 1)] +latex_logo = '_static/sphinx.png' +latex_elements = { + 'fontenc': r'\usepackage[LGR,X2,T1]{fontenc}', + 'passoptionstopackages': r''' +\PassOptionsToPackage{svgnames}{xcolor} +''', + 'preamble': r''' +\DeclareUnicodeCharacter{229E}{\ensuremath{\boxplus}} +\setcounter{tocdepth}{3}% depth of what main TOC shows (3=subsubsection) +\setcounter{secnumdepth}{1}% depth of section numbering +\setlength{\tymin}{2cm}% avoid too cramped table columns +''', + # fix missing index entry due to RTD doing only once pdflatex after makeindex + 'printindex': r''' +\IfFileExists{\jobname.ind} + {\footnotesize\raggedright\printindex} + {\begin{sphinxtheindex}\end{sphinxtheindex}} +''', +} +latex_show_urls = 'footnote' +latex_use_xindy = True + +linkcheck_timeout = 5 + +autodoc_member_order = 'groupwise' +autosummary_generate = False +todo_include_todos = True +extlinks = {'duref': ('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')} + +man_pages = [ + ('index', 'sphinx-all', 'Sphinx documentation generator system manual', + 'the Sphinx developers', 1), + ('man/sphinx-build', 'sphinx-build', 'Sphinx documentation generator tool', + '', 1), + ('man/sphinx-quickstart', 'sphinx-quickstart', 'Sphinx documentation ' + 'template generator', '', 1), + ('man/sphinx-apidoc', 'sphinx-apidoc', 'Sphinx API doc generator tool', + '', 1), + ('man/sphinx-autogen', 'sphinx-autogen', 'Generate autodoc stub pages', + '', 1), +] + +texinfo_documents = [ + ('index', 'sphinx', 'Sphinx Documentation', 'the Sphinx developers', + 'Sphinx', 'The Sphinx documentation builder.', 'Documentation tools', + 1), +] + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3/', None), + 'requests': ('https://requests.readthedocs.io/en/latest/', None), + 'readthedocs': ('https://docs.readthedocs.io/en/stable', None), +} + +# Sphinx document translation with sphinx gettext feature uses these settings: +locale_dirs = ['locale/'] +gettext_compact = False + +nitpick_ignore = { + ('cpp:class', 'template<typename TOuter> template<typename TInner> Wrapper::Outer<TOuter>::Inner'), # NoQA: E501 + ('cpp:identifier', 'MyContainer'), + ('js:func', 'SomeError'), + ('js:func', 'number'), + ('js:func', 'string'), + ('py:attr', 'srcline'), + ('py:class', 'Element'), # sphinx.domains.Domain + ('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', 'Theme'), # sphinx.application.TemplateBridge + ('py:class', 'TitleGetter'), # sphinx.domains.Domain + ('py:class', 'XRefRole'), # sphinx.domains.Domain + ('py:class', 'docutils.nodes.Element'), + ('py:class', 'docutils.nodes.Node'), + ('py:class', 'docutils.nodes.NodeVisitor'), + ('py:class', 'docutils.nodes.TextElement'), + ('py:class', 'docutils.nodes.document'), + ('py:class', 'docutils.nodes.system_message'), + ('py:class', 'docutils.parsers.Parser'), + ('py:class', 'docutils.parsers.rst.states.Inliner'), + ('py:class', 'docutils.transforms.Transform'), + ('py:class', 'nodes.NodeVisitor'), + ('py:class', 'nodes.document'), + ('py:class', 'nodes.reference'), + ('py:class', 'pygments.lexer.Lexer'), + ('py:class', 'sphinx.directives.ObjDescT'), + ('py:class', 'sphinx.domains.IndexEntry'), + ('py:class', 'sphinx.ext.autodoc.Documenter'), + ('py:class', 'sphinx.errors.NoUri'), + ('py:class', 'sphinx.roles.XRefRole'), + ('py:class', 'sphinx.search.SearchLanguage'), + ('py:class', 'sphinx.theming.Theme'), + ('py:class', 'sphinxcontrib.websupport.errors.DocumentNotFoundError'), + ('py:class', 'sphinxcontrib.websupport.errors.UserNotAuthorizedError'), + ('py:exc', 'docutils.nodes.SkipNode'), + ('py:exc', 'sphinx.environment.NoUri'), + ('py:func', 'setup'), + ('py:func', 'sphinx.util.nodes.nested_parse_with_titles'), + # Error in sphinxcontrib.websupport.core::WebSupport.add_comment + ('py:meth', 'get_comments'), + ('py:mod', 'autodoc'), + ('py:mod', 'docutils.nodes'), + ('py:mod', 'docutils.parsers.rst.directives'), + ('py:mod', 'sphinx.ext'), + ('py:obj', 'sphinx.util.relative_uri'), + ('rst:role', 'c:any'), + ('std:confval', 'autodoc_inherit_docstring'), + ('std:confval', 'automodule_skip_lines'), + ('std:confval', 'autossummary_imported_members'), + ('std:confval', 'gettext_language_team'), + ('std:confval', 'gettext_last_translator'), + ('std:confval', 'globaltoc_collapse'), + ('std:confval', 'globaltoc_includehidden'), + ('std:confval', 'globaltoc_maxdepth'), +} + + +# -- Extension interface ------------------------------------------------------- + +from sphinx import addnodes # noqa: E402 + +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: + signode += addnodes.desc_name(sig, sig) + return sig + name, args = m.groups() + signode += addnodes.desc_name(name, name) + plist = addnodes.desc_parameterlist() + for arg in args.split(','): + arg = arg.strip() + plist += addnodes.desc_parameter(arg, arg) + signode += plist + return name + + +def linkify_issues_in_changelog(app, docname, source): + """ Linkify issue references like #123 in changelog to GitHub. """ + + if docname == 'changes': + changelog_path = os.path.join(os.path.dirname(__file__), "../CHANGES") + # 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) + + source[0] = source[0].replace('.. include:: ../CHANGES', linkified_changelog) + + +def setup(app): + 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') + 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]) diff --git a/doc/development/builders.rst b/doc/development/builders.rst new file mode 100644 index 0000000..bb67770 --- /dev/null +++ b/doc/development/builders.rst @@ -0,0 +1,34 @@ +Configuring builders +==================== + +Discover builders by entry point +-------------------------------- + +.. versionadded:: 1.6 + +:term:`builder` extensions can be discovered by means of `entry points`_ so +that they do not have to be listed in the :confval:`extensions` configuration +value. + +Builder extensions should define an entry point in the ``sphinx.builders`` +group. The name of the entry point needs to match your builder's +:attr:`~.Builder.name` attribute, which is the name passed to the +:option:`sphinx-build -b` option. The entry point value should equal the +dotted name of the extension module. Here is an example of how an entry point +for 'mybuilder' can be defined in the extension's ``setup.py`` + +.. code-block:: python + + setup( + # ... + entry_points={ + 'sphinx.builders': [ + 'mybuilder = my.extension.module', + ], + } + ) + +Note that it is still necessary to register the builder using +:meth:`~.Sphinx.add_builder` in the extension's :func:`setup` function. + +.. _entry points: https://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins diff --git a/doc/development/index.rst b/doc/development/index.rst new file mode 100644 index 0000000..55a31a0 --- /dev/null +++ b/doc/development/index.rst @@ -0,0 +1,24 @@ +========================= +Writing Sphinx Extensions +========================= + +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`. + +.. toctree:: + :maxdepth: 2 + + overview + tutorials/index + builders + +.. toctree:: + :caption: Theming + :maxdepth: 2 + + templating + theming diff --git a/doc/development/overview.rst b/doc/development/overview.rst new file mode 100644 index 0000000..df8f5bb --- /dev/null +++ b/doc/development/overview.rst @@ -0,0 +1,32 @@ +Developing extensions overview +============================== + +This page contains general information about developing Sphinx extensions. + +Make an extension depend on another extension +--------------------------------------------- + +Sometimes your extension depends on the functionality of another +Sphinx extension. Most Sphinx extensions are activated in a +project's :file:`conf.py` file, but this is not available to you as an +extension developer. + +.. module:: sphinx.application + :no-index: + +To ensure that another extension is activated as a part of your own extension, +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: + +.. code-block:: python + + def setup(app): + app.setup_extension("recommonmark") + +.. note:: + + Since your extension will depend on another, make sure to include + it as a part of your extension's installation requirements. diff --git a/doc/development/templating.rst b/doc/development/templating.rst new file mode 100644 index 0000000..73ae6e5 --- /dev/null +++ b/doc/development/templating.rst @@ -0,0 +1,478 @@ +.. highlight:: html+jinja + +.. _templating: + +========== +Templating +========== + +Sphinx uses the `Jinja <https://jinja.palletsprojects.com/>`_ templating engine +for its HTML templates. Jinja is a text-based engine, inspired by Django +templates, so anyone having used Django will already be familiar with it. It +also has excellent documentation for those who need to make themselves familiar +with it. + + +Do I need to use Sphinx's templates to produce HTML? +---------------------------------------------------- + +No. You have several other options: + +* You can write a :class:`~sphinx.application.TemplateBridge` subclass that + calls your template engine of choice, and set the :confval:`template_bridge` + configuration value accordingly. + +* You can :ref:`write a custom builder <writing-builders>` that derives from + :class:`~sphinx.builders.html.StandaloneHTMLBuilder` and calls your template + engine of choice. + +* You can use the :class:`~sphinxcontrib.serializinghtml.PickleHTMLBuilder` that + produces pickle files with the page contents, and postprocess them using a + custom tool, or use them in your Web application. + + +Jinja/Sphinx Templating Primer +------------------------------ + +The default templating language in Sphinx is Jinja. It's Django/Smarty inspired +and easy to understand. The most important concept in Jinja is :dfn:`template +inheritance`, which means that you can overwrite only specific blocks within a +template, customizing it while also keeping the changes at a minimum. + +To customize the output of your documentation you can override all the templates +(both the layout templates and the child templates) by adding files with the +same name as the original filename into the template directory of the structure +the Sphinx quickstart generated for you. + +Sphinx will look for templates in the folders of :confval:`templates_path` +first, and if it can't find the template it's looking for there, it falls back +to the selected theme's templates. + +A template contains **variables**, which are replaced with values when the +template is evaluated, **tags**, which control the logic of the template and +**blocks** which are used for template inheritance. + +Sphinx's *basic* theme provides base templates with a couple of blocks it will +fill with data. These are located in the :file:`themes/basic` subdirectory of +the Sphinx installation directory, and used by all builtin Sphinx themes. +Templates with the same name in the :confval:`templates_path` override templates +supplied by the selected theme. + +For example, to add a new link to the template area containing related links all +you have to do is to add a new template called ``layout.html`` with the +following contents:: + + {% extends "!layout.html" %} + {% block rootrellink %} + <li><a href="https://project.invalid/">Project Homepage</a> »</li> + {{ super() }} + {% endblock %} + +By prefixing the name of the overridden template with an exclamation mark, +Sphinx will load the layout template from the underlying HTML theme. + +.. important:: + If you override a block, call ``{{ super() }}`` somewhere to render the + block's original content in the extended template -- unless you don't want + that content to show up. + + +Working with the builtin templates +---------------------------------- + +The builtin **basic** theme supplies the templates that all builtin Sphinx +themes are based on. It has the following elements you can override or use: + +Blocks +~~~~~~ + +The following blocks exist in the ``layout.html`` template: + +``doctype`` + The doctype of the output format. By default this is XHTML 1.0 Transitional + as this is the closest to what Sphinx and Docutils generate and it's a good + idea not to change it unless you want to switch to HTML 5 or a different but + compatible XHTML doctype. + +``linktags`` + This block adds a couple of ``<link>`` tags to the head section of the + template. + +``extrahead`` + This block is empty by default and can be used to add extra contents into + the ``<head>`` tag of the generated HTML file. This is the right place to + add references to JavaScript or extra CSS files. + +``relbar1``, ``relbar2`` + This block contains the *relation bar*, the list of related links (the + parent documents on the left, and the links to index, modules etc. on the + right). ``relbar1`` appears before the document, ``relbar2`` after the + document. By default, both blocks are filled; to show the relbar only + before the document, you would override `relbar2` like this:: + + {% block relbar2 %}{% endblock %} + +``rootrellink``, ``relbaritems`` + Inside the relbar there are three sections: The ``rootrellink``, the links + from the documentation and the custom ``relbaritems``. The ``rootrellink`` + is a block that by default contains a list item pointing to the root + document by default, the ``relbaritems`` is an empty block. If you + override them to add extra links into the bar make sure that they are list + items and end with the :data:`reldelim1`. + +``document`` + The contents of the document itself. It contains the block "body" where + the individual content is put by subtemplates like ``page.html``. + + .. note:: + In order for the built-in JavaScript search to show a page preview on + the results page, the document or body content should be wrapped in an + HTML element containing the ``role="main"`` attribute. For example:: + + <div role="main"> + {% block document %}{% endblock %} + </div> + +``sidebar1``, ``sidebar2`` + A possible location for a sidebar. ``sidebar1`` appears before the document + and is empty by default, ``sidebar2`` after the document and contains the + default sidebar. If you want to swap the sidebar location override this and + call the ``sidebar`` helper:: + + {% block sidebar1 %}{{ sidebar() }}{% endblock %} + {% block sidebar2 %}{% endblock %} + + (The ``sidebar2`` location for the sidebar is needed by the ``sphinxdoc.css`` + stylesheet, for example.) + +``sidebarlogo`` + The logo location within the sidebar. Override this if you want to place + some content at the top of the sidebar. + +``footer`` + The block for the footer div. If you want a custom footer or markup before + or after it, override this one. + +The following four blocks are *only* used for pages that do not have assigned a +list of custom sidebars in the :confval:`html_sidebars` config value. Their use +is deprecated in favor of separate sidebar templates, which can be included via +:confval:`html_sidebars`. + +``sidebartoc`` + The table of contents within the sidebar. + + .. deprecated:: 1.0 + +``sidebarrel`` + The relation links (previous, next document) within the sidebar. + + .. deprecated:: 1.0 + +``sidebarsourcelink`` + The "Show source" link within the sidebar (normally only shown if this is + enabled by :confval:`html_show_sourcelink`). + + .. deprecated:: 1.0 + +``sidebarsearch`` + The search box within the sidebar. Override this if you want to place some + content at the bottom of the sidebar. + + .. deprecated:: 1.0 + + +Configuration Variables +~~~~~~~~~~~~~~~~~~~~~~~ + +Inside templates you can set a couple of variables used by the layout template +using the ``{% set %}`` tag: + +.. data:: reldelim1 + + The delimiter for the items on the left side of the related bar. This + defaults to ``' »'`` Each item in the related bar ends with the value + of this variable. + +.. data:: reldelim2 + + The delimiter for the items on the right side of the related bar. This + defaults to ``' |'``. Each item except of the last one in the related bar + ends with the value of this variable. + +Overriding works like this:: + + {% extends "!layout.html" %} + {% set reldelim1 = ' >' %} + +.. data:: script_files + + Add additional script files here, like this:: + + {% set script_files = script_files + ["_static/myscript.js"] %} + + .. deprecated:: 1.8.0 + + Please use ``.Sphinx.add_js_file()`` instead. + +Helper Functions +~~~~~~~~~~~~~~~~ + +Sphinx provides various Jinja functions as helpers in the template. You can use +them to generate links or output multiply used elements. + +.. function:: pathto(document) + + Return the path to a Sphinx document as a URL. Use this to refer to built + documents. + +.. function:: pathto(file, 1) + :no-index: + + Return the path to a *file* which is a filename relative to the root of the + generated output. Use this to refer to static files. + +.. function:: hasdoc(document) + + Check if a document with the name *document* exists. + +.. function:: sidebar() + + Return the rendered sidebar. + +.. function:: relbar() + + Return the rendered relation bar. + +.. function:: warning(message) + + Emit a warning message. + +Global Variables +~~~~~~~~~~~~~~~~ + +These global variables are available in every template and are safe to use. +There are more, but most of them are an implementation detail and might change +in the future. + +.. data:: builder + + The name of the builder (e.g. ``html`` or ``htmlhelp``). + +.. data:: copyright + + The value of :confval:`copyright`. + +.. data:: docstitle + + The title of the documentation (the value of :confval:`html_title`), except + when the "single-file" builder is used, when it is set to ``None``. + +.. data:: embedded + + True if the built HTML is meant to be embedded in some viewing application + that handles navigation, not the web browser, such as for HTML help or Qt + help formats. In this case, the sidebar is not included. + +.. data:: favicon_url + + The relative path to the HTML favicon image from the current document, or + URL to the favicon, or ``''``. + + .. versionadded:: 4.0 + +.. data:: file_suffix + + The value of the builder's :attr:`~.SerializingHTMLBuilder.out_suffix` + attribute, i.e. the file name extension that the output files will get. For + a standard HTML builder, this is usually ``.html``. + +.. data:: has_source + + True if the reST document sources are copied (if :confval:`html_copy_source` + is ``True``). + +.. data:: language + + The value of :confval:`language`. + +.. data:: last_updated + + The build date. + +.. data:: logo_url + + The relative path to the HTML logo image from the current document, or URL + to the logo, or ``''``. + + .. versionadded:: 4.0 + +.. data:: master_doc + + Same as :data:`root_doc`. + + .. versionchanged:: 4.0 + + Renamed to ``root_doc``. + +.. data:: root_doc + + The value of :confval:`root_doc`, for usage with :func:`pathto`. + + .. versionchanged:: 4.0 + + Renamed from ``master_doc``. + +.. 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 + (``[directory/]filename_without_extension``). + +.. data:: project + + The value of :confval:`project`. + +.. data:: release + + The value of :confval:`release`. + +.. data:: rellinks + + A list of links to put at the left side of the relbar, next to "next" and + "prev". This usually contains links to the general index and other indices, + such as the Python module index. If you add something yourself, it must be a + tuple ``(pagename, link title, accesskey, link text)``. + +.. data:: shorttitle + + The value of :confval:`html_short_title`. + +.. data:: show_source + + True if :confval:`html_show_sourcelink` is ``True``. + +.. data:: sphinx_version + + The version of Sphinx used to build represented as a string for example "3.5.1". + +.. data:: sphinx_version_tuple + + The version of Sphinx used to build represented as a tuple of five elements. + For Sphinx version 3.5.1 beta 3 this would be ``(3, 5, 1, 'beta', 3)``. + The fourth element can be one of: ``alpha``, ``beta``, ``rc``, ``final``. + ``final`` always has 0 as the last element. + + .. versionadded:: 4.2 + +.. data:: docutils_version_info + + The version of Docutils used to build represented as a tuple of five elements. + For Docutils version 0.16.1 beta 2 this would be ``(0, 16, 1, 'beta', 2)``. + The fourth element can be one of: ``alpha``, ``beta``, ``candidate``, ``final``. + ``final`` always has 0 as the last element. + + .. versionadded:: 5.0.2 + +.. data:: styles + + A list of the names of the main stylesheets as given by the theme or + :confval:`html_style`. + + .. versionadded:: 5.1 + +.. data:: title + + The title of the current document, as used in the ``<title>`` tag. + +.. data:: use_opensearch + + The value of :confval:`html_use_opensearch`. + +.. data:: version + + The value of :confval:`version`. + + +In addition to these values, there are also all **theme options** available +(prefixed by ``theme_``), as well as the values given by the user in +:confval:`html_context`. + +In documents that are created from source files (as opposed to +automatically-generated files like the module index, or documents that already +are in HTML form), these variables are also available: + +.. data:: body + + A string containing the content of the page in HTML form as produced by the + HTML builder, before the theme is applied. + +.. data:: display_toc + + A boolean that is True if the toc contains more than one entry. + +.. data:: meta + + Document metadata (a dictionary), see :ref:`metadata`. + +.. data:: metatags + + A string containing the page's HTML :dudir:`meta` tags. + +.. data:: next + + The next document for the navigation. This variable is either false or has + two attributes `link` and `title`. The title contains HTML markup. For + example, to generate a link to the next page, you can use this snippet:: + + {% if next %} + <a href="{{ next.link|e }}">{{ next.title }}</a> + {% endif %} + +.. data:: page_source_suffix + + The suffix of the file that was rendered. Since we support a list of + :confval:`source_suffix`, this will allow you to properly link to the + original source file. + +.. data:: parents + + A list of parent documents for navigation, structured like the :data:`next` + item. + +.. data:: prev + + Like :data:`next`, but for the previous page. + +.. data:: sourcename + + The name of the copied source file for the current document. This is only + nonempty if the :confval:`html_copy_source` value is ``True``. + This has empty value on creating automatically-generated files. + +.. data:: toc + + The local table of contents for the current page, rendered as HTML bullet + lists. + +.. data:: toctree + + A callable yielding the global TOC tree containing the current page, rendered + as HTML bullet lists. Optional keyword arguments: + + ``collapse`` + If true, all TOC entries that are not ancestors of the current page are + collapsed. + ``True`` by default. + + ``maxdepth`` + The maximum depth of the tree. Set it to ``-1`` to allow unlimited depth. + Defaults to the max depth selected in the toctree directive. + + ``titles_only`` + If true, put only top-level document titles in the tree. + ``False`` by default. + + ``includehidden`` + If true, the ToC tree will also contain hidden entries. + ``False`` by default. diff --git a/doc/development/theming.rst b/doc/development/theming.rst new file mode 100644 index 0000000..538dcaf --- /dev/null +++ b/doc/development/theming.rst @@ -0,0 +1,342 @@ +HTML theme development +====================== + +.. versionadded:: 0.6 + +.. note:: + + This document provides information about creating your own theme. If you + simply wish to use a pre-existing HTML themes, refer to + :doc:`/usage/theming`. + +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. +Additionally, it has a configuration file which specifies from which theme to +inherit, which highlighting style to use, and what options exist for customizing +the theme's look and feel. + +Themes are meant to be project-unaware, so they can be used for different +projects without change. + +.. note:: + + See :ref:`dev-extensions` for more information that may + be helpful in developing themes. + + +Creating themes +--------------- + +Themes take the form of either a directory or a zipfile (whose name is the +theme name), containing the following: + +* A :file:`theme.conf` file. +* HTML templates, if needed. +* A ``static/`` directory containing any static files that will be copied to the + output static directory on build. These can be images, styles, script files. + +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 + + [theme] + inherit = base theme + stylesheet = main CSS name + pygments_style = stylename + sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html + + [options] + variable = default value + +* The **inherit** setting gives the name of a "base theme", or ``none``. The + base theme will be used to locate missing templates (most themes will not have + to supply most templates if they use ``basic`` as the base theme), its options + will be inherited, and all of its static files will be used as well. If you + want to also inherit the stylesheet, include it via CSS' ``@import`` in your + own. + +* The **stylesheet** setting gives a list of CSS filenames separated commas which + will be referenced in the HTML header. You can also use CSS' ``@import`` + technique to include one from the other, or use a custom HTML template that + adds ``<link rel="stylesheet">`` tags as necessary. Setting the + :confval:`html_style` config value will override this setting. + +* The **pygments_style** setting gives the name of a Pygments style to use for + highlighting. This can be overridden by the user in the + :confval:`pygments_style` config value. + +* The **pygments_dark_style** setting gives the name of a Pygments style to use + for highlighting when the CSS media query ``(prefers-color-scheme: dark)`` + evaluates to true. It is injected into the page using + :meth:`~sphinx.application.Sphinx.add_css_file()`. + +* The **sidebars** setting gives the comma separated list of sidebar templates + for constructing sidebars. This can be overridden by the user in the + :confval:`html_sidebars` config value. + +* The **options** section contains pairs of variable names and default values. + These options can be overridden by the user in :confval:`html_theme_options` + and are accessible from all templates as ``theme_<name>``. + +.. versionadded:: 1.7 + sidebar settings + +.. versionchanged:: 5.1 + + The stylesheet setting accepts multiple CSS filenames + +.. _distribute-your-theme: + +Distribute your theme as a Python package +----------------------------------------- + +As a way to distribute your theme, you can use a Python package. This makes it +easier for users to set up your theme. + +To distribute your theme as a Python package, please define an entry point +called ``sphinx.html_themes`` in your ``setup.py`` file, and write a ``setup()`` +function to register your themes using ``add_html_theme()`` API in it:: + + # 'setup.py' + setup( + ... + entry_points = { + 'sphinx.html_themes': [ + 'name_of_theme = your_package', + ] + }, + ... + ) + + # 'your_package.py' + from os import path + + def setup(app): + app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__))) + +If your theme package contains two or more themes, please call +``add_html_theme()`` twice or more. + +.. versionadded:: 1.2 + 'sphinx_themes' entry_points feature. + +.. deprecated:: 1.6 + ``sphinx_themes`` entry_points has been deprecated. + +.. versionadded:: 1.6 + ``sphinx.html_themes`` entry_points feature. + + +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: + +* First, in the user's ``templates_path`` directories. +* Then, in the selected theme. +* Then, in its base theme, its base's base theme, etc. + +When extending a template in the base theme with the same name, use the theme +name as an explicit directory: ``{% extends "basic/layout.html" %}``. From a +user ``templates_path`` template, you can still use the "exclamation mark" +syntax as described in the templating document. + + +.. _theming-static-templates: + +Static templates +~~~~~~~~~~~~~~~~ + +Since theme options are meant for the user to configure a theme more easily, +without having to write a custom stylesheet, it is necessary to be able to +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. + + +Use custom page metadata in HTML templates +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Any key / value pairs in :doc:`field lists </usage/restructuredtext/field-lists>` +that are placed *before* the page's title will be available to the Jinja +template when building the page within the :data:`meta` attribute. For example, +if a page had the following text before its first title: + +.. code-block:: rst + + :mykey: My value + + My first title + -------------- + +Then it could be accessed within a Jinja template like so: + +.. code-block:: jinja + + {%- if meta is mapping %} + {{ meta.get("mykey") }} + {%- endif %} + +Note the check that ``meta`` is a dictionary ("mapping" in Jinja +terminology) to ensure that using it in this way is valid. + + +Defining custom template functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sometimes it is useful to define your own function in Python that you wish to +then use in a template. For example, if you'd like to insert a template value +with logic that depends on the user's configuration in the project, or if you'd +like to include non-trivial checks and provide friendly error messages for +incorrect configuration in the template. + +To define your own template function, you'll need to define two functions +inside your module: + +* A **page context event handler** (or **registration**) function. This is + connected to the :class:`.Sphinx` application via an event callback. +* A **template function** that you will use in your Jinja template. + +First, define the registration function, which accepts the arguments for +:event:`html-page-context`. + +Within the registration function, define the template function that you'd like to +use within Jinja. The template function should return a string or Python objects +(lists, dictionaries) with strings inside that Jinja uses in the templating process + +.. note:: + + The template function will have access to all of the variables that + are passed to the registration function. + +At the end of the registration function, add the template function to the +Sphinx application's context with ``context['template_func'] = template_func``. + +Finally, in your extension's ``setup()`` function, add your registration +function as a callback for :event:`html-page-context`. + +.. code-block:: python + + # The registration function + def setup_my_func(app, pagename, templatename, context, doctree): + # The template function + def my_func(mystring): + return "Your string is %s" % mystring + # Add it to the page's context + context['my_func'] = my_func + + # Your extension's setup function + def setup(app): + app.connect("html-page-context", setup_my_func) + +Now, you will have access to this function in jinja like so: + +.. code-block:: jinja + + <div> + {{ my_func("some string") }} + </div> + + +Add your own static files to the build assets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, Sphinx copies static files on the ``static/`` directory of the template +directory. However, if your package needs to place static files outside of the +``static/`` directory for some reasons, you need to copy them to the ``_static/`` +directory of HTML outputs manually at the build via an event hook. Here is an +example of code to accomplish this: + +.. code-block:: python + + from os import path + from sphinx.util.fileutil import copy_asset_file + + def copy_custom_files(app, exc): + if app.builder.format == 'html' and not exc: + staticdir = path.join(app.builder.outdir, '_static') + copy_asset_file('path/to/myextension/_static/myjsfile.js', staticdir) + + def setup(app): + app.connect('build-finished', copy_custom_files) + + +Inject JavaScript based on user configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If your extension makes use of JavaScript, it can be useful to allow users +to control its behavior using their Sphinx configuration. However, this can +be difficult to do if your JavaScript comes in the form of a static library +(which will not be built with Jinja). + +There are two ways to inject variables into the JavaScript space based on user +configuration. + +First, you may append ``_t`` to the end of any static files included with your +extension. This will cause Sphinx to process these files with the templating +engine, allowing you to embed variables and control behavior. + +For example, the following JavaScript structure: + +.. code-block:: none + + mymodule/ + ├── _static + │ └── myjsfile.js_t + └── mymodule.py + +Will result in the following static file placed in your HTML's build output: + +.. code-block:: none + + _build/ + └── html + └── _static + └── myjsfile.js + +See :ref:`theming-static-templates` for more information. + +Second, you may use the :meth:`.Sphinx.add_js_file` method without pointing it +to a file. Normally, this method is used to insert a new JavaScript file +into your site. However, if you do *not* pass a file path, but instead pass +a string to the "body" argument, then this text will be inserted as JavaScript +into your site's head. This allows you to insert variables into your project's +JavaScript from Python. + +For example, the following code will read in a user-configured value and then +insert this value as a JavaScript variable, which your extension's JavaScript +code may use: + +.. code-block:: python + + # This function reads in a variable and inserts it into JavaScript + def add_js_variable(app): + # This is a configuration that you've specified for users in `conf.py` + js_variable = app.config['my_javascript_variable'] + js_text = "var my_variable = '%s';" % js_variable + app.add_js_file(None, body=js_text) + # We connect this function to the step after the builder is initialized + def setup(app): + # Tell Sphinx about this configuration variable + app.add_config_value('my_javascript_variable', 0, 'html') + # Run the function after the builder is initialized + app.connect('builder-inited', add_js_variable) + +As a result, in your theme you can use code that depends on the presence of +this variable. Users can control the variable's value by defining it in their +:file:`conf.py` file. + + +.. [1] It is not an executable Python file, as opposed to :file:`conf.py`, + because that would pose an unnecessary security risk if themes are + shared. diff --git a/doc/development/tutorials/autodoc_ext.rst b/doc/development/tutorials/autodoc_ext.rst new file mode 100644 index 0000000..cfd23e7 --- /dev/null +++ b/doc/development/tutorials/autodoc_ext.rst @@ -0,0 +1,141 @@ +.. _autodoc_ext_tutorial: + +Developing autodoc extension for IntEnum +======================================== + +The objective of this tutorial is to create an extension that adds +support for new type for autodoc. This autodoc extension will format +the ``IntEnum`` class from Python standard library. (module ``enum``) + +Overview +-------- + +We want the extension that will create auto-documentation for IntEnum. +``IntEnum`` is the integer enum class from standard library ``enum`` module. + +Currently this class has no special auto documentation behavior. + +We want to add following to autodoc: + +* A new ``autointenum`` directive that will document the ``IntEnum`` class. +* The generated documentation will have all the enum possible values + with names. +* The ``autointenum`` directive will have an option ``:hex:`` which will + cause the integers be printed in hexadecimal form. + + +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`. +The :file:`my_enums.py` will contain the sample enums we will document. + +Here is an example of the folder structure you might obtain: + +.. code-block:: text + + └── source + ├── _ext + │ └── autodoc_intenum.py + ├── conf.py + ├── index.rst + └── my_enums.py + + +Writing the extension +--------------------- + +Start with ``setup`` function for the extension. + +.. literalinclude:: examples/autodoc_intenum.py + :language: python + :linenos: + :pyobject: setup + + +The :meth:`~sphinx.application.Sphinx.setup_extension` method will pull the +autodoc extension because our new extension depends on autodoc. +:meth:`~sphinx.application.Sphinx.add_autodocumenter` is the method that +registers our new auto documenter class. + +We want to import certain objects from the autodoc extension: + +.. literalinclude:: examples/autodoc_intenum.py + :language: python + :linenos: + :lines: 1-7 + + +There are several different documenter classes such as ``MethodDocumenter`` +or ``AttributeDocumenter`` available in the autodoc extension but +our new class is the subclass of ``ClassDocumenter`` which a +documenter class used by autodoc to document classes. + +This is the definition of our new the auto-documenter class: + +.. literalinclude:: examples/autodoc_intenum.py + :language: python + :linenos: + :pyobject: IntEnumDocumenter + + +Important attributes of the new class: + +**objtype** + This attribute determines the ``auto`` directive name. In + this case the auto directive will be ``autointenum``. + +**directivetype** + This attribute sets the generated directive name. In + this example the generated directive will be ``.. :py:class::``. + +**priority** + the larger the number the higher is the priority. We want our + documenter be higher priority than the parent. + +**option_spec** + option specifications. We copy the parent class options and + add a new option *hex*. + + +Overridden members: + +**can_document_member** + This member is important to override. It should + return *True* when the passed object can be documented by this class. + +**add_directive_header** + This method generates the directive header. We add + **:final:** directive option. Remember to call **super** or no directive + will be generated. + +**add_content** + This method generates the body of the class documentation. + After calling the super method we generate lines for enum description. + + +Using the extension +------------------- + +You can now use the new autodoc directive to document any ``IntEnum``. + +For example, you have the following ``IntEnum``: + +.. code-block:: python + :caption: my_enums.py + + class Colors(IntEnum): + """Colors enumerator""" + NONE = 0 + RED = 1 + GREEN = 2 + BLUE = 3 + + +This will be the documentation file with auto-documentation directive: + +.. code-block:: rst + :caption: index.rst + + .. autointenum:: my_enums.Colors diff --git a/doc/development/tutorials/examples/README.rst b/doc/development/tutorials/examples/README.rst new file mode 100644 index 0000000..2b9c01b --- /dev/null +++ b/doc/development/tutorials/examples/README.rst @@ -0,0 +1,11 @@ +:orphan: + +Tutorial examples +================= + +This directory contains a number of examples used in the tutorials. These are +intended to be increasingly complex to demonstrate the various features of +Sphinx, but should aim to be as complicated as necessary but no more. +Individual sections are referenced by line numbers, meaning if you make changes +to the source files, you should update the references in the documentation +accordingly. diff --git a/doc/development/tutorials/examples/autodoc_intenum.py b/doc/development/tutorials/examples/autodoc_intenum.py new file mode 100644 index 0000000..75fa204 --- /dev/null +++ b/doc/development/tutorials/examples/autodoc_intenum.py @@ -0,0 +1,58 @@ +from __future__ import annotations + +from enum import IntEnum +from typing import TYPE_CHECKING, Any + +from sphinx.ext.autodoc import ClassDocumenter, bool_option + +if TYPE_CHECKING: + from docutils.statemachine import StringList + + from sphinx.application import Sphinx + + +class IntEnumDocumenter(ClassDocumenter): + objtype = 'intenum' + directivetype = ClassDocumenter.objtype + priority = 10 + ClassDocumenter.priority + option_spec = dict(ClassDocumenter.option_spec) + option_spec['hex'] = bool_option + + @classmethod + def can_document_member(cls, + member: Any, membername: str, + isattr: bool, parent: Any) -> bool: + try: + return issubclass(member, IntEnum) + except TypeError: + return False + + def add_directive_header(self, sig: str) -> None: + super().add_directive_header(sig) + self.add_line(' :final:', self.get_sourcename()) + + def add_content(self, + more_content: StringList | None, + no_docstring: bool = False, + ) -> None: + + super().add_content(more_content, no_docstring) + + source_name = self.get_sourcename() + enum_object: IntEnum = self.object + use_hex = self.options.hex + self.add_line('', source_name) + + for the_member_name, enum_member in enum_object.__members__.items(): + the_member_value = enum_member.value + if use_hex: + the_member_value = hex(the_member_value) + + self.add_line( + f"**{the_member_name}**: {the_member_value}", source_name) + self.add_line('', source_name) + + +def setup(app: Sphinx) -> None: + app.setup_extension('sphinx.ext.autodoc') # Require autodoc extension + app.add_autodocumenter(IntEnumDocumenter) diff --git a/doc/development/tutorials/examples/helloworld.py b/doc/development/tutorials/examples/helloworld.py new file mode 100644 index 0000000..d6d81fd --- /dev/null +++ b/doc/development/tutorials/examples/helloworld.py @@ -0,0 +1,19 @@ +from docutils import nodes +from docutils.parsers.rst import Directive + + +class HelloWorld(Directive): + + def run(self): + paragraph_node = nodes.paragraph(text='Hello World!') + return [paragraph_node] + + +def setup(app): + app.add_directive("helloworld", HelloWorld) + + return { + 'version': '0.1', + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } diff --git a/doc/development/tutorials/examples/recipe.py b/doc/development/tutorials/examples/recipe.py new file mode 100644 index 0000000..c7ebf2a --- /dev/null +++ b/doc/development/tutorials/examples/recipe.py @@ -0,0 +1,159 @@ +from collections import defaultdict + +from docutils.parsers.rst import directives + +from sphinx import addnodes +from sphinx.directives import ObjectDescription +from sphinx.domains import Domain, Index +from sphinx.roles import XRefRole +from sphinx.util.nodes import make_refnode + + +class RecipeDirective(ObjectDescription): + """A custom directive that describes a recipe.""" + + has_content = True + required_arguments = 1 + option_spec = { + 'contains': directives.unchanged_required, + } + + def handle_signature(self, sig, signode): + signode += addnodes.desc_name(text=sig) + return sig + + def add_target_and_index(self, name_cls, sig, signode): + signode['ids'].append('recipe' + '-' + sig) + if 'contains' in self.options: + ingredients = [ + x.strip() for x in self.options.get('contains').split(',')] + + recipes = self.env.get_domain('recipe') + recipes.add_recipe(sig, ingredients) + + +class IngredientIndex(Index): + """A custom index that creates an ingredient matrix.""" + + name = 'ingredient' + localname = 'Ingredient Index' + shortname = 'Ingredient' + + def generate(self, docnames=None): + content = defaultdict(list) + + recipes = {name: (dispname, typ, docname, anchor) + for name, dispname, typ, docname, anchor, _ + in self.domain.get_objects()} + recipe_ingredients = self.domain.data['recipe_ingredients'] + ingredient_recipes = defaultdict(list) + + # flip from recipe_ingredients to ingredient_recipes + for recipe_name, ingredients in recipe_ingredients.items(): + for ingredient in ingredients: + ingredient_recipes[ingredient].append(recipe_name) + + # convert the mapping of ingredient to recipes to produce the expected + # output, shown below, using the ingredient name as a key to group + # + # name, subtype, docname, anchor, extra, qualifier, description + for ingredient, recipe_names in ingredient_recipes.items(): + for recipe_name in recipe_names: + dispname, typ, docname, anchor = recipes[recipe_name] + content[ingredient].append( + (dispname, 0, docname, anchor, docname, '', typ)) + + # convert the dict to the sorted list of tuples expected + content = sorted(content.items()) + + return content, True + + +class RecipeIndex(Index): + """A custom index that creates an recipe matrix.""" + + name = 'recipe' + localname = 'Recipe Index' + shortname = 'Recipe' + + def generate(self, docnames=None): + content = defaultdict(list) + + # sort the list of recipes in alphabetical order + recipes = self.domain.get_objects() + recipes = sorted(recipes, key=lambda recipe: recipe[0]) + + # generate the expected output, shown below, from the above using the + # first letter of the recipe as a key to group thing + # + # name, subtype, docname, anchor, extra, qualifier, description + for _name, dispname, typ, docname, anchor, _priority in recipes: + content[dispname[0].lower()].append( + (dispname, 0, docname, anchor, docname, '', typ)) + + # convert the dict to the sorted list of tuples expected + content = sorted(content.items()) + + return content, True + + +class RecipeDomain(Domain): + + name = 'recipe' + label = 'Recipe Sample' + roles = { + 'ref': XRefRole(), + } + directives = { + 'recipe': RecipeDirective, + } + indices = { + RecipeIndex, + IngredientIndex, + } + initial_data = { + 'recipes': [], # object list + 'recipe_ingredients': {}, # name -> object + } + + def get_full_qualified_name(self, node): + return f'recipe.{node.arguments[0]}' + + def get_objects(self): + yield from self.data['recipes'] + + def resolve_xref(self, env, fromdocname, builder, typ, target, node, + contnode): + match = [(docname, anchor) + for name, sig, typ, docname, anchor, prio + in self.get_objects() if sig == target] + + if len(match) > 0: + todocname = match[0][0] + targ = match[0][1] + + return make_refnode(builder, fromdocname, todocname, targ, + contnode, targ) + else: + print('Awww, found nothing') + return None + + def add_recipe(self, signature, ingredients): + """Add a new recipe to the domain.""" + name = f'recipe.{signature}' + anchor = f'recipe-{signature}' + + self.data['recipe_ingredients'][name] = ingredients + # name, dispname, type, docname, anchor, priority + self.data['recipes'].append( + (name, signature, 'Recipe', self.env.docname, anchor, 0)) + + +def setup(app): + app.add_domain(RecipeDomain) + + return { + 'version': '0.1', + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } diff --git a/doc/development/tutorials/examples/todo.py b/doc/development/tutorials/examples/todo.py new file mode 100644 index 0000000..15368f4 --- /dev/null +++ b/doc/development/tutorials/examples/todo.py @@ -0,0 +1,135 @@ +from docutils import nodes +from docutils.parsers.rst import Directive + +from sphinx.locale import _ +from sphinx.util.docutils import SphinxDirective + + +class todo(nodes.Admonition, nodes.Element): + pass + + +class todolist(nodes.General, nodes.Element): + pass + + +def visit_todo_node(self, node): + self.visit_admonition(node) + + +def depart_todo_node(self, node): + self.depart_admonition(node) + + +class TodolistDirective(Directive): + + def run(self): + return [todolist('')] + + +class TodoDirective(SphinxDirective): + + # this enables content in the directive + has_content = True + + def run(self): + targetid = 'todo-%d' % self.env.new_serialno('todo') + targetnode = nodes.target('', '', ids=[targetid]) + + todo_node = todo('\n'.join(self.content)) + todo_node += nodes.title(_('Todo'), _('Todo')) + self.state.nested_parse(self.content, self.content_offset, todo_node) + + if not hasattr(self.env, 'todo_all_todos'): + self.env.todo_all_todos = [] + + self.env.todo_all_todos.append({ + 'docname': self.env.docname, + 'lineno': self.lineno, + 'todo': todo_node.deepcopy(), + 'target': targetnode, + }) + + return [targetnode, todo_node] + + +def purge_todos(app, env, docname): + if not hasattr(env, 'todo_all_todos'): + return + + env.todo_all_todos = [todo for todo in env.todo_all_todos + if todo['docname'] != docname] + + +def merge_todos(app, env, docnames, other): + if not hasattr(env, 'todo_all_todos'): + env.todo_all_todos = [] + if hasattr(other, 'todo_all_todos'): + env.todo_all_todos.extend(other.todo_all_todos) + + +def process_todo_nodes(app, doctree, fromdocname): + if not app.config.todo_include_todos: + for node in doctree.findall(todo): + node.parent.remove(node) + + # Replace all todolist nodes with a list of the collected todos. + # Augment each todo with a backlink to the original location. + env = app.builder.env + + if not hasattr(env, 'todo_all_todos'): + env.todo_all_todos = [] + + for node in doctree.findall(todolist): + if not app.config.todo_include_todos: + node.replace_self([]) + continue + + content = [] + + for todo_info in env.todo_all_todos: + para = nodes.paragraph() + filename = env.doc2path(todo_info['docname'], base=None) + description = ( + _('(The original entry is located in %s, line %d and can be found ') % + (filename, todo_info['lineno'])) + para += nodes.Text(description) + + # Create a reference + newnode = nodes.reference('', '') + innernode = nodes.emphasis(_('here'), _('here')) + newnode['refdocname'] = todo_info['docname'] + newnode['refuri'] = app.builder.get_relative_uri( + fromdocname, todo_info['docname']) + newnode['refuri'] += '#' + todo_info['target']['refid'] + newnode.append(innernode) + para += newnode + para += nodes.Text('.)') + + # Insert into the todolist + content.append(todo_info['todo']) + content.append(para) + + node.replace_self(content) + + +def setup(app): + app.add_config_value('todo_include_todos', False, 'html') + + app.add_node(todolist) + app.add_node(todo, + html=(visit_todo_node, depart_todo_node), + latex=(visit_todo_node, depart_todo_node), + text=(visit_todo_node, depart_todo_node)) + + app.add_directive('todo', TodoDirective) + app.add_directive('todolist', TodolistDirective) + app.connect('doctree-resolved', process_todo_nodes) + app.connect('env-purge-doc', purge_todos) + app.connect('env-merge-info', merge_todos) + + return { + 'version': '0.1', + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } diff --git a/doc/development/tutorials/helloworld.rst b/doc/development/tutorials/helloworld.rst new file mode 100644 index 0000000..8940e3d --- /dev/null +++ b/doc/development/tutorials/helloworld.rst @@ -0,0 +1,189 @@ +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 new file mode 100644 index 0000000..a7eee48 --- /dev/null +++ b/doc/development/tutorials/index.rst @@ -0,0 +1,17 @@ +.. _extension-tutorials-index: + +Extension tutorials +=================== + +Refer to the following tutorials to get started with extension development. + + +.. toctree:: + :caption: Directive tutorials + :maxdepth: 1 + + helloworld + todo + recipe + autodoc_ext + diff --git a/doc/development/tutorials/recipe.rst b/doc/development/tutorials/recipe.rst new file mode 100644 index 0000000..1ed428a --- /dev/null +++ b/doc/development/tutorials/recipe.rst @@ -0,0 +1,227 @@ +Developing a "recipe" extension +=============================== + +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 +reference that recipe from elsewhere in our documentation. + +.. note:: + + This tutorial is based on a guide first published on `opensource.com`_ and + is provided here with the original author's permission. + + .. _opensource.com: https://opensource.com/article/18/11/building-custom-workflows-sphinx + + +Overview +-------- + +We want the extension to add the following to Sphinx: + +* A ``recipe`` :term:`directive`, containing some content describing the recipe + steps, along with a ``:contains:`` option highlighting the main ingredients + of the recipe. + +* A ``ref`` :term:`role`, which provides a cross-reference to the recipe + itself. + +* A ``recipe`` :term:`domain`, which allows us to tie together the above role + and domain, along with things like indices. + +For that, we will need to add the following elements to Sphinx: + +* A new directive called ``recipe`` + +* New indexes to allow us to reference ingredient and recipes + +* A new domain called ``recipe``, which will contain the ``recipe`` directive + and ``ref`` role + + +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:`recipe.py`. + +Here is an example of the folder structure you might obtain: + +.. code-block:: text + + └── source + ├── _ext + │ └── recipe.py + ├── conf.py + └── index.rst + + +Writing the extension +--------------------- + +Open :file:`recipe.py` and paste the following code in it, all of which we will +explain in detail shortly: + +.. literalinclude:: examples/recipe.py + :language: python + :linenos: + +Let's look at each piece of this extension step-by-step to explain what's going +on. + +.. rubric:: The directive class + +The first thing to examine is the ``RecipeDirective`` directive: + +.. literalinclude:: examples/recipe.py + :language: python + :linenos: + :pyobject: RecipeDirective + +Unlike :doc:`helloworld` and :doc:`todo`, 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 +because ``ObjectDescription`` is a special-purpose directive that's intended +for describing things like classes, functions, or, in our case, recipes. More +specifically, ``handle_signature`` implements parsing the signature of the +directive and passes on the object's name and type to its superclass, while +``add_target_and_index`` adds a target (to link to) and an entry to the index +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. + +.. rubric:: The index classes + +.. currentmodule:: sphinx.domains + +.. todo:: Add brief overview of indices + +.. literalinclude:: examples/recipe.py + :language: python + :linenos: + :pyobject: IngredientIndex + +.. literalinclude:: examples/recipe.py + :language: python + :linenos: + :pyobject: RecipeIndex + +Both ``IngredientIndex`` and ``RecipeIndex`` are derived from :class:`Index`. +They implement custom logic to generate a tuple of values that define the +index. Note that ``RecipeIndex`` is a simple index that has only one entry. +Extending it to cover more object types is not yet part of the code. + +Both indices use the method :meth:`Index.generate` to do their work. This +method combines the information from our domain, sorts it, and returns it in a +list structure that will be accepted by Sphinx. This might look complicated but +all it really is is a list of tuples like ``('tomato', 'TomatoSoup', 'test', +'rec-TomatoSoup',...)``. Refer to the :doc:`domain API guide +</extdev/domainapi>` for more information on this API. + +These index pages can be referenced with the :rst:role:`ref` role by combining +the domain name and the index ``name`` value. For example, ``RecipeIndex`` can be +referenced with ``:ref:`recipe-recipe``` and ``IngredientIndex`` can be referenced +with ``:ref:`recipe-ingredient```. + +.. rubric:: The domain + +A Sphinx domain is a specialized container that ties together roles, +directives, and indices, among other things. Let's look at the domain we're +creating here. + +.. literalinclude:: examples/recipe.py + :language: python + :linenos: + :pyobject: RecipeDomain + +There are some interesting things to note about this ``recipe`` domain and domains +in general. Firstly, we actually register our directives, roles and indices +here, via the ``directives``, ``roles`` and ``indices`` attributes, rather than +via calls later on in ``setup``. We can also note that we aren't actually +defining a custom role and are instead reusing the +:class:`sphinx.roles.XRefRole` role and defining the +:class:`sphinx.domains.Domain.resolve_xref` method. This method takes two +arguments, ``typ`` and ``target``, which refer to the cross-reference type and +its target name. We'll use ``target`` to resolve our destination from our +domain's ``recipes`` because we currently have only one type of node. + +Moving on, we can see that we've defined ``initial_data``. The values defined in +``initial_data`` will be copied to ``env.domaindata[domain_name]`` as the +initial data of the domain, and domain instances can access it via +``self.data``. We see that we have defined two items in ``initial_data``: +``recipes`` and ``recipe_ingredients``. Each contains a list of all objects +defined (i.e. all recipes) and a hash that maps a canonical ingredient name to +the list of objects. The way we name objects is common across our extension and +is defined in the ``get_full_qualified_name`` method. For each object created, +the canonical name is ``recipe.<recipename>``, where ``<recipename>`` is the +name the documentation writer gives the object (a recipe). This enables the +extension to use different object types that share the same name. Having a +canonical name and central place for our objects is a huge advantage. Both our +indices and our cross-referencing code use this feature. + +.. rubric:: The ``setup`` function + +.. currentmodule:: sphinx.application + +:doc:`As always <todo>`, 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. + +.. literalinclude:: examples/recipe.py + :language: python + :linenos: + :pyobject: setup + +This looks a little different to what we're used to seeing. There are no calls +to :meth:`~Sphinx.add_directive` or even :meth:`~Sphinx.add_role`. Instead, we +have a single call to :meth:`~Sphinx.add_domain` followed by some +initialization of the :ref:`standard domain <domains-std>`. This is because we +had already registered our directives, roles and indexes as part of the +directive itself. + + +Using the extension +------------------- + +You can now use the extension throughout your project. For example: + +.. code-block:: rst + :caption: index.rst + + Joe's Recipes + ============= + + Below are a collection of my favourite recipes. I highly recommend the + :recipe:ref:`TomatoSoup` recipe in particular! + + .. toctree:: + + tomato-soup + +.. code-block:: rst + :caption: tomato-soup.rst + + The recipe contains `tomato` and `cilantro`. + + .. recipe:recipe:: TomatoSoup + :contains: tomato, cilantro, salt, pepper + + This recipe is a tasty tomato soup, combine all ingredients + and cook. + +The important things to note are the use of the ``:recipe:ref:`` role to +cross-reference the recipe actually defined elsewhere (using the +``:recipe:recipe:`` directive). + + +Further reading +--------------- + +For more information, refer to the `docutils`_ documentation and +:doc:`/extdev/index`. + +.. _docutils: https://docutils.sourceforge.io/docs/ diff --git a/doc/development/tutorials/todo.rst b/doc/development/tutorials/todo.rst new file mode 100644 index 0000000..f23d8ad --- /dev/null +++ b/doc/development/tutorials/todo.rst @@ -0,0 +1,367 @@ +Developing a "TODO" extension +============================= + +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. + + +Overview +-------- + +.. note:: + To understand the design of this extension, refer to + :ref:`important-objects` and :ref:`build-phases`. + +We want the extension to add the following to Sphinx: + +* A ``todo`` directive, containing some content that is marked with "TODO" and + only shown in the output if a new config value is set. Todo entries should not + be in the output by default. + +* A ``todolist`` directive that creates a list of all todo entries throughout + the documentation. + +For that, we will need to add the following elements to Sphinx: + +* New directives, called ``todo`` and ``todolist``. + +* New document tree nodes to represent these directives, conventionally also + called ``todo`` and ``todolist``. We wouldn't need new nodes if the new + directives only produced some content representable by existing nodes. + +* A new config value ``todo_include_todos`` (config value names should start + with the extension name, in order to stay unique) that controls whether todo + entries make it into the output. + +* New event handlers: one for the :event:`doctree-resolved` event, to + replace the todo and todolist nodes, one for :event:`env-merge-info` + to merge intermediate results from parallel builds, and one for + :event:`env-purge-doc` (the reason for that will be covered later). + + +Prerequisites +------------- + +As with :doc:`helloworld`, 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`. + +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:`todo.py` + +Here is an example of the folder structure you might obtain: + +.. code-block:: text + + └── source + ├── _ext + │ └── todo.py + ├── _static + ├── conf.py + ├── somefolder + ├── index.rst + ├── somefile.rst + └── someotherfile.rst + + +Writing the extension +--------------------- + +Open :file:`todo.py` and paste the following code in it, all of which we will +explain in detail shortly: + +.. literalinclude:: examples/todo.py + :language: python + :linenos: + +This is far more extensive extension than the one detailed in :doc:`helloworld`, +however, we will will look at each piece step-by-step to explain what's +happening. + +.. rubric:: The node classes + +Let's start with the node classes: + +.. literalinclude:: examples/todo.py + :language: python + :linenos: + :lines: 8-21 + +Node classes usually don't have to do anything except inherit from the standard +docutils classes defined in :mod:`docutils.nodes`. ``todo`` inherits from +``Admonition`` because it should be handled like a note or warning, ``todolist`` +is just a "general" node. + +.. note:: + + Many extensions will not have to create their own node classes and work fine + with the nodes already provided by `docutils + <https://docutils.sourceforge.io/docs/ref/doctree.html>`__ and :ref:`Sphinx + <nodes>`. + +.. attention:: + + It is important to know that while you can extend Sphinx without + leaving your ``conf.py``, if you declare an inherited node right + there, you'll hit an unobvious :py:class:`~pickle.PickleError`. So if + something goes wrong, please make sure that you put inherited nodes + into a separate Python module. + + For more details, see: + + - https://github.com/sphinx-doc/sphinx/issues/6751 + - https://github.com/sphinx-doc/sphinx/issues/1493 + - https://github.com/sphinx-doc/sphinx/issues/1424 + +.. rubric:: The directive classes + +A directive class is a class deriving usually from +:class:`docutils.parsers.rst.Directive`. The directive interface is also +covered in detail in the `docutils documentation`_; the important thing is that +the class should have attributes that configure the allowed markup, and a +``run`` method that returns a list of nodes. + +Looking first at the ``TodolistDirective`` directive: + +.. literalinclude:: examples/todo.py + :language: python + :linenos: + :lines: 24-27 + +It's very simple, creating and returning an instance of our ``todolist`` node +class. The ``TodolistDirective`` directive itself has neither content nor +arguments that need to be handled. That brings us to the ``TodoDirective`` +directive: + +.. literalinclude:: examples/todo.py + :language: python + :linenos: + :lines: 30-53 + +Several important things are covered here. First, as you can see, we're now +subclassing the :class:`~sphinx.util.docutils.SphinxDirective` helper class +instead of the usual :class:`~docutils.parsers.rst.Directive` class. This +gives us access to the :ref:`build environment instance <important-objects>` +using the ``self.env`` property. Without this, we'd have to use the rather +convoluted ``self.state.document.settings.env``. Then, to act as a link target +(from ``TodolistDirective``), the ``TodoDirective`` directive needs to return a +target node in addition to the ``todo`` node. The target ID (in HTML, this will +be the anchor name) is generated by using ``env.new_serialno`` which returns a +new unique integer on each call and therefore leads to unique target names. The +target node is instantiated without any text (the first two arguments). + +On creating admonition node, the content body of the directive are parsed using +``self.state.nested_parse``. The first argument gives the content body, and +the second one gives content offset. The third argument gives the parent node +of parsed result, in our case the ``todo`` node. Following this, the ``todo`` +node is added to the environment. This is needed to be able to create a list of +all todo entries throughout the documentation, in the place where the author +puts a ``todolist`` directive. For this case, the environment attribute +``todo_all_todos`` is used (again, the name should be unique, so it is prefixed +by the extension name). It does not exist when a new environment is created, so +the directive must check and create it if necessary. Various information about +the todo entry's location are stored along with a copy of the node. + +In the last line, the nodes that should be put into the doctree are returned: +the target node and the admonition node. + +The node structure that the directive returns looks like this:: + + +--------------------+ + | target node | + +--------------------+ + +--------------------+ + | todo node | + +--------------------+ + \__+--------------------+ + | admonition title | + +--------------------+ + | paragraph | + +--------------------+ + | ... | + +--------------------+ + +.. rubric:: The event handlers + +Event handlers are one of Sphinx's most powerful features, providing a way to +do hook into any part of the documentation process. There are many events +provided by Sphinx itself, as detailed in :ref:`the API guide <events>`, and +we're going to use a subset of them here. + +Let's look at the event handlers used in the above example. First, the one for +the :event:`env-purge-doc` event: + +.. literalinclude:: examples/todo.py + :language: python + :linenos: + :lines: 56-61 + +Since we store information from source files in the environment, which is +persistent, it may become out of date when the source file changes. Therefore, +before each source file is read, the environment's records of it are cleared, +and the :event:`env-purge-doc` event gives extensions a chance to do the same. +Here we clear out all todos whose docname matches the given one from the +``todo_all_todos`` list. If there are todos left in the document, they will be +added again during parsing. + +The next handler, for the :event:`env-merge-info` event, is used +during parallel builds. As during parallel builds all threads have +their own ``env``, there's multiple ``todo_all_todos`` lists that need +to be merged: + +.. literalinclude:: examples/todo.py + :language: python + :linenos: + :lines: 64-68 + + +The other handler belongs to the :event:`doctree-resolved` event: + +.. literalinclude:: examples/todo.py + :language: python + :linenos: + :lines: 71-113 + +The :event:`doctree-resolved` event is emitted at the end of :ref:`phase 3 +(resolving) <build-phases>` and allows custom resolving to be done. The handler +we have written for this event is a bit more involved. If the +``todo_include_todos`` config value (which we'll describe shortly) is false, +all ``todo`` and ``todolist`` nodes are removed from the documents. If not, +``todo`` nodes just stay where and how they are. ``todolist`` nodes are +replaced by a list of todo entries, complete with backlinks to the location +where they come from. The list items are composed of the nodes from the +``todo`` entry and docutils nodes created on the fly: a paragraph for each +entry, containing text that gives the location, and a link (reference node +containing an italic node) with the backreference. The reference URI is built +by :meth:`sphinx.builders.Builder.get_relative_uri` which creates a suitable +URI depending on the used builder, and appending the todo node's (the target's) +ID as the anchor name. + +.. rubric:: The ``setup`` function + +.. currentmodule:: sphinx.application + +As noted :doc:`previously <helloworld>`, 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: + +.. literalinclude:: examples/todo.py + :language: python + :linenos: + :lines: 116- + +The calls in this function refer to the classes and functions we added earlier. +What the individual calls do is the following: + +* :meth:`~Sphinx.add_config_value` lets Sphinx know that it should recognize the + new *config value* ``todo_include_todos``, whose default value should be + ``False`` (this also tells Sphinx that it is a boolean value). + + If the third argument was ``'html'``, HTML documents would be full rebuild if the + config value changed its value. This is needed for config values that + influence reading (build :ref:`phase 1 (reading) <build-phases>`). + +* :meth:`~Sphinx.add_node` adds a new *node class* to the build system. It also + can specify visitor functions for each supported output format. These visitor + functions are needed when the new nodes stay until :ref:`phase 4 (writing) + <build-phases>`. Since the ``todolist`` node is always replaced in + :ref:`phase 3 (resolving) <build-phases>`, it doesn't need any. + +* :meth:`~Sphinx.add_directive` adds a new *directive*, given by name and class. + +* Finally, :meth:`~Sphinx.connect` adds an *event handler* to the event whose + name is given by the first argument. The event handler function is called + with several arguments which are documented with the event. + +With this, our extension is complete. + + +Using the extension +------------------- + +As before, we need to enable the extension by declaring it in our +:file:`conf.py` file. 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 + +In addition, we may wish to set the ``todo_include_todos`` config value. As +noted above, this defaults to ``False`` but we can set it explicitly. + +For example: + +.. code-block:: python + + import os + import sys + + sys.path.append(os.path.abspath("./_ext")) + + extensions = ['todo'] + + todo_include_todos = False + +You can now use the extension throughout your project. For example: + +.. code-block:: rst + :caption: index.rst + + Hello, world + ============ + + .. toctree:: + somefile.rst + someotherfile.rst + + Hello world. Below is the list of TODOs. + + .. todolist:: + +.. code-block:: rst + :caption: somefile.rst + + foo + === + + Some intro text here... + + .. todo:: Fix this + +.. code-block:: rst + :caption: someotherfile.rst + + bar + === + + Some more text here... + + .. todo:: Fix that + +Because we have configured ``todo_include_todos`` to ``False``, we won't +actually see anything rendered for the ``todo`` and ``todolist`` directives. +However, if we toggle this to true, we will see the output described +previously. + + +Further reading +--------------- + +For more information, refer to the `docutils`_ documentation and +:doc:`/extdev/index`. + + +.. _docutils: https://docutils.sourceforge.io/docs/ +.. _Python path: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH +.. _docutils documentation: https://docutils.sourceforge.io/docs/ref/rst/directives.html diff --git a/doc/examples.rst b/doc/examples.rst new file mode 100644 index 0000000..c28364a --- /dev/null +++ b/doc/examples.rst @@ -0,0 +1,5 @@ +:tocdepth: 2 + +.. _examples: + +.. include:: ../EXAMPLES diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst new file mode 100644 index 0000000..270000b --- /dev/null +++ b/doc/extdev/appapi.rst @@ -0,0 +1,473 @@ +.. highlight:: rest + +Application API +=============== + +.. module:: sphinx.application + :synopsis: Application class and extensibility interface. + + +Each Sphinx extension is a Python module with at least a :func:`setup` +function. This function is called at initialization time with one argument, +the application object representing the Sphinx process. + +.. class:: Sphinx + + This application object has the public API described in the following. + +Extension setup +--------------- + +These methods are usually called in an extension's ``setup()`` function. + +Examples of using the Sphinx extension API can be seen in the :mod:`sphinx.ext` +package. + +.. currentmodule:: sphinx.application + +.. automethod:: Sphinx.setup_extension + +.. automethod:: Sphinx.require_sphinx + +.. automethod:: Sphinx.connect + +.. automethod:: Sphinx.disconnect + +.. automethod:: Sphinx.add_builder + +.. automethod:: Sphinx.add_config_value + +.. automethod:: Sphinx.add_event + +.. automethod:: Sphinx.set_translator + +.. automethod:: Sphinx.add_node + +.. automethod:: Sphinx.add_enumerable_node + +.. automethod:: Sphinx.add_directive + +.. automethod:: Sphinx.add_role + +.. automethod:: Sphinx.add_generic_role + +.. automethod:: Sphinx.add_domain + +.. automethod:: Sphinx.add_directive_to_domain + +.. automethod:: Sphinx.add_role_to_domain + +.. automethod:: Sphinx.add_index_to_domain + +.. automethod:: Sphinx.add_object_type + +.. automethod:: Sphinx.add_crossref_type + +.. automethod:: Sphinx.add_transform + +.. automethod:: Sphinx.add_post_transform + +.. automethod:: Sphinx.add_js_file + +.. automethod:: Sphinx.add_css_file + +.. automethod:: Sphinx.add_latex_package + +.. automethod:: Sphinx.add_lexer + +.. automethod:: Sphinx.add_autodocumenter + +.. automethod:: Sphinx.add_autodoc_attrgetter + +.. automethod:: Sphinx.add_search_language + +.. automethod:: Sphinx.add_source_suffix + +.. automethod:: Sphinx.add_source_parser + +.. automethod:: Sphinx.add_env_collector + +.. automethod:: Sphinx.add_html_theme + +.. automethod:: Sphinx.add_html_math_renderer + +.. automethod:: Sphinx.add_message_catalog + +.. automethod:: Sphinx.is_parallel_allowed + +.. exception:: ExtensionError + + All these methods raise this exception if something went wrong with the + extension API. + + +Emitting events +--------------- + +.. class:: Sphinx + :no-index: + + .. automethod:: emit + + .. automethod:: emit_firstresult + + +Sphinx runtime information +-------------------------- + +The application object also provides runtime information as attributes. + +.. attribute:: Sphinx.project + + Target project. See :class:`.Project`. + +.. attribute:: Sphinx.srcdir + + Source directory. + +.. attribute:: Sphinx.confdir + + Directory containing ``conf.py``. + +.. attribute:: Sphinx.doctreedir + + Directory for storing pickled doctrees. + +.. attribute:: Sphinx.outdir + + Directory for storing built document. + + +.. _events: + +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 + + +Checking the Sphinx version +--------------------------- + +.. currentmodule:: sphinx + +Use this to adapt your extension to API changes in Sphinx. + +.. autodata:: version_info + + +The Config object +----------------- + +.. currentmodule:: sphinx.config + +.. autoclass:: Config + + +.. _template-bridge: + +The template bridge +------------------- + +.. currentmodule:: sphinx.application + +.. autoclass:: TemplateBridge + :members: + + +.. _exceptions: + +Exceptions +---------- + +.. module:: sphinx.errors + +.. autoexception:: SphinxError + +.. autoexception:: ConfigError + +.. autoexception:: ExtensionError + +.. autoexception:: ThemeError + +.. autoexception:: VersionRequirementError diff --git a/doc/extdev/builderapi.rst b/doc/extdev/builderapi.rst new file mode 100644 index 0000000..5c5a525 --- /dev/null +++ b/doc/extdev/builderapi.rst @@ -0,0 +1,46 @@ +.. _writing-builders: + +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: + + .. autoattribute:: name + .. autoattribute:: format + .. autoattribute:: epilog + .. autoattribute:: allow_parallel + .. autoattribute:: supported_image_types + .. autoattribute:: supported_remote_images + .. autoattribute:: supported_data_uri_images + .. autoattribute:: default_translator_class + + These methods are predefined and will be called from the application: + + .. automethod:: get_relative_uri + .. automethod:: build_all + .. automethod:: build_specific + .. automethod:: build_update + .. automethod:: build + + These methods can be overridden in concrete builder classes: + + .. automethod:: init + .. automethod:: get_outdated_docs + .. automethod:: get_target_uri + .. automethod:: prepare_writing + .. automethod:: write_doc + .. automethod:: finish + + **Attributes** + + .. attribute:: events + + An :class:`.EventManager` object. diff --git a/doc/extdev/collectorapi.rst b/doc/extdev/collectorapi.rst new file mode 100644 index 0000000..cb4c30b --- /dev/null +++ b/doc/extdev/collectorapi.rst @@ -0,0 +1,9 @@ +.. _collector-api: + +Environment Collector API +------------------------- + +.. module:: sphinx.environment.collectors + +.. autoclass:: EnvironmentCollector + :members: diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst new file mode 100644 index 0000000..f90389c --- /dev/null +++ b/doc/extdev/deprecated.rst @@ -0,0 +1,1911 @@ +.. _dev-deprecated-apis: + +Deprecated APIs +=============== + +On developing Sphinx, we are always careful to the compatibility of our APIs. +But, sometimes, the change of interface are needed for some reasons. In such +cases, we've marked them as deprecated. And they are kept during the two +major versions (for more details, please see :ref:`deprecation-policy`). + +The following is a list of deprecated interfaces. + +.. tabularcolumns:: >{\raggedright}\Y{.4}>{\centering}\Y{.1}>{\sphinxcolorblend{!95!red}\centering\noindent\bfseries\color{red}}\Y{.12}>{\raggedright\arraybackslash}\Y{.38} + +.. list-table:: deprecated APIs + :header-rows: 1 + :class: deprecated + :widths: 40, 10, 10, 40 + + * - Target + - Deprecated + - Removed + - Alternatives + + * - ``sphinx.ext.autodoc.preserve_defaults.get_function_def()`` + - 7.2 + - 9.0 + - N/A (replacement is private) + + * - ``sphinx.builders.html.StandaloneHTMLBuilder.css_files`` + - 7.2 + - 9.0 + - N/A + + * - ``sphinx.builders.html.StandaloneHTMLBuilder.script_files`` + - 7.2 + - 9.0 + - N/A + + * - ``sphinx.builders.html.Stylesheet`` + - 7.2 + - 9.0 + - ``sphinx.application.Sphinx.add_css_file()`` + + * - ``sphinx.builders.html.JavaScript`` + - 7.2 + - 9.0 + - ``sphinx.application.Sphinx.add_js_file()`` + + * - ``sphinx.util.split_into`` + - 7.2 + - 9.0 + - N/A + + * - ``sphinx.util.split_index_msg`` + - 7.2 + - 9.0 + - ``sphinx.util.index_entries.split_index_msg`` + + * - ``sphinx.testing.path`` + - 7.2 + - 9.0 + - ``os.path`` or ``pathlib`` + + * - ``sphinx.util.md5`` + - 7.2 + - 9.0 + - ``hashlib.md5`` + + * - ``sphinx.util.sha1`` + - 7.2 + - 9.0 + - ``hashlib.sha1`` + + * - ``sphinx.util.osutil.cd`` + - 6.2 + - 8.0 + - ``contextlib.chdir`` + + * - ``sphinx.util.save_traceback`` + - 6.1 + - 8.0 + - ``sphinx.util.exceptions.save_traceback`` + + * - ``sphinx.util.format_exception_cut_frames`` + - 6.1 + - 8.0 + - ``sphinx.util.exceptions.format_exception_cut_frames`` + + * - ``sphinx.util.epoch_to_rfc1123`` + - 6.1 + - 8.0 + - ``sphinx.util.http_date.epoch_to_rfc1123`` + + * - ``sphinx.util.rfc1123_to_epoch`` + - 6.1 + - 8.0 + - ``sphinx.util.http_date.rfc1123_to_epoch`` + + * - ``sphinx.util.status_iterator`` + - 6.1 + - 8.0 + - ``sphinx.util.display.status_iterator`` + + * - ``sphinx.util.display_chunk`` + - 6.1 + - 8.0 + - ``sphinx.util.display.display_chunk`` + + * - ``sphinx.util.SkipProgressMessage`` + - 6.1 + - 8.0 + - ``sphinx.util.display.SkipProgressMessage`` + + * - ``sphinx.util.progress_message`` + - 6.1 + - 8.0 + - ``sphinx.util.display.progress_message`` + + * - ``sphinx.util.typing.stringify`` + - 6.1 + - 8.0 + - ``sphinx.util.typing.stringify_annotation`` + + * - HTML 4 support + - 5.2 + - 7.0 + - N/A + + * - ``sphinx.util.path_stabilize`` + - 5.1 + - 7.0 + - ``sphinx.util.osutil.path_stabilize`` + + * - ``sphinx.util.get_matching_files`` + - 5.1 + - 7.0 + - ``sphinx.util.matching.get_matching_files`` + + * - ``sphinx.ext.napoleon.iterators`` + - 5.1 + - 7.0 + - ``pockets.iterators`` + + * - ``sphinx.util.stemmer`` + - 5.1 + - 7.0 + - ``snowballstemmer`` + + * - ``sphinx.util.jsdump`` + - 5.0 + - 7.0 + - The standard library ``json`` module. + + * - The Setuptools integration (``setup.py build_sphinx``) + - 5.0 + - 7.0 + - N/A + + * - The ``locale`` argument of ``sphinx.util.i18n:babel_format_date()`` + - 5.0 + - 7.0 + - N/A + + * - The ``language`` argument of ``sphinx.util.i18n:format_date()`` + - 5.0 + - 7.0 + - N/A + + * - ``sphinx.builders.html.html5_ready`` + - 5.0 + - 7.0 + - N/A + + * - ``sphinx.io.read_doc()`` + - 5.0 + - 7.0 + - ``sphinx.builders.Builder.read_doc()`` + + * - ``sphinx.util.docutils.__version_info__`` + - 5.0 + - 7.0 + - ``docutils.__version_info__`` + + * - ``sphinx.util.docutils.is_html5_writer_available()`` + - 5.0 + - 7.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXWriter.docclasses`` + - 5.0 + - 7.0 + - N/A + + * - ``sphinx.ext.napoleon.docstring.GoogleDocstring._qualify_name()`` + - 4.5 + - 6.0 + - N/A + + * - ``sphinx.ext.autodoc.AttributeDocumenter._datadescriptor`` + - 4.3 + - 6.0 + - N/A + + * - ``sphinx.writers.html.HTMLTranslator._fieldlist_row_index`` + - 4.3 + - 6.0 + - ``sphinx.writers.html.HTMLTranslator._fieldlist_row_indices`` + + * - ``sphinx.writers.html.HTMLTranslator._table_row_index`` + - 4.3 + - 6.0 + - ``sphinx.writers.html.HTMLTranslator._table_row_indices`` + + * - ``sphinx.writers.html5.HTML5Translator._fieldlist_row_index`` + - 4.3 + - 6.0 + - ``sphinx.writers.html5.HTML5Translator._fieldlist_row_indices`` + + * - ``sphinx.writers.html5.HTML5Translator._table_row_index`` + - 4.3 + - 6.0 + - ``sphinx.writers.html5.HTML5Translator._table_row_indices`` + + * - The optional argument ``app`` for ``sphinx.environment.BuildEnvironment`` + - 4.1 + - 6.0 + - The required argument + + * - ``sphinx.application.Sphinx.html_theme`` + - 4.1 + - 6.0 + - ``sphinx.registry.SphinxComponentRegistry.html_themes`` + + * - ``sphinx.ext.autosummary._app`` + - 4.1 + - 6.0 + - N/A + + * - ``sphinx.util.docstrings.extract_metadata()`` + - 4.1 + - 6.0 + - ``sphinx.util.docstrings.separate_metadata()`` + + * - ``favicon`` variable in HTML templates + - 4.0 + - 6.0 + - ``favicon_url`` + + * - ``logo`` variable in HTML templates + - 4.0 + - 6.0 + - ``logo_url`` + + * - ``sphinx.directives.patches.ListTable`` + - 4.0 + - 6.0 + - ``docutils.parsers.rst.directives.tables.ListSVTable`` + + * - ``sphinx.directives.patches.RSTTable`` + - 4.0 + - 6.0 + - ``docutils.parsers.rst.directives.tables.RSTTable`` + + * - ``sphinx.ext.autodoc.directive.DocumenterBridge.filename_set`` + - 4.0 + - 6.0 + - ``sphinx.ext.autodoc.directive.DocumenterBridge.record_dependencies`` + + * - ``sphinx.ext.autodoc.directive.DocumenterBridge.warn()`` + - 4.0 + - 6.0 + - :ref:`logging-api` + + * - ``sphinx.registry.SphinxComponentRegistry.get_source_input()`` + - 4.0 + - 6.0 + - N/A + + * - ``sphinx.registry.SphinxComponentRegistry.source_inputs`` + - 4.0 + - 6.0 + - N/A + + * - ``sphinx.transforms.FigureAligner`` + - 4.0 + - 6.0 + - N/A + + * - ``sphinx.util.pycompat.convert_with_2to3()`` + - 4.0 + - 6.0 + - N/A + + * - ``sphinx.util.pycompat.execfile_()`` + - 4.0 + - 6.0 + - N/A + + * - ``sphinx.util.smartypants`` + - 4.0 + - 6.0 + - ``docutils.utils.smartquotes`` + + * - ``sphinx.util.typing.DirectiveOption`` + - 4.0 + - 6.0 + - N/A + + * - pending_xref node for viewcode extension + - 3.5 + - 5.0 + - ``sphinx.ext.viewcode.viewcode_anchor`` + + * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.anchors_ignore`` + - 3.5 + - 5.0 + - N/A + + * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.auth`` + - 3.5 + - 5.0 + - N/A + + * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.broken`` + - 3.5 + - 5.0 + - N/A + + * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.good`` + - 3.5 + - 5.0 + - N/A + + * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.redirected`` + - 3.5 + - 5.0 + - N/A + + * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.rqueue`` + - 3.5 + - 5.0 + - N/A + + * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.to_ignore`` + - 3.5 + - 5.0 + - N/A + + * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.workers`` + - 3.5 + - 5.0 + - N/A + + * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.wqueue`` + - 3.5 + - 5.0 + - N/A + + * - ``sphinx.builders.linkcheck.node_line_or_0()`` + - 3.5 + - 5.0 + - ``sphinx.util.nodes.get_node_line()`` + + * - ``sphinx.ext.autodoc.AttributeDocumenter.isinstanceattribute()`` + - 3.5 + - 5.0 + - N/A + + * - ``sphinx.ext.autodoc.importer.get_module_members()`` + - 3.5 + - 5.0 + - ``sphinx.ext.autodoc.ModuleDocumenter.get_module_members()`` + + * - ``sphinx.ext.autosummary.generate._simple_info()`` + - 3.5 + - 5.0 + - :ref:`logging-api` + + * - ``sphinx.ext.autosummary.generate._simple_warn()`` + - 3.5 + - 5.0 + - :ref:`logging-api` + + * - ``sphinx.writers.html.HTMLTranslator.permalink_text`` + - 3.5 + - 5.0 + - :confval:`html_permalinks_icon` + + * - ``sphinx.writers.html5.HTML5Translator.permalink_text`` + - 3.5 + - 5.0 + - :confval:`html_permalinks_icon` + + * - The ``follow_wrapped`` argument of ``sphinx.util.inspect.signature()`` + - 3.4 + - 5.0 + - N/A + + * - The ``no_docstring`` argument of + ``sphinx.ext.autodoc.Documenter.add_content()`` + - 3.4 + - 5.0 + - ``sphinx.ext.autodoc.Documenter.get_doc()`` + + * - ``sphinx.ext.autodoc.Documenter.get_object_members()`` + - 3.4 + - 6.0 + - ``sphinx.ext.autodoc.ClassDocumenter.get_object_members()`` + + * - ``sphinx.ext.autodoc.DataDeclarationDocumenter`` + - 3.4 + - 5.0 + - ``sphinx.ext.autodoc.DataDocumenter`` + + * - ``sphinx.ext.autodoc.GenericAliasDocumenter`` + - 3.4 + - 5.0 + - ``sphinx.ext.autodoc.DataDocumenter`` + + * - ``sphinx.ext.autodoc.InstanceAttributeDocumenter`` + - 3.4 + - 5.0 + - ``sphinx.ext.autodoc.AttributeDocumenter`` + + * - ``sphinx.ext.autodoc.SlotsAttributeDocumenter`` + - 3.4 + - 5.0 + - ``sphinx.ext.autodoc.AttributeDocumenter`` + + * - ``sphinx.ext.autodoc.TypeVarDocumenter`` + - 3.4 + - 5.0 + - ``sphinx.ext.autodoc.DataDocumenter`` + + * - ``sphinx.ext.autodoc.directive.DocumenterBridge.reporter`` + - 3.5 + - 5.0 + - ``sphinx.util.logging`` + + * - ``sphinx.ext.autodoc.importer._getannotations()`` + - 3.4 + - 4.0 + - ``sphinx.util.inspect.getannotations()`` + + * - ``sphinx.ext.autodoc.importer._getmro()`` + - 3.4 + - 4.0 + - ``sphinx.util.inspect.getmro()`` + + * - ``sphinx.pycode.ModuleAnalyzer.parse()`` + - 3.4 + - 5.0 + - ``sphinx.pycode.ModuleAnalyzer.analyze()`` + + * - ``sphinx.util.osutil.movefile()`` + - 3.4 + - 5.0 + - ``os.replace()`` + + * - ``sphinx.util.requests.is_ssl_error()`` + - 3.4 + - 5.0 + - N/A + + * - ``sphinx.builders.latex.LaTeXBuilder.usepackages`` + - 3.3 + - 5.0 + - N/A + + * - ``sphinx.builders.latex.LaTeXBuilder.usepackages_afger_hyperref`` + - 3.3 + - 5.0 + - N/A + + * - ``sphinx.ext.autodoc.SingledispatchFunctionDocumenter`` + - 3.3 + - 5.0 + - ``sphinx.ext.autodoc.FunctionDocumenter`` + + * - ``sphinx.ext.autodoc.SingledispatchMethodDocumenter`` + - 3.3 + - 5.0 + - ``sphinx.ext.autodoc.MethodDocumenter`` + + * - ``sphinx.ext.autodoc.members_set_option()`` + - 3.2 + - 5.0 + - N/A + + * - ``sphinx.ext.autodoc.merge_special_members_option()`` + - 3.2 + - 5.0 + - ``sphinx.ext.autodoc.merge_members_option()`` + + * - ``sphinx.writers.texinfo.TexinfoWriter.desc`` + - 3.2 + - 5.0 + - ``sphinx.writers.texinfo.TexinfoWriter.descs`` + + * - The first argument for + ``sphinx.ext.autosummary.generate.AutosummaryRenderer`` has been changed + to Sphinx object + - 3.1 + - 5.0 + - N/A + + * - ``sphinx.ext.autosummary.generate.AutosummaryRenderer`` takes an object + type as an argument + - 3.1 + - 5.0 + - N/A + + * - The ``ignore`` argument of ``sphinx.ext.autodoc.Documenter.get_doc()`` + - 3.1 + - 5.0 + - N/A + + * - The ``template_dir`` argument of + ``sphinx.ext.autosummary.generate.AutosummaryRenderer`` + - 3.1 + - 5.0 + - N/A + + * - The ``module`` argument of + ``sphinx.ext.autosummary.generate.find_autosummary_in_docstring()`` + - 3.0 + - 5.0 + - N/A + + * - The ``builder`` argument of + ``sphinx.ext.autosummary.generate.generate_autosummary_docs()`` + - 3.1 + - 5.0 + - N/A + + * - The ``template_dir`` argument of + ``sphinx.ext.autosummary.generate.generate_autosummary_docs()`` + - 3.1 + - 5.0 + - N/A + + * - ``sphinx.ext.autosummary.generate.AutosummaryRenderer.exists()`` + - 3.1 + - 5.0 + - N/A + + * - The ``ignore`` argument of ``sphinx.util.docstring.prepare_docstring()`` + - 3.1 + - 5.0 + - N/A + + * - ``sphinx.util.rpartition()`` + - 3.1 + - 5.0 + - ``str.rpartition()`` + + * - ``desc_signature['first']`` + - + - 3.0 + - N/A + + * - ``sphinx.directives.DescDirective`` + - 3.0 + - 5.0 + - ``sphinx.directives.ObjectDescription`` + + * - ``sphinx.domains.std.StandardDomain.add_object()`` + - 3.0 + - 5.0 + - ``sphinx.domains.std.StandardDomain.note_object()`` + + * - ``sphinx.domains.python.PyDecoratorMixin`` + - 3.0 + - 5.0 + - N/A + + * - ``sphinx.ext.autodoc.get_documenters()`` + - 3.0 + - 5.0 + - ``sphinx.registry.documenters`` + + * - ``sphinx.ext.autosummary.process_autosummary_toc()`` + - 3.0 + - 5.0 + - N/A + + * - ``sphinx.parsers.Parser.app`` + - 3.0 + - 5.0 + - N/A + + * - ``sphinx.testing.path.Path.text()`` + - 3.0 + - 5.0 + - ``sphinx.testing.path.Path.read_text()`` + + * - ``sphinx.testing.path.Path.bytes()`` + - 3.0 + - 5.0 + - ``sphinx.testing.path.Path.read_bytes()`` + + * - ``sphinx.util.inspect.getargspec()`` + - 3.0 + - 5.0 + - ``inspect.getargspec()`` + + * - ``sphinx.writers.latex.LaTeXWriter.format_docclass()`` + - 3.0 + - 5.0 + - LaTeX Themes + + * - ``decode`` argument of ``sphinx.pycode.ModuleAnalyzer()`` + - 2.4 + - 4.0 + - N/A + + * - ``sphinx.directives.other.Index`` + - 2.4 + - 4.0 + - ``sphinx.domains.index.IndexDirective`` + + * - ``sphinx.environment.temp_data['gloss_entries']`` + - 2.4 + - 4.0 + - ``documents.nameids`` + + * - ``sphinx.environment.BuildEnvironment.indexentries`` + - 2.4 + - 4.0 + - ``sphinx.domains.index.IndexDomain`` + + * - ``sphinx.environment.collectors.indexentries.IndexEntriesCollector`` + - 2.4 + - 4.0 + - ``sphinx.domains.index.IndexDomain`` + + * - ``sphinx.io.FiletypeNotFoundError`` + - 2.4 + - 4.0 + - ``sphinx.errors.FiletypeNotFoundError`` + + * - ``sphinx.ext.apidoc.INITPY`` + - 2.4 + - 4.0 + - N/A + + * - ``sphinx.ext.apidoc.shall_skip()`` + - 2.4 + - 4.0 + - ``sphinx.ext.apidoc.is_skipped_package`` + + * - ``sphinx.io.get_filetype()`` + - 2.4 + - 4.0 + - ``sphinx.util.get_filetype()`` + + * - ``sphinx.pycode.ModuleAnalyzer.encoding`` + - 2.4 + - 4.0 + - N/A + + * - ``sphinx.roles.Index`` + - 2.4 + - 4.0 + - ``sphinx.domains.index.IndexRole`` + + * - ``sphinx.util.detect_encoding()`` + - 2.4 + - 4.0 + - ``tokenize.detect_encoding()`` + + * - ``sphinx.util.get_module_source()`` + - 2.4 + - 4.0 + - N/A + + * - ``sphinx.util.inspect.Signature`` + - 2.4 + - 4.0 + - ``sphinx.util.inspect.signature`` and + ``sphinx.util.inspect.stringify_signature()`` + + * - ``sphinx.util.inspect.safe_getmembers()`` + - 2.4 + - 4.0 + - ``inspect.getmembers()`` + + * - ``sphinx.writers.latex.LaTeXTranslator.settings.author`` + - 2.4 + - 4.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.settings.contentsname`` + - 2.4 + - 4.0 + - ``document['contentsname']`` + + * - ``sphinx.writers.latex.LaTeXTranslator.settings.docclass`` + - 2.4 + - 4.0 + - ``document['docclass']`` + + * - ``sphinx.writers.latex.LaTeXTranslator.settings.docname`` + - 2.4 + - 4.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.settings.title`` + - 2.4 + - 4.0 + - N/A + + * - ``sphinx.writers.latex.ADDITIONAL_SETTINGS`` + - 2.4 + - 4.0 + - ``sphinx.builders.latex.constants.ADDITIONAL_SETTINGS`` + + * - ``sphinx.writers.latex.DEFAULT_SETTINGS`` + - 2.4 + - 4.0 + - ``sphinx.builders.latex.constants.DEFAULT_SETTINGS`` + + * - ``sphinx.writers.latex.LUALATEX_DEFAULT_FONTPKG`` + - 2.4 + - 4.0 + - ``sphinx.builders.latex.constants.LUALATEX_DEFAULT_FONTPKG`` + + * - ``sphinx.writers.latex.PDFLATEX_DEFAULT_FONTPKG`` + - 2.4 + - 4.0 + - ``sphinx.builders.latex.constants.PDFLATEX_DEFAULT_FONTPKG`` + + * - ``sphinx.writers.latex.XELATEX_DEFAULT_FONTPKG`` + - 2.4 + - 4.0 + - ``sphinx.builders.latex.constants.XELATEX_DEFAULT_FONTPKG`` + + * - ``sphinx.writers.latex.XELATEX_GREEK_DEFAULT_FONTPKG`` + - 2.4 + - 4.0 + - ``sphinx.builders.latex.constants.XELATEX_GREEK_DEFAULT_FONTPKG`` + + * - ``sphinx.builders.gettext.POHEADER`` + - 2.3 + - 4.0 + - ``sphinx/templates/gettext/message.pot_t`` (template file) + + * - ``sphinx.io.SphinxStandaloneReader.app`` + - 2.3 + - 4.0 + - ``sphinx.io.SphinxStandaloneReader.setup()`` + + * - ``sphinx.io.SphinxStandaloneReader.env`` + - 2.3 + - 4.0 + - ``sphinx.io.SphinxStandaloneReader.setup()`` + + * - ``sphinx.util.texescape.tex_escape_map`` + - 2.3 + - 4.0 + - ``sphinx.util.texescape.escape()`` + + * - ``sphinx.util.texescape.tex_hl_escape_map_new`` + - 2.3 + - 4.0 + - ``sphinx.util.texescape.hlescape()`` + + * - ``sphinx.writers.latex.LaTeXTranslator.no_contractions`` + - 2.3 + - 4.0 + - N/A + + * - ``sphinx.domains.math.MathDomain.add_equation()`` + - 2.2 + - 4.0 + - ``sphinx.domains.math.MathDomain.note_equation()`` + + * - ``sphinx.domains.math.MathDomain.get_next_equation_number()`` + - 2.2 + - 4.0 + - ``sphinx.domains.math.MathDomain.note_equation()`` + + * - The ``info`` and ``warn`` arguments of + ``sphinx.ext.autosummary.generate.generate_autosummary_docs()`` + - 2.2 + - 4.0 + - ``logging.info()`` and ``logging.warning()`` + + * - ``sphinx.ext.autosummary.generate._simple_info()`` + - 2.2 + - 4.0 + - ``logging.info()`` + + * - ``sphinx.ext.autosummary.generate._simple_warn()`` + - 2.2 + - 4.0 + - ``logging.warning()`` + + * - ``sphinx.ext.todo.merge_info()`` + - 2.2 + - 4.0 + - ``sphinx.ext.todo.TodoDomain`` + + * - ``sphinx.ext.todo.process_todo_nodes()`` + - 2.2 + - 4.0 + - ``sphinx.ext.todo.TodoDomain`` + + * - ``sphinx.ext.todo.process_todos()`` + - 2.2 + - 4.0 + - ``sphinx.ext.todo.TodoDomain`` + + * - ``sphinx.ext.todo.purge_todos()`` + - 2.2 + - 4.0 + - ``sphinx.ext.todo.TodoDomain`` + + * - ``sphinx.builders.latex.LaTeXBuilder.apply_transforms()`` + - 2.1 + - 4.0 + - N/A + + * - ``sphinx.builders._epub_base.EpubBuilder.esc()`` + - 2.1 + - 4.0 + - ``html.escape()`` + + * - ``sphinx.directives.Acks`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.Acks`` + + * - ``sphinx.directives.Author`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.Author`` + + * - ``sphinx.directives.Centered`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.Centered`` + + * - ``sphinx.directives.Class`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.Class`` + + * - ``sphinx.directives.CodeBlock`` + - 2.1 + - 4.0 + - ``sphinx.directives.code.CodeBlock`` + + * - ``sphinx.directives.Figure`` + - 2.1 + - 4.0 + - ``sphinx.directives.patches.Figure`` + + * - ``sphinx.directives.HList`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.HList`` + + * - ``sphinx.directives.Highlight`` + - 2.1 + - 4.0 + - ``sphinx.directives.code.Highlight`` + + * - ``sphinx.directives.Include`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.Include`` + + * - ``sphinx.directives.Index`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.Index`` + + * - ``sphinx.directives.LiteralInclude`` + - 2.1 + - 4.0 + - ``sphinx.directives.code.LiteralInclude`` + + * - ``sphinx.directives.Meta`` + - 2.1 + - 4.0 + - ``sphinx.directives.patches.Meta`` + + * - ``sphinx.directives.Only`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.Only`` + + * - ``sphinx.directives.SeeAlso`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.SeeAlso`` + + * - ``sphinx.directives.TabularColumns`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.TabularColumns`` + + * - ``sphinx.directives.TocTree`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.TocTree`` + + * - ``sphinx.directives.VersionChange`` + - 2.1 + - 4.0 + - ``sphinx.directives.other.VersionChange`` + + * - ``sphinx.domains.python.PyClassmember`` + - 2.1 + - 4.0 + - ``sphinx.domains.python.PyAttribute``, + ``sphinx.domains.python.PyMethod``, + ``sphinx.domains.python.PyClassMethod``, + ``sphinx.domains.python.PyObject`` and + ``sphinx.domains.python.PyStaticMethod`` + + * - ``sphinx.domains.python.PyModulelevel`` + - 2.1 + - 4.0 + - ``sphinx.domains.python.PyFunction``, + ``sphinx.domains.python.PyObject`` and + ``sphinx.domains.python.PyVariable`` + + * - ``sphinx.domains.std.StandardDomain._resolve_citation_xref()`` + - 2.1 + - 4.0 + - ``sphinx.domains.citation.CitationDomain.resolve_xref()`` + + * - ``sphinx.domains.std.StandardDomain.note_citations()`` + - 2.1 + - 4.0 + - ``sphinx.domains.citation.CitationDomain.note_citation()`` + + * - ``sphinx.domains.std.StandardDomain.note_citation_refs()`` + - 2.1 + - 4.0 + - ``sphinx.domains.citation.CitationDomain.note_citation_reference()`` + + * - ``sphinx.domains.std.StandardDomain.note_labels()`` + - 2.1 + - 4.0 + - ``sphinx.domains.std.StandardDomain.process_doc()`` + + * - ``sphinx.domains.js.JSObject.display_prefix`` + - + - 4.3 + - ``sphinx.domains.js.JSObject.get_display_prefix()`` + + * - ``sphinx.environment.NoUri`` + - 2.1 + - 3.0 + - ``sphinx.errors.NoUri`` + + * - ``sphinx.ext.apidoc.format_directive()`` + - 2.1 + - 4.0 + - N/A + + * - ``sphinx.ext.apidoc.format_heading()`` + - 2.1 + - 4.0 + - N/A + + * - ``sphinx.ext.apidoc.makename()`` + - 2.1 + - 4.0 + - ``sphinx.ext.apidoc.module_join()`` + + * - ``sphinx.ext.autodoc.importer.MockFinder`` + - 2.1 + - 4.0 + - ``sphinx.ext.autodoc.mock.MockFinder`` + + * - ``sphinx.ext.autodoc.importer.MockLoader`` + - 2.1 + - 4.0 + - ``sphinx.ext.autodoc.mock.MockLoader`` + + * - ``sphinx.ext.autodoc.importer.mock()`` + - 2.1 + - 4.0 + - ``sphinx.ext.autodoc.mock.mock()`` + + * - ``sphinx.ext.autosummary.autolink_role()`` + - 2.1 + - 4.0 + - ``sphinx.ext.autosummary.AutoLink`` + + * - ``sphinx.ext.imgmath.DOC_BODY`` + - 2.1 + - 4.0 + - N/A + + * - ``sphinx.ext.imgmath.DOC_BODY_PREVIEW`` + - 2.1 + - 4.0 + - N/A + + * - ``sphinx.ext.imgmath.DOC_HEAD`` + - 2.1 + - 4.0 + - N/A + + * - ``sphinx.transforms.CitationReferences`` + - 2.1 + - 4.0 + - ``sphinx.domains.citation.CitationReferenceTransform`` + + * - ``sphinx.transforms.SmartQuotesSkipper`` + - 2.1 + - 4.0 + - ``sphinx.domains.citation.CitationDefinitionTransform`` + + * - ``sphinx.util.docfields.DocFieldTransformer.preprocess_fieldtypes()`` + - 2.1 + - 4.0 + - ``sphinx.directives.ObjectDescription.get_field_type_map()`` + + * - ``sphinx.util.node.find_source_node()`` + - 2.1 + - 4.0 + - ``sphinx.util.node.get_node_source()`` + + * - ``sphinx.util.i18n.find_catalog()`` + - 2.1 + - 4.0 + - ``sphinx.util.i18n.docname_to_domain()`` + + * - ``sphinx.util.i18n.find_catalog_files()`` + - 2.1 + - 4.0 + - ``sphinx.util.i18n.CatalogRepository`` + + * - ``sphinx.util.i18n.find_catalog_source_files()`` + - 2.1 + - 4.0 + - ``sphinx.util.i18n.CatalogRepository`` + + * - ``encoding`` argument of ``autodoc.Documenter.get_doc()``, + ``autodoc.DocstringSignatureMixin.get_doc()``, + ``autodoc.DocstringSignatureMixin._find_signature()``, and + ``autodoc.ClassDocumenter.get_doc()`` + - 2.0 + - 4.0 + - N/A + + * - arguments of ``EpubBuilder.build_mimetype()``, + ``EpubBuilder.build_container()``, ``EpubBuilder.build_content()``, + ``EpubBuilder.build_toc()`` and ``EpubBuilder.build_epub()`` + - 2.0 + - 4.0 + - N/A + + * - arguments of ``Epub3Builder.build_navigation_doc()`` + - 2.0 + - 4.0 + - N/A + + * - ``nodetype`` argument of + ``sphinx.search.WordCollector.is_meta_keywords()`` + - 2.0 + - 4.0 + - N/A + + * - ``suffix`` argument of ``BuildEnvironment.doc2path()`` + - 2.0 + - 4.0 + - N/A + + * - string style ``base`` argument of ``BuildEnvironment.doc2path()`` + - 2.0 + - 4.0 + - ``os.path.join()`` + + * - ``sphinx.addnodes.abbreviation`` + - 2.0 + - 4.0 + - ``docutils.nodes.abbreviation`` + + * - ``sphinx.builders.applehelp`` + - 2.0 + - 4.0 + - ``sphinxcontrib.applehelp`` + + * - ``sphinx.builders.devhelp`` + - 2.0 + - 4.0 + - ``sphinxcontrib.devhelp`` + + * - ``sphinx.builders.epub3.Epub3Builder.validate_config_value()`` + - 2.0 + - 4.0 + - ``sphinx.builders.epub3.validate_config_values()`` + + * - ``sphinx.builders.html.JSONHTMLBuilder`` + - 2.0 + - 4.0 + - ``sphinx.builders.serializinghtml.JSONHTMLBuilder`` + + * - ``sphinx.builders.html.PickleHTMLBuilder`` + - 2.0 + - 4.0 + - ``sphinx.builders.serializinghtml.PickleHTMLBuilder`` + + * - ``sphinx.builders.html.SerializingHTMLBuilder`` + - 2.0 + - 4.0 + - ``sphinx.builders.serializinghtml.SerializingHTMLBuilder`` + + * - ``sphinx.builders.html.SingleFileHTMLBuilder`` + - 2.0 + - 4.0 + - ``sphinx.builders.singlehtml.SingleFileHTMLBuilder`` + + * - ``sphinx.builders.html.WebHTMLBuilder`` + - 2.0 + - 4.0 + - ``sphinx.builders.serializinghtml.PickleHTMLBuilder`` + + * - ``sphinx.builders.htmlhelp`` + - 2.0 + - 4.0 + - ``sphinxcontrib.htmlhelp`` + + * - ``sphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()`` + - 2.0 + - 4.0 + - ``open()`` + + * - ``sphinx.builders.qthelp`` + - 2.0 + - 4.0 + - ``sphinxcontrib.qthelp`` + + * - ``sphinx.cmd.quickstart.term_decode()`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.cmd.quickstart.TERM_ENCODING`` + - 2.0 + - 4.0 + - ``sys.stdin.encoding`` + + * - ``sphinx.config.check_unicode()`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.config.string_classes`` + - 2.0 + - 4.0 + - ``[str]`` + + * - ``sphinx.domains.cpp.DefinitionError.description`` + - 2.0 + - 4.0 + - ``str(exc)`` + + * - ``sphinx.domains.cpp.NoOldIdError.description`` + - 2.0 + - 4.0 + - ``str(exc)`` + + * - ``sphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded`` + - 2.0 + - 4.0 + - ``str(exc)`` + + * - ``sphinx.ext.autosummary.Autosummary.warn()`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.ext.autosummary.Autosummary.genopt`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.ext.autosummary.Autosummary.warnings`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.ext.autosummary.Autosummary.result`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.ext.doctest.doctest_encode()`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.ext.jsmath`` + - 2.0 + - 4.0 + - ``sphinxcontrib.jsmath`` + + * - ``sphinx.roles.abbr_role()`` + - 2.0 + - 4.0 + - ``sphinx.roles.Abbreviation`` + + * - ``sphinx.roles.emph_literal_role()`` + - 2.0 + - 4.0 + - ``sphinx.roles.EmphasizedLiteral`` + + * - ``sphinx.roles.menusel_role()`` + - 2.0 + - 4.0 + - ``sphinx.roles.GUILabel`` or ``sphinx.roles.MenuSelection`` + + * - ``sphinx.roles.index_role()`` + - 2.0 + - 4.0 + - ``sphinx.roles.Index`` + + * - ``sphinx.roles.indexmarkup_role()`` + - 2.0 + - 4.0 + - ``sphinx.roles.PEP`` or ``sphinx.roles.RFC`` + + * - ``sphinx.testing.util.remove_unicode_literal()`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.util.attrdict`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.util.force_decode()`` + - 2.0 + - 5.0 + - N/A + + * - ``sphinx.util.get_matching_docs()`` + - 2.0 + - 4.0 + - ``sphinx.util.get_matching_files()`` + + * - ``sphinx.util.inspect.Parameter`` + - 2.0 + - 3.0 + - N/A + + * - ``sphinx.util.jsonimpl`` + - 2.0 + - 4.0 + - ``sphinxcontrib.serializinghtml.jsonimpl`` + + * - ``sphinx.util.osutil.EEXIST`` + - 2.0 + - 4.0 + - ``errno.EEXIST`` or ``FileExistsError`` + + * - ``sphinx.util.osutil.EINVAL`` + - 2.0 + - 4.0 + - ``errno.EINVAL`` + + * - ``sphinx.util.osutil.ENOENT`` + - 2.0 + - 4.0 + - ``errno.ENOENT`` or ``FileNotFoundError`` + + * - ``sphinx.util.osutil.EPIPE`` + - 2.0 + - 4.0 + - ``errno.ENOENT`` or ``BrokenPipeError`` + + * - ``sphinx.util.osutil.walk()`` + - 2.0 + - 4.0 + - ``os.walk()`` + + * - ``sphinx.util.pycompat.NoneType`` + - 2.0 + - 4.0 + - ``sphinx.util.typing.NoneType`` + + * - ``sphinx.util.pycompat.TextIOWrapper`` + - 2.0 + - 4.0 + - ``io.TextIOWrapper`` + + * - ``sphinx.util.pycompat.UnicodeMixin`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.util.pycompat.htmlescape()`` + - 2.0 + - 4.0 + - ``html.escape()`` + + * - ``sphinx.util.pycompat.indent()`` + - 2.0 + - 4.0 + - ``textwrap.indent()`` + + * - ``sphinx.util.pycompat.sys_encoding`` + - 2.0 + - 4.0 + - ``sys.getdefaultencoding()`` + + * - ``sphinx.util.pycompat.terminal_safe()`` + - 2.0 + - 4.0 + - ``sphinx.util.console.terminal_safe()`` + + * - ``sphinx.util.pycompat.u`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.util.PeekableIterator`` + - 2.0 + - 4.0 + - N/A + + * - Omitting the ``filename`` argument in an overriddent + ``IndexBuilder.feed()`` method. + - 2.0 + - 4.0 + - ``IndexBuilder.feed(docname, filename, title, doctree)`` + + * - ``sphinx.writers.latex.ExtBabel`` + - 2.0 + - 4.0 + - ``sphinx.builders.latex.util.ExtBabel`` + + * - ``sphinx.writers.latex.LaTeXTranslator.babel_defmacro()`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.application.Sphinx._setting_up_extension`` + - 2.0 + - 3.0 + - N/A + + * - The ``importer`` argument of ``sphinx.ext.autodoc.importer._MockModule`` + - 2.0 + - 3.0 + - N/A + + * - ``sphinx.ext.autodoc.importer._MockImporter`` + - 2.0 + - 3.0 + - N/A + + * - ``sphinx.io.SphinxBaseFileInput`` + - 2.0 + - 3.0 + - N/A + + * - ``sphinx.io.SphinxFileInput.supported`` + - 2.0 + - 3.0 + - N/A + + * - ``sphinx.io.SphinxRSTFileInput`` + - 2.0 + - 3.0 + - N/A + + * - ``sphinx.registry.SphinxComponentRegistry.add_source_input()`` + - 2.0 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator._make_visit_admonition()`` + - 2.0 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.collect_footnotes()`` + - 2.0 + - 4.0 + - N/A + + * - ``sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()`` + - 2.0 + - 3.0 + - N/A + + * - ``sphinx.writers.text.TextTranslator._make_depart_admonition()`` + - 2.0 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.generate_numfig_format()`` + - 2.0 + - 4.0 + - N/A + + * - :rst:dir:`!highlightlang` + - 1.8 + - 4.0 + - :rst:dir:`highlight` + + * - :meth:`!add_stylesheet` + - 1.8 + - 6.0 + - :meth:`~sphinx.application.Sphinx.add_css_file()` + + * - :meth:`!add_javascript()` + - 1.8 + - 4.0 + - :meth:`~sphinx.application.Sphinx.add_js_file()` + + * - :confval:`autodoc_default_flags` + - 1.8 + - 4.0 + - :confval:`autodoc_default_options` + + * - ``content`` arguments of ``sphinx.util.image.guess_mimetype()`` + - 1.8 + - 3.0 + - N/A + + * - ``gettext_compact`` arguments of + ``sphinx.util.i18n.find_catalog_source_files()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.io.SphinxI18nReader.set_lineno_for_reporter()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.io.SphinxI18nReader.line`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.directives.other.VersionChanges`` + - 1.8 + - 3.0 + - ``sphinx.domains.changeset.VersionChanges`` + + * - ``sphinx.highlighting.PygmentsBridge.unhighlight()`` + - 1.8 + - 3.0 + - N/A + + * - ``trim_doctest_flags`` arguments of + ``sphinx.highlighting.PygmentsBridge`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.ext.mathbase`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.ext.mathbase.MathDomain`` + - 1.8 + - 3.0 + - ``sphinx.domains.math.MathDomain`` + + * - ``sphinx.ext.mathbase.MathDirective`` + - 1.8 + - 3.0 + - ``sphinx.directives.patches.MathDirective`` + + * - ``sphinx.ext.mathbase.math_role()`` + - 1.8 + - 3.0 + - ``docutils.parsers.rst.roles.math_role()`` + + * - ``sphinx.ext.mathbase.setup_math()`` + - 1.8 + - 3.0 + - :meth:`~sphinx.application.Sphinx.add_html_math_renderer()` + + * - ``sphinx.ext.mathbase.is_in_section_title()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.ext.mathbase.get_node_equation_number()`` + - 1.8 + - 3.0 + - ``sphinx.util.math.get_node_equation_number()`` + + * - ``sphinx.ext.mathbase.wrap_displaymath()`` + - 1.8 + - 3.0 + - ``sphinx.util.math.wrap_displaymath()`` + + * - ``sphinx.ext.mathbase.math`` (node) + - 1.8 + - 3.0 + - ``docutils.nodes.math`` + + * - ``sphinx.ext.mathbase.displaymath`` (node) + - 1.8 + - 3.0 + - ``docutils.nodes.math_block`` + + * - ``sphinx.ext.mathbase.eqref`` (node) + - 1.8 + - 3.0 + - ``sphinx.builders.latex.nodes.math_reference`` + + * - :confval:`!viewcode_import` (config value) + - 1.8 + - 3.0 + - :confval:`viewcode_follow_imported_members` + + * - ``sphinx.writers.latex.Table.caption_footnotetexts`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.Table.header_footnotetexts`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.footnotestack`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.in_container_literal_block`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.next_section_ids`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.restrict_footnote()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.bibitems`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.hlsettingstack`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.ExtBabel.get_shorthandoff()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.html.HTMLTranslator.highlightlang()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.html.HTMLTranslator.highlightlang_base()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.html.HTMLTranslator.highlightlangopts()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.html.HTMLTranslator.highlightlinenothreshold()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.html5.HTMLTranslator.highlightlang()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.html5.HTMLTranslator.highlightlang_base()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.html5.HTMLTranslator.highlightlangopts()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold()`` + - 1.8 + - 3.0 + - N/A + + * - ``sphinx.writers.latex.LaTeXTranslator.check_latex_elements()`` + - 1.8 + - 3.0 + - Nothing + + * - ``sphinx.application.CONFIG_FILENAME`` + - 1.8 + - 3.0 + - ``sphinx.config.CONFIG_FILENAME`` + + * - ``Config.check_unicode()`` + - 1.8 + - 3.0 + - ``sphinx.config.check_unicode()`` + + * - ``Config.check_types()`` + - 1.8 + - 3.0 + - ``sphinx.config.check_confval_types()`` + + * - ``dirname``, ``filename`` and ``tags`` arguments of + ``Config.__init__()`` + - 1.8 + - 3.0 + - ``Config.read()`` + + * - The value of :confval:`html_search_options` + - 1.8 + - 3.0 + - see :confval:`html_search_options` + + * - ``sphinx.versioning.prepare()`` + - 1.8 + - 3.0 + - ``sphinx.versioning.UIDTransform`` + + * - ``Sphinx.override_domain()`` + - 1.8 + - 3.0 + - :meth:`~sphinx.application.Sphinx.add_domain()` + + * - ``Sphinx.import_object()`` + - 1.8 + - 3.0 + - ``sphinx.util.import_object()`` + + * - ``suffix`` argument of + :meth:`~sphinx.application.Sphinx.add_source_parser()` + - 1.8 + - 3.0 + - :meth:`~sphinx.application.Sphinx.add_source_suffix()` + + + * - ``BuildEnvironment.load()`` + - 1.8 + - 3.0 + - ``pickle.load()`` + + * - ``BuildEnvironment.loads()`` + - 1.8 + - 3.0 + - ``pickle.loads()`` + + * - ``BuildEnvironment.frompickle()`` + - 1.8 + - 3.0 + - ``pickle.load()`` + + * - ``BuildEnvironment.dump()`` + - 1.8 + - 3.0 + - ``pickle.dump()`` + + * - ``BuildEnvironment.dumps()`` + - 1.8 + - 3.0 + - ``pickle.dumps()`` + + * - ``BuildEnvironment.topickle()`` + - 1.8 + - 3.0 + - ``pickle.dump()`` + + * - ``BuildEnvironment._nitpick_ignore`` + - 1.8 + - 3.0 + - :confval:`nitpick_ignore` + + * - ``BuildEnvironment.versionchanges`` + - 1.8 + - 3.0 + - N/A + + * - ``BuildEnvironment.update()`` + - 1.8 + - 3.0 + - ``Builder.read()`` + + * - ``BuildEnvironment.read_doc()`` + - 1.8 + - 3.0 + - ``Builder.read_doc()`` + + * - ``BuildEnvironment._read_serial()`` + - 1.8 + - 3.0 + - ``Builder.read()`` + + * - ``BuildEnvironment._read_parallel()`` + - 1.8 + - 3.0 + - ``Builder.read()`` + + * - ``BuildEnvironment.write_doctree()`` + - 1.8 + - 3.0 + - ``Builder.write_doctree()`` + + * - ``BuildEnvironment.note_versionchange()`` + - 1.8 + - 3.0 + - ``ChangesDomain.note_changeset()`` + + * - ``warn()`` (template helper function) + - 1.8 + - 3.0 + - ``warning()`` + + * - :confval:`source_parsers` + - 1.8 + - 3.0 + - :meth:`~sphinx.application.Sphinx.add_source_parser()` + + * - ``sphinx.util.docutils.directive_helper()`` + - 1.8 + - 3.0 + - ``Directive`` class of docutils + + * - ``sphinx.cmdline`` + - 1.8 + - 3.0 + - ``sphinx.cmd.build`` + + * - ``sphinx.make_mode`` + - 1.8 + - 3.0 + - ``sphinx.cmd.make_mode`` + + * - ``sphinx.locale.l_()`` + - 1.8 + - 3.0 + - :func:`sphinx.locale._()` + + * - ``sphinx.locale.lazy_gettext()`` + - 1.8 + - 3.0 + - :func:`sphinx.locale._()` + + * - ``sphinx.locale.mygettext()`` + - 1.8 + - 3.0 + - :func:`sphinx.locale._()` + + * - ``sphinx.util.copy_static_entry()`` + - 1.5 + - 3.0 + - ``sphinx.util.fileutil.copy_asset()`` + + * - ``sphinx.build_main()`` + - 1.7 + - 2.0 + - ``sphinx.cmd.build.build_main()`` + + * - ``sphinx.ext.intersphinx.debug()`` + - 1.7 + - 2.0 + - ``sphinx.ext.intersphinx.inspect_main()`` + + * - ``sphinx.ext.autodoc.format_annotation()`` + - 1.7 + - 2.0 + - ``sphinx.util.inspect.Signature`` + + * - ``sphinx.ext.autodoc.formatargspec()`` + - 1.7 + - 2.0 + - ``sphinx.util.inspect.Signature`` + + * - ``sphinx.ext.autodoc.AutodocReporter`` + - 1.7 + - 2.0 + - ``sphinx.util.docutils.switch_source_input()`` + + * - ``sphinx.ext.autodoc.add_documenter()`` + - 1.7 + - 2.0 + - :meth:`~sphinx.application.Sphinx.add_autodocumenter()` + + * - ``sphinx.ext.autodoc.AutoDirective._register`` + - 1.7 + - 2.0 + - :meth:`~sphinx.application.Sphinx.add_autodocumenter()` + + * - ``AutoDirective._special_attrgetters`` + - 1.7 + - 2.0 + - :meth:`~sphinx.application.Sphinx.add_autodoc_attrgetter()` + + * - ``Sphinx.warn()``, ``Sphinx.info()`` + - 1.6 + - 2.0 + - :ref:`logging-api` + + * - ``BuildEnvironment.set_warnfunc()`` + - 1.6 + - 2.0 + - :ref:`logging-api` + + * - ``BuildEnvironment.note_toctree()`` + - 1.6 + - 2.0 + - ``Toctree.note()`` (in ``sphinx.environment.adapters.toctree``) + + * - ``BuildEnvironment.get_toc_for()`` + - 1.6 + - 2.0 + - ``Toctree.get_toc_for()`` (in ``sphinx.environment.adapters.toctree``) + + * - ``BuildEnvironment.get_toctree_for()`` + - 1.6 + - 2.0 + - ``Toctree.get_toctree_for()`` (in ``sphinx.environment.adapters.toctree``) + + * - ``BuildEnvironment.create_index()`` + - 1.6 + - 2.0 + - ``IndexEntries.create_index()`` (in ``sphinx.environment.adapters.indexentries``) + + * - ``sphinx.websupport`` + - 1.6 + - 2.0 + - `sphinxcontrib-websupport`_ + + .. _sphinxcontrib-websupport: https://pypi.org/project/sphinxcontrib-websupport/ + + * - ``StandaloneHTMLBuilder.css_files`` + - 1.6 + - 2.0 + - :meth:`!add_stylesheet` + + * - ``document.settings.gettext_compact`` + - 1.8 + - 1.8 + - :confval:`gettext_compact` + + * - ``Sphinx.status_iterator()`` + - 1.6 + - 1.7 + - ``sphinx.util.status_iterator()`` + + * - ``Sphinx.old_status_iterator()`` + - 1.6 + - 1.7 + - ``sphinx.util.old_status_iterator()`` + + * - ``Sphinx._directive_helper()`` + - 1.6 + - 1.7 + - ``sphinx.util.docutils.directive_helper()`` + + * - ``sphinx.util.compat.Directive`` + - 1.6 + - 1.7 + - ``docutils.parsers.rst.Directive`` + + * - ``sphinx.util.compat.docutils_version`` + - 1.6 + - 1.7 + - ``sphinx.util.docutils.__version_info__`` + +.. note:: On deprecating on public APIs (internal functions and classes), + we also follow the policy as much as possible. diff --git a/doc/extdev/domainapi.rst b/doc/extdev/domainapi.rst new file mode 100644 index 0000000..d70b5db --- /dev/null +++ b/doc/extdev/domainapi.rst @@ -0,0 +1,32 @@ +.. _domain-api: + +Domain API +========== + +.. module:: sphinx.domains + +.. autoclass:: Domain + :members: + +.. autoclass:: ObjType + +.. autoclass:: Index + :members: + +.. module:: sphinx.directives + +.. autoclass:: ObjectDescription + :members: + :private-members: _toc_entry_name, _object_hierarchy_parts + +Python Domain +------------- + +.. module:: sphinx.domains.python + +.. autoclass:: PythonDomain + + .. autoattribute:: objects + .. autoattribute:: modules + .. automethod:: note_object + .. automethod:: note_module diff --git a/doc/extdev/envapi.rst b/doc/extdev/envapi.rst new file mode 100644 index 0000000..d7ec239 --- /dev/null +++ b/doc/extdev/envapi.rst @@ -0,0 +1,58 @@ +Build environment API +===================== + +.. module:: sphinx.environment + +.. class:: BuildEnvironment + + **Attributes** + + .. attribute:: app + + Reference to the :class:`.Sphinx` (application) object. + + .. attribute:: config + + Reference to the :class:`.Config` object. + + .. attribute:: project + + Target project. See :class:`.Project`. + + .. attribute:: srcdir + + Source directory. + + .. attribute:: doctreedir + + Directory for storing pickled doctrees. + + .. attribute:: events + + An :class:`.EventManager` object. + + .. attribute:: found_docs + + A set of all existing docnames. + + .. attribute:: metadata + + Dictionary mapping docnames to "metadata" (see :ref:`metadata`). + + .. attribute:: titles + + Dictionary mapping docnames to the docutils node for their main title. + + .. autoattribute:: docname + + **Utility methods** + + .. automethod:: doc2path + + .. automethod:: relfn2path + + .. automethod:: note_dependency + + .. automethod:: new_serialno + + .. automethod:: note_reread diff --git a/doc/extdev/i18n.rst b/doc/extdev/i18n.rst new file mode 100644 index 0000000..6b32b8b --- /dev/null +++ b/doc/extdev/i18n.rst @@ -0,0 +1,97 @@ +.. _i18n-api: + +i18n API +======== + +.. currentmodule:: sphinx.locale + +.. autofunction:: init + +.. autofunction:: init_console + +.. autofunction:: get_translation + +.. autofunction:: _ + +.. autofunction:: __ + + +.. _ext-i18n: + +Extension internationalization (`i18n`) and localization (`l10n`) using i18n API +-------------------------------------------------------------------------------- + +.. versionadded:: 1.8 + +An extension may naturally come with message translations. This is briefly +summarized in :func:`sphinx.locale.get_translation` help. + +In practice, you have to: + +#. Choose a name for your message catalog, which must be unique. Usually + the name of your extension is used for the name of message catalog. + +#. Mark in your extension sources all messages as translatable, via + :func:`sphinx.locale.get_translation` function, usually renamed ``_()``, + e.g.: + + .. code-block:: python + :caption: src/__init__.py + + from sphinx.locale import get_translation + + MESSAGE_CATALOG_NAME = 'myextension' + _ = get_translation(MESSAGE_CATALOG_NAME) + + translated_text = _('Hello Sphinx!') + +#. Set up your extension to be aware of its dedicated translations: + + .. code-block:: python + :caption: src/__init__.py + + def setup(app): + package_dir = path.abspath(path.dirname(__file__)) + locale_dir = os.path.join(package_dir, 'locales') + app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir) + +#. Generate message catalog template ``*.pot`` file, usually in ``locale/`` + source directory, for example via `Babel`_: + + .. code-block:: console + + $ pybabel extract --output=src/locale/myextension.pot src/ + +#. Create message catalogs (``*.po``) for each language which your extension + will provide localization, for example via `Babel`_: + + .. code-block:: console + + $ pybabel init --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale --locale=fr_FR + +#. Translate message catalogs for each language manually + +#. Compile message catalogs into ``*.mo`` files, for example via `Babel`_: + + .. code-block:: console + + $ pybabel compile --directory=src/locale --domain=myextension + +#. Ensure that message catalog files are distributed when your package will + be installed, by adding equivalent line in your extension ``MANIFEST.in``: + + .. code-block:: ini + :caption: MANIFEST.in + + recursive-include src *.pot *.po *.mo + + +When the messages on your extension has been changed, you need to also update +message catalog template and message catalogs, for example via `Babel`_: + +.. code-block:: console + + $ pybabel extract --output=src/locale/myextension.pot src/ + $ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale + +.. _Babel: https://babel.pocoo.org/ diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst new file mode 100644 index 0000000..8332315 --- /dev/null +++ b/doc/extdev/index.rst @@ -0,0 +1,218 @@ +.. _dev-extensions: + +Sphinx Extensions API +===================== + +Since many projects will need special features in their documentation, Sphinx +is designed to be extensible on several levels. + +Here are a few things you can do in an extension: + +* Add new :term:`builder`\s to support new output formats or actions on the + parsed documents. +* Register custom reStructuredText roles and directives, extending the markup + using the :doc:`markupapi`. +* Add custom code to so-called "hook points" at strategic places throughout the + build process, allowing you to register a hook and run specialized code. + For example, see the :ref:`events`. + +An extension is simply a Python module with a ``setup()`` function. A user +activates the extension by placing the extension's module name +(or a sub-module) in their :confval:`extensions` configuration value. + +When :program:`sphinx-build` is executed, Sphinx will attempt to import each +module that is listed, and execute ``yourmodule.setup(app)``. This +function is used to prepare the extension (e.g., by executing Python code), +linking resources that Sphinx uses in the build process (like CSS or HTML +files), and notifying Sphinx of everything the extension offers (such +as directive or role definitions). The ``app`` argument is an instance of +:class:`.Sphinx` and gives you control over most aspects of the Sphinx build. + +.. note:: + + The configuration file itself can be treated as an extension if it + contains a ``setup()`` function. All other extensions to load must be + listed in the :confval:`extensions` configuration value. + +The rest of this page describes some high-level aspects of developing +extensions and various parts of Sphinx's behavior that you can control. +For some examples of how extensions can be built and used to control different +parts of Sphinx, see the :ref:`extension-tutorials-index`. + +.. _important-objects: + +Important objects +----------------- + +There are several key objects whose API you will use while writing an +extension. These are: + +**Application** + The application object (usually called ``app``) is an instance of + :class:`.Sphinx`. It controls most high-level functionality, such as the + setup of extensions, event dispatching and producing output (logging). + + If you have the environment object, the application is available as + ``env.app``. + +**Environment** + The build environment object (usually called ``env``) is an instance of + :class:`.BuildEnvironment`. It is responsible for parsing the source + documents, stores all metadata about the document collection and is + serialized to disk after each build. + + Its API provides methods to do with access to metadata, resolving references, + etc. It can also be used by extensions to cache information that should + persist for incremental rebuilds. + + If you have the application or builder object, the environment is available + as ``app.env`` or ``builder.env``. + +**Builder** + The builder object (usually called ``builder``) is an instance of a specific + subclass of :class:`.Builder`. Each builder class knows how to convert the + parsed documents into an output format, or otherwise process them (e.g. check + external links). + + If you have the application object, the builder is available as + ``app.builder``. + +**Config** + The config object (usually called ``config``) provides the values of + configuration values set in :file:`conf.py` as attributes. It is an instance + of :class:`.Config`. + + 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`. + +.. _build-phases: + +Build Phases +------------ + +One thing that is vital in order to understand extension mechanisms is the way +in which a Sphinx project is built: this works in several phases. + +**Phase 0: Initialization** + +In this phase, almost nothing of interest to us happens. The source +directory is searched for source files, and extensions are initialized. +Should a stored build environment exist, it is loaded, otherwise a new one is +created. + +**Phase 1: Reading** + +In Phase 1, all source files (and on subsequent builds, those that are new or +changed) are read and parsed. This is the phase where directives and roles +are encountered by docutils, and the corresponding code is executed. The +output of this phase is a *doctree* for each source file; that is a tree of +docutils nodes. For document elements that aren't fully known until all +existing files are read, temporary nodes are created. + +There are nodes provided by docutils, which are documented `in the docutils +documentation <https://docutils.sourceforge.io/docs/ref/doctree.html>`__. +Additional nodes are provided by Sphinx and :ref:`documented here <nodes>`. + +During reading, the build environment is updated with all meta- and cross +reference data of the read documents, such as labels, the names of headings, +described Python objects and index entries. This will later be used to +replace the temporary nodes. + +The parsed doctrees are stored on the disk, because it is not possible to +hold all of them in memory. + +**Phase 2: Consistency checks** + +Some checking is done to ensure no surprises in the built documents. + +**Phase 3: Resolving** + +Now that the metadata and cross-reference data of all existing documents is +known, all temporary nodes are replaced by nodes that can be converted into +output using components called transforms. For example, links are created +for object references that exist, and simple literal nodes are created for +those that don't. + +**Phase 4: Writing** + +This phase converts the resolved doctrees to the desired output format, such +as HTML or LaTeX. This happens via a so-called docutils writer that visits +the individual nodes of each doctree and produces some output in the process. + +.. note:: + + Some builders deviate from this general build plan, for example, the builder + 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`. + +.. _ext-metadata: + +Extension metadata +------------------ + +.. versionadded:: 1.3 + +The ``setup()`` function can return a dictionary. This is treated by Sphinx +as metadata of the extension. Metadata keys currently recognized are: + +* ``'version'``: a string that identifies the extension version. It is used for + extension version requirement checking (see :confval:`needs_extensions`) and + informational purposes. If not given, ``"unknown version"`` is substituted. +* ``'env_version'``: an integer that identifies the version of env data + structure if the extension stores any data to environment. It is used to + detect the data structure has been changed from last build. The extensions + have to increment the version when data structure has changed. If not given, + Sphinx considers the extension does not stores any data to environment. +* ``'parallel_read_safe'``: a boolean that specifies if parallel reading of + source files can be used when the extension is loaded. It defaults to + ``False``, i.e. you have to explicitly specify your extension to be + parallel-read-safe after checking that it is. + + .. note:: The *parallel-read-safe* extension must satisfy the following + conditions: + + * The core logic of the extension is parallelly executable during + the reading phase. + * It has event handlers for :event:`env-merge-info` and + :event:`env-purge-doc` events if it stores data to the build + environment object (env) during the reading phase. + +* ``'parallel_write_safe'``: a boolean that specifies if parallel writing of + output files can be used when the extension is loaded. Since extensions + usually don't negatively influence the process, this defaults to ``True``. + + .. note:: The *parallel-write-safe* extension must satisfy the following + conditions: + + * The core logic of the extension is parallelly executable during + the writing phase. + + +APIs used for writing extensions +-------------------------------- + +These sections provide a more complete description of the tools at your +disposal when developing Sphinx extensions. Some are core to Sphinx +(such as the :doc:`appapi`) while others trigger specific behavior +(such as the :doc:`i18n`) + +.. toctree:: + :maxdepth: 2 + + appapi + projectapi + envapi + builderapi + collectorapi + markupapi + domainapi + parserapi + nodes + logging + i18n + utils + deprecated diff --git a/doc/extdev/logging.rst b/doc/extdev/logging.rst new file mode 100644 index 0000000..e6c4dc6 --- /dev/null +++ b/doc/extdev/logging.rst @@ -0,0 +1,66 @@ +.. _logging-api: + +Logging API +=========== + +.. currentmodule:: sphinx.util.logging + +.. autofunction:: getLogger(name) + +.. autoclass:: SphinxLoggerAdapter(logging.LoggerAdapter) + + .. method:: SphinxLoggerAdapter.error(msg, *args, **kwargs) + .. method:: SphinxLoggerAdapter.critical(msg, *args, **kwargs) + .. method:: SphinxLoggerAdapter.warning(msg, *args, **kwargs) + + Logs a message on this logger with the specified level. + Basically, the arguments are as with python's logging module. + + In addition, Sphinx logger supports following keyword arguments: + + **type**, ***subtype*** + Categories of warning logs. It is used to suppress + warnings by :confval:`suppress_warnings` setting. + + **location** + Where the warning happened. It is used to include + the path and line number in each log. It allows docname, + tuple of docname and line number and nodes:: + + logger = sphinx.util.logging.getLogger(__name__) + logger.warning('Warning happened!', location='index') + logger.warning('Warning happened!', location=('chapter1/index', 10)) + logger.warning('Warning happened!', location=some_node) + + **color** + The color of logs. By default, error level logs are colored as + ``"darkred"``, critical level ones is not colored, and warning level + ones are colored as ``"red"``. + + .. method:: SphinxLoggerAdapter.log(level, msg, *args, **kwargs) + .. method:: SphinxLoggerAdapter.info(msg, *args, **kwargs) + .. method:: SphinxLoggerAdapter.verbose(msg, *args, **kwargs) + .. method:: SphinxLoggerAdapter.debug(msg, *args, **kwargs) + + Logs a message to this logger with the specified level. + Basically, the arguments are as with python's logging module. + + In addition, Sphinx logger supports following keyword arguments: + + **nonl** + If true, the logger does not fold lines at the end of the log message. + The default is ``False``. + + **location** + Where the message emitted. For more detail, see + :meth:`SphinxLoggerAdapter.warning`. + + **color** + The color of logs. By default, info and verbose level logs are not + colored, and debug level ones are colored as ``"darkgray"``. + +.. autofunction:: pending_logging() + +.. autofunction:: pending_warnings() + +.. autofunction:: prefixed_warnings() diff --git a/doc/extdev/markupapi.rst b/doc/extdev/markupapi.rst new file mode 100644 index 0000000..072760c --- /dev/null +++ b/doc/extdev/markupapi.rst @@ -0,0 +1,152 @@ +Docutils markup API +=================== + +This section describes the API for adding ReST markup elements (roles and +directives). + +Roles +----- + + +Directives +---------- + +Directives are handled by classes derived from +``docutils.parsers.rst.Directive``. They have to be registered by an extension +using :meth:`.Sphinx.add_directive` or :meth:`.Sphinx.add_directive_to_domain`. + +.. module:: docutils.parsers.rst + +.. class:: Directive + + The markup syntax of the new directive is determined by the follow five class + attributes: + + .. autoattribute:: required_arguments + .. autoattribute:: optional_arguments + .. autoattribute:: final_argument_whitespace + .. autoattribute:: option_spec + + Option validator functions take a single parameter, the option argument + (or ``None`` if not given), and should validate it or convert it to the + proper form. They raise :exc:`ValueError` or :exc:`TypeError` to indicate + failure. + + There are several predefined and possibly useful validators in the + :mod:`docutils.parsers.rst.directives` module. + + .. autoattribute:: has_content + + New directives must implement the :meth:`run` method: + + .. method:: run() + + This method must process the directive arguments, options and content, and + return a list of Docutils/Sphinx nodes that will be inserted into the + document tree at the point where the directive was encountered. + + Instance attributes that are always set on the directive are: + + .. attribute:: name + + The directive name (useful when registering the same directive class under + multiple names). + + .. attribute:: arguments + + The arguments given to the directive, as a list. + + .. attribute:: options + + The options given to the directive, as a dictionary mapping option names + to validated/converted values. + + .. attribute:: content + + The directive content, if given, as a :class:`!ViewList`. + + .. attribute:: lineno + + The absolute line number on which the directive appeared. This is not + always a useful value; use :attr:`srcline` instead. + + .. attribute:: content_offset + + Internal offset of the directive content. Used when calling + ``nested_parse`` (see below). + + .. attribute:: block_text + + The string containing the entire directive. + + .. attribute:: state + state_machine + + The state and state machine which controls the parsing. Used for + ``nested_parse``. + + +ViewLists +^^^^^^^^^ + +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. + +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 constructor takes a list of strings (lines) and a source (document) name. + +* The ``.append()`` method takes a line and a source name as well. + + +Parsing directive content as ReST +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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. + +Both APIs parse the content into a given node. They are used like this:: + + node = docutils.nodes.paragraph() + # either + nested_parse_with_titles(self.state, self.result, node) + # or + self.state.nested_parse(self.result, 0, node) + +.. 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:: + + from sphinx.util.docutils import switch_source_input + + # 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) + + .. 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. + + +.. seealso:: + + `Creating directives`_ HOWTO of the Docutils documentation + +.. _Creating directives: https://docutils.sourceforge.io/docs/howto/rst-directives.html diff --git a/doc/extdev/nodes.rst b/doc/extdev/nodes.rst new file mode 100644 index 0000000..7603763 --- /dev/null +++ b/doc/extdev/nodes.rst @@ -0,0 +1,103 @@ +.. _nodes: + +Doctree node classes added by Sphinx +==================================== + +.. module:: sphinx.addnodes + +Nodes for domain-specific object descriptions +--------------------------------------------- + +Top-level nodes +............... + +These nodes form the top-most levels of object descriptions. + +.. autoclass:: desc +.. autoclass:: desc_signature +.. autoclass:: desc_signature_line +.. autoclass:: desc_content +.. autoclass:: desc_inline + +Nodes for high-level structure in signatures +............................................ + +These nodes occur in in non-multiline :py:class:`desc_signature` nodes +and in :py:class:`desc_signature_line` nodes. + +.. autoclass:: desc_name +.. autoclass:: desc_addname + +.. autoclass:: desc_type +.. autoclass:: desc_returns +.. autoclass:: desc_parameterlist +.. autoclass:: desc_parameter +.. autoclass:: desc_optional +.. autoclass:: desc_annotation + +Nodes for signature text elements +................................. + +These nodes inherit :py:class:`desc_sig_element` and are generally translated +to ``docutils.nodes.inline`` by :py:class:`!SigElementFallbackTransform`. + +Extensions may create additional ``desc_sig_*``-like nodes but in order for +:py:class:`!SigElementFallbackTransform` to translate them to inline nodes +automatically, they must be added to :py:data:`SIG_ELEMENTS` via the class +keyword argument `_sig_element=True` of :py:class:`desc_sig_element`, e.g.: + + .. code-block:: python + + class desc_custom_sig_node(desc_sig_element, _sig_element=True): ... + +For backwards compatibility, it is still possible to add the nodes directly +using ``SIG_ELEMENTS.add(desc_custom_sig_node)``. + +.. autodata:: SIG_ELEMENTS + :no-value: + +.. autoclass:: desc_sig_element + +.. autoclass:: desc_sig_space +.. autoclass:: desc_sig_name +.. autoclass:: desc_sig_operator +.. autoclass:: desc_sig_punctuation +.. autoclass:: desc_sig_keyword +.. autoclass:: desc_sig_keyword_type +.. autoclass:: desc_sig_literal_number +.. autoclass:: desc_sig_literal_string +.. autoclass:: desc_sig_literal_char + +New admonition-like constructs +------------------------------ + +.. autoclass:: versionmodified +.. autoclass:: seealso + +Other paragraph-level nodes +------------------------------- + +.. autoclass:: compact_paragraph + +New inline nodes +---------------- + +.. autoclass:: index +.. autoclass:: pending_xref +.. autoclass:: pending_xref_condition +.. autoclass:: literal_emphasis +.. autoclass:: download_reference + +Special nodes +------------- + +.. autoclass:: only +.. autoclass:: highlightlang + +You should not need to generate the nodes below in extensions. + +.. autoclass:: glossary +.. autoclass:: toctree +.. autoclass:: start_of_file +.. autoclass:: productionlist +.. autoclass:: production diff --git a/doc/extdev/parserapi.rst b/doc/extdev/parserapi.rst new file mode 100644 index 0000000..c5db2ac --- /dev/null +++ b/doc/extdev/parserapi.rst @@ -0,0 +1,38 @@ +.. _parser-api: + +Parser API +========== + +`The docutils documentation describes`__ parsers as follows: + + The Parser analyzes the input document and creates a node tree + representation. + +__ https://docutils.sourceforge.io/docs/dev/hacking.html#parsing-the-document + +In Sphinx, the parser modules works as same as docutils. The parsers are +registered to Sphinx by extensions using Application APIs; +:meth:`.Sphinx.add_source_suffix()` and :meth:`.Sphinx.add_source_parser()`. + +The *source suffix* is a mapping from file suffix to file type. For example, +``.rst`` file is mapped to ``'restructuredtext'`` type. Sphinx uses the +file type to looking for parsers from registered list. On searching, +Sphinx refers to the ``Parser.supported`` attribute and picks up a parser +which contains the file type in the attribute. + +The users can override the source suffix mappings using +:confval:`source_suffix` like following:: + + # a mapping from file suffix to file types + source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown', + } + +You should indicate file types your parser supports. This will allow users +to configure their settings appropriately. + +.. module:: sphinx.parsers + +.. autoclass:: Parser + :members: diff --git a/doc/extdev/projectapi.rst b/doc/extdev/projectapi.rst new file mode 100644 index 0000000..238aeb4 --- /dev/null +++ b/doc/extdev/projectapi.rst @@ -0,0 +1,9 @@ +.. _project-api: + +Project API +=========== + +.. currentmodule:: sphinx.project + +.. autoclass:: Project + :members: diff --git a/doc/extdev/utils.rst b/doc/extdev/utils.rst new file mode 100644 index 0000000..e842f30 --- /dev/null +++ b/doc/extdev/utils.rst @@ -0,0 +1,37 @@ +Utilities +========= + +Sphinx provides utility classes and functions to develop extensions. + +Base classes for components +--------------------------- + +These base classes are useful to allow your extensions to obtain Sphinx +components (e.g. :class:`.Config`, :class:`.BuildEnvironment` and so on) easily. + +.. note:: The subclasses of them might not work with bare docutils because they + are strongly coupled with Sphinx. + +.. autoclass:: sphinx.transforms.SphinxTransform + :members: + +.. autoclass:: sphinx.transforms.post_transforms.SphinxPostTransform + :members: + +.. autoclass:: sphinx.util.docutils.SphinxDirective + :members: + +.. autoclass:: sphinx.util.docutils.SphinxRole + :members: + +.. autoclass:: sphinx.util.docutils.ReferenceRole + :members: + +.. autoclass:: sphinx.transforms.post_transforms.images.ImageConverter + :members: + +Utility components +------------------ + +.. autoclass:: sphinx.events.EventManager + :members: diff --git a/doc/faq.rst b/doc/faq.rst new file mode 100644 index 0000000..85ccb24 --- /dev/null +++ b/doc/faq.rst @@ -0,0 +1,354 @@ +.. _faq: + +Sphinx FAQ +========== + +This is a list of Frequently Asked Questions about Sphinx. Feel free to +suggest new entries! + +How do I... +----------- + +... create PDF files without LaTeX? + `rinohtype`_ provides a PDF builder that can be used as a drop-in + replacement for the LaTeX builder. + + .. _rinohtype: https://github.com/brechtm/rinohtype + +... get section numbers? + They are automatic in LaTeX output; for HTML, give a ``:numbered:`` option to + the :rst:dir:`toctree` directive where you want to start numbering. + +... customize the look of the built HTML files? + Use themes, see :doc:`/usage/theming`. + +... add global substitutions or includes? + Add them in the :confval:`rst_prolog` or :confval:`rst_epilog` config value. + +... display the whole TOC tree in the sidebar? + Use the :data:`toctree` callable in a custom layout template, probably in the + ``sidebartoc`` block. + +... write my own extension? + See the :doc:`/development/tutorials/index`. + +... convert from my existing docs using MoinMoin markup? + The easiest way is to convert to xhtml, then convert `xhtml to reST`_. + You'll still need to mark up classes and such, but the headings and code + examples come through cleanly. + +For many more extensions and other contributed stuff, see the sphinx-contrib_ +repository. + +.. _sphinx-contrib: https://github.com/sphinx-contrib/ + +.. _usingwith: + +Using Sphinx with... +-------------------- + +Read the Docs + `Read the Docs <https://readthedocs.org>`_ is a documentation hosting + service based around Sphinx. They will host sphinx documentation, along + with supporting a number of other features including version support, PDF + generation, and more. The `Getting Started`_ guide is a good place to start. + +Epydoc + There's a third-party extension providing an `api role`_ which refers to + 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>`_. + +SCons + Glenn Hutchings has written a SCons build script to build Sphinx + documentation; it is hosted here: + https://bitbucket-archive.softwareheritage.org/projects/zo/zondo/sphinx-scons.html + +PyPI + Jannis Leidel wrote a `setuptools command + <https://pypi.org/project/Sphinx-PyPI-upload/>`_ that automatically + uploads Sphinx documentation to the PyPI package documentation area at + https://pythonhosted.org/. + +GitHub Pages + Please add :py:mod:`sphinx.ext.githubpages` to your project. It allows you + to publish your document in GitHub Pages. It generates helper files for + GitHub Pages on building HTML document automatically. + +MediaWiki + See `sphinx-wiki`_, a project by Kevin Dunn. + + .. _sphinx-wiki: https://bitbucket-archive.softwareheritage.org/projects/ke/kevindunn/sphinx-wiki.html + +Google Analytics + You can use a custom ``layout.html`` template, like this: + + .. code-block:: html+jinja + + {% extends "!layout.html" %} + + {%- block extrahead %} + {{ super() }} + <script> + var _gaq = _gaq || []; + _gaq.push(['_setAccount', 'XXX account number XXX']); + _gaq.push(['_trackPageview']); + </script> + {% endblock %} + + {% block footer %} + {{ super() }} + <div class="footer">This page uses <a href="https://analytics.google.com/"> + Google Analytics</a> to collect statistics. You can disable it by blocking + the JavaScript coming from www.google-analytics.com. + <script> + (function() { + var ga = document.createElement('script'); + ga.src = ('https:' == document.location.protocol ? + 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; + ga.setAttribute('async', 'true'); + document.documentElement.firstChild.appendChild(ga); + })(); + </script> + </div> + {% endblock %} + + +Google Search + To replace Sphinx's built-in search function with Google Search, proceed as + follows: + + 1. Go to https://cse.google.com/cse/all to create the Google Search code + snippet. + + 2. Copy the code snippet and paste it into ``_templates/searchbox.html`` in + your Sphinx project: + + .. code-block:: html+jinja + + <div> + <h3>{{ _('Quick search') }}</h3> + <script> + (function() { + var cx = '......'; + var gcse = document.createElement('script'); + gcse.async = true; + gcse.src = 'https://cse.google.com/cse.js?cx=' + cx; + var s = document.getElementsByTagName('script')[0]; + s.parentNode.insertBefore(gcse, s); + })(); + </script> + <gcse:search></gcse:search> + </div> + + 3. Add ``searchbox.html`` to the :confval:`html_sidebars` configuration value. + +.. _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 + + +Sphinx vs. Docutils +------------------- + +tl;dr: *docutils* converts reStructuredText to multiple output formats. Sphinx +builds upon docutils to allow construction of cross-referenced and indexed +bodies of documentation. + +`docutils`__ is a text processing system for converting plain text +documentation into other, richer formats. As noted in the `docutils +documentation`__, docutils uses *readers* to read a document, *parsers* for +parsing plain text formats into an internal tree representation made up of +different types of *nodes*, and *writers* to output this tree in various +document formats. docutils provides parsers for one plain text format - +`reStructuredText`__ - though other, *out-of-tree* parsers have been +implemented including Sphinx's :doc:`Markdown parser </usage/markdown>`. On the +other hand, it provides writers for many different formats including HTML, +LaTeX, man pages, Open Document Format and XML. + +docutils exposes all of its functionality through a variety of `front-end +tools`__, such as ``rst2html``, ``rst2odt`` and ``rst2xml``. Crucially though, +all of these tools, and docutils itself, are concerned with individual +documents. They don't support concepts such as cross-referencing, indexing of +documents, or the construction of a document hierarchy (typically manifesting +in a table of contents). + +Sphinx builds upon docutils by harnessing docutils' readers and parsers and +providing its own :doc:`/usage/builders/index`. As a result, Sphinx wraps some +of the *writers* provided by docutils. This allows Sphinx to provide many +features that would simply not be possible with docutils, such as those +outlined above. + +__ https://docutils.sourceforge.io/ +__ https://docutils.sourceforge.io/docs/dev/hacking.html +__ https://docutils.sourceforge.io/rst.html +__ https://docutils.sourceforge.io/docs/user/tools.html + + +.. _epub-faq: + +Epub info +--------- + +The following list gives some hints for the creation of epub files: + +* Split the text into several files. The longer the individual HTML files are, + the longer it takes the ebook reader to render them. In extreme cases, the + rendering can take up to one minute. + +* Try to minimize the markup. This also pays in rendering time. + +* For some readers you can use embedded or external fonts using the CSS + ``@font-face`` directive. This is *extremely* useful for code listings which + are often cut at the right margin. The default Courier font (or variant) is + quite wide and you can only display up to 60 characters on a line. If you + replace it with a narrower font, you can get more characters on a line. You + may even use `FontForge <https://fontforge.github.io/>`_ and create + narrow variants of some free font. In my case I get up to 70 characters on a + line. + + You may have to experiment a little until you get reasonable results. + +* Test the created epubs. You can use several alternatives. The ones I am aware + of are Epubcheck_, Calibre_, FBreader_ (although it does not render the CSS), + and Bookworm_. For Bookworm, you can download the source from + https://code.google.com/archive/p/threepress and run your own local server. + +* Large floating divs are not displayed properly. + If they cover more than one page, the div is only shown on the first page. + In that case you can copy the :file:`epub.css` from the + ``sphinx/themes/epub/static/`` directory to your local ``_static/`` + directory and remove the float settings. + +* Files that are inserted outside of the ``toctree`` directive must be manually + included. This sometimes applies to appendixes, e.g. the glossary or + the indices. You can add them with the :confval:`epub_post_files` option. + +* The handling of the epub cover page differs from the reStructuredText + procedure which automatically resolves image paths and puts the images + into the ``_images`` directory. For the epub cover page put the image in the + :confval:`html_static_path` directory and reference it with its full path in + the :confval:`epub_cover` config option. + +* kindlegen_ command can convert from epub3 resulting file to ``.mobi`` file + for Kindle. You can get ``yourdoc.mobi`` under ``_build/epub`` after the + following command: + + .. code-block:: bash + + $ make epub + $ kindlegen _build/epub/yourdoc.epub + + The kindlegen command doesn't accept documents that have section + titles surrounding ``toctree`` directive: + + .. code-block:: rst + + Section Title + ============= + + .. toctree:: + + subdocument + + Section After Toc Tree + ====================== + + kindlegen assumes all documents order in line, but the resulting document + has complicated order for kindlegen:: + + ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml`` + + If you get the following error, fix your document structure: + + .. code-block:: none + + Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title) + Error(prcgen):E24001: The table of content could not be built. + +.. _Epubcheck: https://github.com/IDPF/epubcheck +.. _Calibre: https://calibre-ebook.com/ +.. _FBreader: https://fbreader.org/ +.. _Bookworm: https://www.oreilly.com/bookworm/index.html +.. _kindlegen: https://www.amazon.com/gp/feature.html?docId=1000765211 + +.. _texinfo-faq: + +Texinfo info +------------ + +There are two main programs for reading Info files, ``info`` and GNU Emacs. The +``info`` program has less features but is available in most Unix environments +and can be quickly accessed from the terminal. Emacs provides better font and +color display and supports extensive customization (of course). + +.. _texinfo-links: + +Displaying Links +~~~~~~~~~~~~~~~~ + +One noticeable problem you may encounter with the generated Info files is how +references are displayed. If you read the source of an Info file, a reference +to this section would look like:: + + * note Displaying Links: target-id + +In the stand-alone reader, ``info``, references are displayed just as they +appear in the source. Emacs, on the other-hand, will by default replace +``*note:`` with ``see`` and hide the ``target-id``. For example: + + :ref:`texinfo-links` + +One can disable generation of the inline references in a document +with :confval:`texinfo_cross_references`. That makes +an info file more readable with stand-alone reader (``info``). + +The exact behavior of how Emacs displays references is dependent on the variable +``Info-hide-note-references``. If set to the value of ``hide``, Emacs will hide +both the ``*note:`` part and the ``target-id``. This is generally the best way +to view Sphinx-based documents since they often make frequent use of links and +do not take this limitation into account. However, changing this variable +affects how all Info documents are displayed and most do take this behavior +into account. + +If you want Emacs to display Info files produced by Sphinx using the value +``hide`` for ``Info-hide-note-references`` and the default value for all other +Info files, try adding the following Emacs Lisp code to your start-up file, +``~/.emacs.d/init.el``. + +.. code-block:: elisp + + (defadvice info-insert-file-contents (after + sphinx-info-insert-file-contents + activate) + "Hack to make `Info-hide-note-references' buffer-local and + automatically set to `hide' iff it can be determined that this file + was created from a Texinfo file generated by Docutils or Sphinx." + (set (make-local-variable 'Info-hide-note-references) + (default-value 'Info-hide-note-references)) + (save-excursion + (save-restriction + (widen) (goto-char (point-min)) + (when (re-search-forward + "^Generated by \\(Sphinx\\|Docutils\\)" + (save-excursion (search-forward "\x1f" nil t)) t) + (set (make-local-variable 'Info-hide-note-references) + 'hide))))) + + +Notes +~~~~~ + +The following notes may be helpful if you want to create Texinfo files: + +- Each section corresponds to a different ``node`` in the Info file. + +- Colons (``:``) cannot be properly escaped in menu entries and xrefs. + They will be replaced with semicolons (``;``). + +- Links to external Info files can be created using the somewhat official URI + scheme ``info``. For example:: + + info:Texinfo#makeinfo_options diff --git a/doc/glossary.rst b/doc/glossary.rst new file mode 100644 index 0000000..e58ce6b --- /dev/null +++ b/doc/glossary.rst @@ -0,0 +1,103 @@ +.. _glossary: + +Glossary +======== + +.. glossary:: + + builder + A class (inheriting from :class:`~sphinx.builders.Builder`) that takes + parsed documents and performs an action on them. Normally, builders + translate the documents to an output format, but it is also possible to + use builders that e.g. check for broken links in the documentation, or + build coverage information. + + See :doc:`/usage/builders/index` for an overview over Sphinx's built-in + builders. + + configuration directory + The directory containing :file:`conf.py`. By default, this is the same as + the :term:`source directory`, but can be set differently with the **-c** + command-line option. + + directive + A reStructuredText markup element that allows marking a block of content + with special meaning. Directives are supplied not only by docutils, but + Sphinx and custom extensions can add their own. The basic directive + syntax looks like this: + + .. sourcecode:: rst + + .. directivename:: argument ... + :option: value + + Content of the directive. + + 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 + 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 + referring to "documents" expect such document names. + + Examples for document names are ``index``, ``library/zipfile``, or + ``reference/datamodel/types``. Note that there is no leading or trailing + slash. + + domain + A domain is a collection of markup (reStructuredText :term:`directive`\ s + and :term:`role`\ s) to describe and link to :term:`object`\ s belonging + together, e.g. elements of a programming language. Directive and role + names in a domain have names like ``domain:name``, e.g. ``py:function``. + + Having domains means that there are no naming problems when one set of + documentation wants to refer to e.g. C++ and Python classes. It also + means that extensions that support the documentation of whole new + languages are much easier to write. + + For more information, refer to :doc:`/usage/restructuredtext/domains`. + + environment + A structure where information about all documents under the root is saved, + and used for cross-referencing. The environment is pickled after the + parsing stage, so that successive runs only need to read and parse new and + changed documents. + + extension + A custom :term:`role`, :term:`directive` or other aspect of Sphinx that + allows users to modify any aspect of the build process within Sphinx. + + For more information, refer to :doc:`/usage/extensions/index`. + + master document + The document that contains the root :rst:dir:`toctree` directive. + + root document + Same as :term:`master document`. + + object + The basic building block of Sphinx documentation. Every "object + directive" (e.g. :rst:dir:`py:function` or :rst:dir:`object`) creates such + a block; and most objects can be cross-referenced to. + + RemoveInSphinxXXXWarning + The feature which is warned will be removed in Sphinx-XXX version. + It usually caused from Sphinx extensions which is using deprecated. + See also :ref:`when-deprecation-warnings-are-displayed`. + + role + A reStructuredText markup element that allows marking a piece of text. + Like directives, roles are extensible. The basic syntax looks like this: + ``:rolename:`content```. See :ref:`rst-inline-markup` for details. + + source directory + The directory which, including its subdirectories, contains all source + files for one Sphinx project. + + reStructuredText + An easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and + parser system. diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..e9aea1c --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,117 @@ +======= +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 re-use 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. + +See below for how to navigate Sphinx's documentation. + +.. seealso:: + + The `Sphinx documentation Table of Contents <contents.html>`_ has + a full list of this site's pages. + +.. _get-started: + +Get started +=========== + +These sections cover the basics of getting started with Sphinx, including +creating and building your own documentation from scratch. + +.. toctree:: + :maxdepth: 2 + :caption: Get started + + usage/quickstart + usage/installation + tutorial/index + +.. _user-guides: + +User Guides +=========== + +These sections cover various topics in using and extending Sphinx for various +use-cases. They are a comprehensive guide to using Sphinx in many contexts and +assume more knowledge of Sphinx. If you are new to Sphinx, we recommend +starting with :ref:`get-started`. + +.. toctree:: + :maxdepth: 2 + :caption: User Guides + + usage/index + development/index + latex + extdev/index + +Community guide +=============== + +Sphinx is community supported and welcomes contributions from anybody. +The sections below should help you get started joining the Sphinx community +as well as contributing. + +See the :doc:`Sphinx contributors' guide <internals/contributing>` if you would +like to contribute to the project. + +.. toctree:: + :maxdepth: 2 + :caption: Community + + support + internals/index + faq + authors + +Reference guide +=============== + +Reference documentation is more complete and programmatic in nature, it is a +collection of information that can be quickly referenced. If you would like +usecase-driven documentation, see :ref:`get-started` or :ref:`user-guides`. + +.. toctree:: + :maxdepth: 2 + :caption: Reference + + man/index + usage/configuration + usage/extensions/index + usage/restructuredtext/index + glossary + changes + examples diff --git a/doc/internals/code-of-conduct.rst b/doc/internals/code-of-conduct.rst new file mode 100644 index 0000000..8e31ef0 --- /dev/null +++ b/doc/internals/code-of-conduct.rst @@ -0,0 +1,5 @@ +:tocdepth: 2 + +.. _code_of_conduct: + +.. include:: ../../CODE_OF_CONDUCT diff --git a/doc/internals/contributing.rst b/doc/internals/contributing.rst new file mode 100644 index 0000000..195f6a5 --- /dev/null +++ b/doc/internals/contributing.rst @@ -0,0 +1,332 @@ +====================== +Contributing to Sphinx +====================== + +There are many ways you can contribute to Sphinx, be it filing bug reports or +feature requests, writing new documentation or submitting patches for new or +fixed behavior. This guide serves to illustrate how you can get started with +this. + +Get help +-------- + +The Sphinx community maintains a number of mailing lists and IRC channels. + +Stack Overflow with tag `python-sphinx`_ + Questions and answers about use and development. + +sphinx-users <sphinx-users@googlegroups.com> + Mailing list for user support. + +sphinx-dev <sphinx-dev@googlegroups.com> + Mailing list for development related discussions. + +#sphinx-doc on irc.libera.chat + IRC channel for development questions and user support. + +.. _python-sphinx: https://stackoverflow.com/questions/tagged/python-sphinx + +Bug Reports and Feature Requests +-------------------------------- + +If you have encountered a problem with Sphinx or have an idea for a new +feature, please submit it to the `issue tracker`_ on GitHub or discuss it +on the `sphinx-dev`_ mailing list. + +For bug reports, please include the output produced during the build process +and also the log file Sphinx creates after it encounters an unhandled +exception. The location of this file should be shown towards the end of the +error message. + +Including or providing a link to the source files involved may help us fix the +issue. If possible, try to create a minimal project that produces the error +and post that instead. + +.. _`issue tracker`: https://github.com/sphinx-doc/sphinx/issues +.. _`sphinx-dev`: mailto:sphinx-dev@googlegroups.com + + +Contribute code +--------------- + +The Sphinx source code is managed using Git and is hosted on `GitHub`__. The +recommended way for new contributors to submit code to Sphinx is to fork this +repository and submit a pull request after committing changes to their fork. +The pull request will then need to be approved by one of the core developers +before it is merged into the main repository. + +.. __: https://github.com/sphinx-doc/sphinx + +.. _contribute-get-started: + +Getting started +~~~~~~~~~~~~~~~ + +Before starting on a patch, we recommend checking for open issues or open a +fresh issue to start a discussion around a feature idea or a bug. If you feel +uncomfortable or uncertain about an issue or your changes, feel free to email +the *sphinx-dev* mailing list. + +These are the basic steps needed to start developing on Sphinx. + +#. Create an account on GitHub. + +#. Fork the main Sphinx repository (`sphinx-doc/sphinx + <https://github.com/sphinx-doc/sphinx>`_) using the GitHub interface. + +#. Clone the forked repository to your machine. :: + + git clone https://github.com/USERNAME/sphinx + cd sphinx + +#. Checkout the appropriate branch. + + Sphinx adopts Semantic Versioning 2.0.0 (refs: https://semver.org/ ). + + For changes that preserves backwards-compatibility of API and features, + they should be included in the next MINOR release, use the ``A.x`` branch. + :: + + git checkout A.x + + For incompatible or other substantial changes that should wait until the + next MAJOR release, use the ``master`` branch. + + For urgent release, a new PATCH branch must be branched from the newest + release tag (see :doc:`release-process` for detail). + +#. Setup a virtual environment. + + This is not necessary for unit testing, thanks to ``tox``, but it is + necessary if you wish to run ``sphinx-build`` locally or run unit tests + without the help of ``tox``:: + + virtualenv ~/.venv + . ~/.venv/bin/activate + pip install -e . + +#. Create a new working branch. Choose any name you like. :: + + git checkout -b feature-xyz + +#. Hack, hack, hack. + + Write your code along with tests that shows that the bug was fixed or that + the feature works as expected. + +#. Add a bullet point to :file:`CHANGES` if the fix or feature is not trivial + (small doc updates, typo fixes), then commit:: + + git commit -m '#42: Add useful new feature that does this.' + + GitHub recognizes certain phrases that can be used to automatically + update the issue tracker. For example:: + + git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.' + + would close issue #42. + +#. Push changes in the branch to your forked repository on GitHub:: + + git push origin feature-xyz + +#. Submit a pull request from your branch to the respective branch (``master`` + or ``A.x``). + +#. Wait for a core developer to review your changes. + +Coding style +~~~~~~~~~~~~ + +Please follow these guidelines when writing code for Sphinx: + +* Try to use the same code style as used in the rest of the project. + +* For non-trivial changes, please update the :file:`CHANGES` file. If your + changes alter existing behavior, please document this. + +* New features should be documented. Include examples and use cases where + appropriate. If possible, include a sample that is displayed in the + generated output. + +* When adding a new configuration variable, be sure to document it and update + :file:`sphinx/cmd/quickstart.py` if it's important enough. + +* Add appropriate unit tests. + +Style and type checks can be run as follows:: + + ruff . + mypy sphinx/ + +Unit tests +~~~~~~~~~~ + +Sphinx is tested using `pytest`__ for Python code and `Karma`__ for JavaScript. + +.. __: https://docs.pytest.org/en/latest/ +.. __: https://karma-runner.github.io + +To run Python unit tests, we recommend using ``tox``, which provides a number +of targets and allows testing against multiple different Python environments: + +* To list all possible targets:: + + tox -av + +* To run unit tests for a specific Python version, such as Python 3.10:: + + tox -e py310 + +* To run unit tests for a specific Python version and turn on deprecation + warnings so they're shown in the test output:: + + PYTHONWARNINGS=error tox -e py310 + +* Arguments to ``pytest`` can be passed via ``tox``, e.g., in order to run a + particular test:: + + tox -e py310 tests/test_module.py::test_new_feature + +You can also test by installing dependencies in your local environment:: + + pip install .[test] + +To run JavaScript tests, use ``npm``:: + + npm install + npm run test + +New unit tests should be included in the ``tests`` directory where +necessary: + +* For bug fixes, first add a test that fails without your changes and passes + after they are applied. + +* Tests that need a ``sphinx-build`` run should be integrated in one of the + existing test modules if possible. New tests that to ``@with_app`` and + then ``build_all`` for a few assertions are not good since *the test suite + should not take more than a minute to run*. + +.. versionadded:: 1.8 + + Sphinx also runs JavaScript tests. + +.. versionadded:: 1.6 + + ``sphinx.testing`` is added as a experimental. + +.. versionchanged:: 1.5.2 + + Sphinx was switched from nose to pytest. + +.. todo:: The below belongs in the developer guide + +Utility functions and pytest fixtures for testing are provided in +``sphinx.testing``. If you are a developer of Sphinx extensions, you can write +unit tests by using pytest. At this time, ``sphinx.testing`` will help your +test implementation. + +How to use pytest fixtures that are provided by ``sphinx.testing``? You can +require ``'sphinx.testing.fixtures'`` in your test modules or ``conftest.py`` +files like this:: + + pytest_plugins = 'sphinx.testing.fixtures' + +If you want to know more detailed usage, please refer to ``tests/conftest.py`` +and other ``test_*.py`` files under the ``tests`` directory. + + +Contribute documentation +------------------------ + +Contributing to documentation involves modifying the source files found in the +``doc/`` folder. To get started, you should first follow :ref:`contribute-get-started`, +and then take the steps below to work with the documentation. + +The following sections describe how to get started with contributing +documentation, as well as key aspects of a few different tools that we use. + +.. todo:: Add a more extensive documentation contribution guide. + +Build the documentation +~~~~~~~~~~~~~~~~~~~~~~~ + +To build the documentation, run the following command:: + + sphinx-build -M html ./doc ./build/sphinx -W --keep-going + +This will parse the Sphinx documentation's source files and generate HTML for +you to preview in ``build/sphinx/html``. + +You can also build a **live version of the documentation** that you can preview +in the browser. It will detect changes and reload the page any time you make +edits. To do so, run the following command:: + + sphinx-autobuild ./doc ./build/sphinx/ + +Translations +~~~~~~~~~~~~ + +The parts of messages in Sphinx that go into builds are translated into several +locales. The translations are kept as gettext ``.po`` files translated from the +master template :file:`sphinx/locale/sphinx.pot`. + +Sphinx uses `Babel <https://babel.pocoo.org/en/latest/>`_ to extract messages +and maintain the catalog files. The ``utils`` directory contains a helper +script, ``babel_runner.py``. + +* Use ``python babel_runner.py extract`` to update the ``.pot`` template. +* Use ``python babel_runner.py update`` to update all existing language + catalogs in ``sphinx/locale/*/LC_MESSAGES`` with the current messages in the + template file. +* Use ``python babel_runner.py compile`` to compile the ``.po`` files to binary + ``.mo`` files and ``.js`` files. + +When an updated ``.po`` file is submitted, run +``python babel_runner.py compile`` to commit both the source and the compiled +catalogs. + +When a new locale is submitted, add a new directory with the ISO 639-1 language +identifier and put ``sphinx.po`` in there. Don't forget to update the possible +values for :confval:`language` in ``doc/usage/configuration.rst``. + +The Sphinx core messages can also be translated on `Transifex +<https://www.transifex.com/sphinx-doc/sphinx-1/>`_. There ``tx`` client tool, +which is provided by the ``transifex_client`` Python package, can be used to +pull translations in ``.po`` format from Transifex. To do this, go to +``sphinx/locale`` and then run ``tx pull -f -l LANG`` where ``LANG`` is an +existing language identifier. It is good practice to run +``python babel_runner.py update`` afterwards to make sure the ``.po`` file has the +canonical Babel formatting. + + +Debugging tips +-------------- + +* Delete the build cache before building documents if you make changes in the + code by running the command ``make clean`` or using the + :option:`sphinx-build -E` option. + +* Use the :option:`sphinx-build -P` option to run ``pdb`` on exceptions. + +* Use ``node.pformat()`` and ``node.asdom().toxml()`` to generate a printable + representation of the document structure. + +* Set the configuration variable :confval:`keep_warnings` to ``True`` so + warnings will be displayed in the generated output. + +* Set the configuration variable :confval:`nitpicky` to ``True`` so that Sphinx + will complain about references without a known target. + +* Set the debugging options in the `Docutils configuration file + <https://docutils.sourceforge.io/docs/user/config.html>`_. + +* JavaScript stemming algorithms in ``sphinx/search/non-minified-js/*.js`` + are generated using `snowball <https://github.com/snowballstem/snowball>`_ + by cloning the repository, executing ``make dist_libstemmer_js`` and then + unpacking the tarball which is generated in ``dist`` directory. + + 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. diff --git a/doc/internals/index.rst b/doc/internals/index.rst new file mode 100644 index 0000000..187082e --- /dev/null +++ b/doc/internals/index.rst @@ -0,0 +1,15 @@ +==================== +Contribute to Sphinx +==================== + +This guide contains information about the Sphinx open source project itself. +This is where you can find information about how Sphinx is managed and learn +how to contribute to the project. + +.. toctree:: + :maxdepth: 2 + + contributing + release-process + organization + code-of-conduct diff --git a/doc/internals/organization.rst b/doc/internals/organization.rst new file mode 100644 index 0000000..9dec923 --- /dev/null +++ b/doc/internals/organization.rst @@ -0,0 +1,56 @@ +================================== +Organization of the Sphinx project +================================== + +The guide explains how the Sphinx project is organized. + +Core developers +--------------- + +The core developers of Sphinx have write access to the main repository. They +can commit changes, accept/reject pull requests, and manage items on the issue +tracker. + +Guidelines +~~~~~~~~~~ + +The following are some general guidelines for core developers: + +* Questionable or extensive changes should be submitted as a pull request + instead of being committed directly to the main repository. The pull + request should be reviewed by another core developer before it is merged. + +* Trivial changes can be committed directly but be sure to keep the repository + in a good working state and that all tests pass before pushing your changes. + +* When committing code written by someone else, please attribute the original + author in the commit message and any relevant :file:`CHANGES` entry. + +Membership +~~~~~~~~~~ + +Core membership is predicated on continued active contribution to the project. +In general, prospective cores should demonstrate: + +- a good understanding of one of more components of Sphinx + +- a history of helpful, constructive contributions + +- a willingness to invest time improving Sphinx + +Refer to :doc:`contributing` for more information on how you can get started. + +Other contributors +------------------ + +You do not need to be a core developer or have write access to be involved in +the development of Sphinx. You can submit patches or create pull requests +from forked repositories and have a core developer add the changes for you. + +Similarly, contributions are not limited to code patches. We also welcome help +triaging bugs, input on design decisions, reviews of existing patches and +documentation improvements. More information can be found in +:doc:`contributing`. + +A list of people that have contributed to Sphinx can be found in +:doc:`../authors`. diff --git a/doc/internals/release-process.rst b/doc/internals/release-process.rst new file mode 100644 index 0000000..50648cd --- /dev/null +++ b/doc/internals/release-process.rst @@ -0,0 +1,125 @@ +======================== +Sphinx's release process +======================== + +Versioning +---------- + +Sphinx adheres to :pep:`440` versions, with a ``major.minor.micro`` scheme for +the *release segment* (e.g. 1.2.3). +The major, minor, and micro version parts should be altered as follows: + +* The major version part should be incremented for incompatible behavior change and + public API updates. + +* The minor version part should be incremented for most releases of Sphinx, where + backwards-compatibility of API and features are preserves. + +* The micro version part should only be incremented for urgent bugfix-only releases. + +When the major version part is incremented, the minor and micro version parts +must be set to ``0``. +When the minor version part is incremented, the micro version part must be set +to ``0``. + +New major versions should come with a beta-testing period before the final +release. + + +Deprecating a feature +--------------------- + +There are a couple reasons that code in Sphinx might be deprecated: + +* If a feature has been improved or modified in a backwards-incompatible way, + the old feature or behavior will be deprecated. + +* Sometimes Sphinx will include a backport of a Python library that's not + included in a version of Python that Sphinx currently supports. When Sphinx + no longer needs to support the older version of Python that doesn't include + the library, the library will be deprecated in Sphinx. + +As the :ref:`deprecation-policy` describes, the first release of Sphinx that +deprecates a feature (``A.B``) should raise a ``RemovedInSphinxXXWarning`` +(where ``XX`` is the Sphinx version where the feature will be removed) when the +deprecated feature is invoked. Assuming we have good test coverage, these +warnings are converted to errors when running the test suite with warnings +enabled:: + + pytest -Wall + +Thus, when adding a ``RemovedInSphinxXXWarning`` you need to eliminate or +silence any warnings generated when running the tests. + + +.. _deprecation-policy: + +Deprecation policy +------------------ + +MAJOR and MINOR releases may deprecate certain features from previous +releases. If a feature is deprecated in a release A.x, it will continue to +work in all A.x.x versions (for all versions of x). It will continue to work +in all B.x.x versions but raise deprecation warnings. Deprecated features +will be removed at the C.0.0. It means the deprecated feature will work during +2 MAJOR releases at least. + +So, for example, if we decided to start the deprecation of a function in +Sphinx 2.x: + +* Sphinx 2.x will contain a backwards-compatible replica of the function + which will raise a ``RemovedInSphinx40Warning``. + This is a subclass of :exc:`python:PendingDeprecationWarning`, i.e. it + will not get displayed by default. + +* Sphinx 3.x will still contain the backwards-compatible replica, but + ``RemovedInSphinx40Warning`` will be a subclass of + :exc:`python:DeprecationWarning` then, and gets displayed by default. + +* Sphinx 4.0 will remove the feature outright. + +Deprecation warnings +~~~~~~~~~~~~~~~~~~~~ + +Sphinx will enable its ``RemovedInNextVersionWarning`` warnings by default, if +:envvar:`python:PYTHONWARNINGS` is not set. Therefore you can disable them +using: + +* ``PYTHONWARNINGS= make html`` (Linux/Mac) +* ``export PYTHONWARNINGS=`` and do ``make html`` (Linux/Mac) +* ``set PYTHONWARNINGS=`` and do ``make html`` (Windows) + +But you can also explicitly enable the pending ones using e.g. +``PYTHONWARNINGS=default`` (see the :ref:`Python docs on configuring warnings +<python:describing-warning-filters>`) for more details. + +Python version support policy +----------------------------- + +Sphinx supports at all minor versions of Python released in the past 42 months +from the anticipated release date with a minimum of 3 minor versions of Python. +This policy is derived from `NEP 29`_, a scientific Python domain standard. + +.. _NEP 29: https://numpy.org/neps/nep-0029-deprecation_policy.html + +For example, a version of Sphinx released in May 2024 would support Python 3.10, +3.11, and 3.12. + +This is a summary table with the current policy: + +=========== ====== +Date Python +=========== ====== +26 Dec 2021 3.8+ +----------- ------ +14 Apr 2023 3.9+ +----------- ------ +05 Apr 2024 3.10+ +----------- ------ +04 Apr 2025 3.11+ +=========== ====== + +Release procedures +------------------ + +The release procedures are listed in ``utils/release-checklist``. diff --git a/doc/latex.rst b/doc/latex.rst new file mode 100644 index 0000000..4c9a4e0 --- /dev/null +++ b/doc/latex.rst @@ -0,0 +1,1841 @@ +LaTeX customization +=================== + +.. module:: latex + :synopsis: LaTeX specifics. + +.. _contents: https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents + +.. raw:: latex + + \begingroup + \sphinxsetup{% + TitleColor={named}{DarkGoldenrod}, + pre_border-width=2pt, + pre_border-right-width=8pt, + pre_padding=5pt, + pre_border-radius=5pt, + pre_background-TeXcolor={named}{OldLace}, + pre_border-TeXcolor=Gold!90, + pre_box-shadow=6pt 6pt, + pre_box-shadow-TeXcolor=gray!20, + % + div.warning_border-width=3pt, + div.warning_padding=6pt, + div.warning_padding-right=18pt, + div.warning_padding-bottom=18pt, + div.warning_border-TeXcolor=DarkCyan, + div.warning_background-TeXcolor=LightCyan, + div.warning_box-shadow=-12pt -12pt inset, + div.warning_box-shadow-TeXcolor=Cyan, + % + attentionborder=3pt, + attentionBorderColor=Crimson, + attentionBgColor=FloralWhite, + % + noteborder=1pt, + noteBorderColor=Olive, + noteBgColor=Olive!10, + div.note_border-top-width=0pt, + div.note_border-bottom-width=0pt, + hintBorderColor=LightCoral, + } + \relax + +Unlike :ref:`the HTML builders <html-themes>`, the ``latex`` builder does not +benefit from prepared themes. The :ref:`latex-options`, and particularly the +:ref:`latex_elements <latex_elements_confval>` variable, provides much of the +interface for customization. For example: + +.. code-block:: latex + + # inside conf.py + latex_engine = 'xelatex' + latex_elements = { + 'fontpkg': r''' + \setmainfont{DejaVu Serif} + \setsansfont{DejaVu Sans} + \setmonofont{DejaVu Sans Mono} + ''', + 'preamble': r''' + \usepackage[titles]{tocloft} + \cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm} + \setlength{\cftchapnumwidth}{0.75cm} + \setlength{\cftsecindent}{\cftchapnumwidth} + \setlength{\cftsecnumwidth}{1.25cm} + ''', + 'fncychap': r'\usepackage[Bjornstrup]{fncychap}', + 'printindex': r'\footnotesize\raggedright\printindex', + } + latex_show_urls = 'footnote' + +.. note:: + + Keep in mind that backslashes must be doubled in Python string literals to + avoid interpretation as escape sequences. Alternatively, you may use raw + strings as is done above. + +.. _latex_elements_confval: + +The ``latex_elements`` configuration setting +-------------------------------------------- + +A dictionary that contains LaTeX snippets overriding those Sphinx usually puts +into the generated ``.tex`` files. Its ``'sphinxsetup'`` key is described +:ref:`separately <latexsphinxsetup>`. It allows also local configurations +inserted in generated files, via :dudir:`raw` directives. For example, in +the PDF documentation this chapter is styled especially, as will be described +later. + +Keys that you may want to override include: + +``'papersize'`` + Paper size option of the document class (``'a4paper'`` or + ``'letterpaper'``) + + Default: ``'letterpaper'`` + +``'pointsize'`` + Point size option of the document class (``'10pt'``, ``'11pt'`` or + ``'12pt'``) + + Default: ``'10pt'`` + +``'pxunit'`` + The value of the ``px`` when used in image attributes ``width`` and + ``height``. The default value is ``'0.75bp'`` which achieves + ``96px=1in`` (in TeX ``1in = 72bp = 72.27pt``.) To obtain for + example ``100px=1in`` use ``'0.01in'`` or ``'0.7227pt'`` (the latter + leads to TeX computing a more precise value, due to the smaller unit + used in the specification); for ``72px=1in``, simply use ``'1bp'``; for + ``90px=1in``, use ``'0.8bp'`` or ``'0.803pt'``. + + Default: ``'0.75bp'`` + + .. versionadded:: 1.5 + +``'passoptionstopackages'`` + A string which will be positioned early in the preamble, designed to + contain ``\\PassOptionsToPackage{options}{foo}`` commands. + + .. hint:: + + It may be also used for loading LaTeX packages very early in the + preamble. For example package ``fancybox`` is incompatible with + being loaded via the ``'preamble'`` key, it must be loaded earlier. + + Default: ``''`` + + .. versionadded:: 1.4 + +``'babel'`` + "babel" package inclusion, default ``'\\usepackage{babel}'`` (the + suitable document language string is passed as class option, and + ``english`` is used if no language.) For Japanese documents, the + default is the empty string. + + With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document to use + `polyglossia`_, but one should be aware that current `babel`_ has + improved its support for Unicode engines in recent years and for some + languages it may make sense to prefer ``babel`` over ``polyglossia``. + + .. _`polyglossia`: https://ctan.org/pkg/polyglossia + .. _`babel`: https://ctan.org/pkg/babel + + .. hint:: + + After modifying a core LaTeX key like this one, clean up the LaTeX + build repertory before next PDF build, else left-over auxiliary + files are likely to break the build. + + Default: ``'\\usepackage{babel}'`` (``''`` for Japanese documents) + + .. versionchanged:: 1.5 + For :confval:`latex_engine` set to ``'xelatex'``, the default + is ``'\\usepackage{polyglossia}\n\\setmainlanguage{<language>}'``. + + .. versionchanged:: 1.6 + ``'lualatex'`` uses same default setting as ``'xelatex'`` + + .. versionchanged:: 1.7.6 + For French, ``xelatex`` and ``lualatex`` default to using + ``babel``, not ``polyglossia``. + +``'fontpkg'`` + Font package inclusion. The default is:: + + r"""\usepackage{tgtermes} + \usepackage{tgheros} + \renewcommand\ttdefault{txtt} + """ + + For ``'xelatex'`` and ``'lualatex'`` however the default is to use + the GNU FreeFont. + + .. versionchanged:: 1.2 + Defaults to ``''`` when the :confval:`language` uses the Cyrillic + script. + + .. versionchanged:: 2.0 + Incorporates some font substitution commands to help support occasional + Greek or Cyrillic in a document using ``'pdflatex'`` engine. + + .. versionchanged:: 4.0.0 + + - The font substitution commands added at ``2.0`` have been moved + to the ``'fontsubstitution'`` key, as their presence here made + it complicated for user to customize the value of ``'fontpkg'``. + - The default font setting has changed: it still uses Times and + Helvetica clones for serif and sans serif, but via better, more + complete TeX fonts and associated LaTeX packages. The + monospace font has been changed to better match the Times clone. + +``'fncychap'`` + Inclusion of the "fncychap" package (which makes fancy chapter titles), + default ``'\\usepackage[Bjarne]{fncychap}'`` for English documentation + (this option is slightly customized by Sphinx), + ``'\\usepackage[Sonny]{fncychap}'`` for internationalized docs (because + the "Bjarne" style uses numbers spelled out in English). Other + "fncychap" styles you can try are "Lenny", "Glenn", "Conny", "Rejne" and + "Bjornstrup". You can also set this to ``''`` to disable fncychap. + + Default: ``'\\usepackage[Bjarne]{fncychap}'`` for English documents, + ``'\\usepackage[Sonny]{fncychap}'`` for internationalized documents, and + ``''`` for Japanese documents. + +``'preamble'`` + Additional preamble content. One may move all needed macros into some file + :file:`mystyle.tex.txt` of the project source repertory, and get LaTeX to + import it at run time:: + + 'preamble': r'\input{mystyle.tex.txt}', + # or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty + 'preamble': r'\usepackage{mystyle}', + + It is then needed to set appropriately :confval:`latex_additional_files`, + for example: + + .. code-block:: python + + latex_additional_files = ["mystyle.sty"] + + Do not use ``.tex`` as suffix, else the file is submitted itself to the PDF + build process, use ``.tex.txt`` or ``.sty`` as in the examples above. + + Default: ``''`` + +``'figure_align'`` + Latex figure float alignment. Whenever an image doesn't fit into the current + page, it will be 'floated' into the next page but may be preceded by any + other text. If you don't like this behavior, use 'H' which will disable + floating and position figures strictly in the order they appear in the + source. + + Default: ``'htbp'`` (here, top, bottom, page) + + .. versionadded:: 1.3 + +``'atendofbody'`` + Additional document content (right before the indices). + + Default: ``''`` + + .. versionadded:: 1.5 + +``'extrapackages'`` + Additional LaTeX packages. For example: + + .. code-block:: latex + + latex_elements = { + 'extrapackages': r'\usepackage{isodate}' + } + + The specified LaTeX packages will be loaded before + hyperref package and packages loaded from Sphinx extensions. + + .. hint:: + If you'd like to load additional LaTeX packages after hyperref, use + ``'preamble'`` key instead. + + Default: ``''`` + + .. versionadded:: 2.3 + +``'footer'`` + Additional footer content (before the indices). + + Default: ``''`` + + .. deprecated:: 1.5 + Use ``'atendofbody'`` key instead. + +Keys that don't need to be overridden unless in special cases are: + +``'extraclassoptions'`` + The default is the empty string. Example: ``'extraclassoptions': + 'openany'`` will allow chapters (for documents of the ``'manual'`` + type) to start on any page. + + Default: ``''`` + + .. versionadded:: 1.2 + + .. versionchanged:: 1.6 + Added this documentation. + +``'maxlistdepth'`` + LaTeX allows by default at most 6 levels for nesting list and + quote-like environments, with at most 4 enumerated lists, and 4 bullet + lists. Setting this key for example to ``'10'`` (as a string) will + allow up to 10 nested levels (of all sorts). Leaving it to the empty + string means to obey the LaTeX default. + + .. warning:: + + - Using this key may prove incompatible with some LaTeX packages + or special document classes which do their own list customization. + + - The key setting is silently *ignored* if ``\usepackage{enumitem}`` + is executed inside the document preamble. Use then rather the + dedicated commands of this LaTeX package. + + Default: ``6`` + + .. versionadded:: 1.5 + +``'inputenc'`` + "inputenc" package inclusion. + + Default: ``'\\usepackage[utf8]{inputenc}'`` when using pdflatex, else + ``''``. + + .. note:: + + If using ``utf8x`` in place of ``utf8`` it is mandatory to extend the + LaTeX preamble with suitable ``\PreloadUnicodePage{<number>}`` commands, + as per the ``utf8x`` documentation (``texdoc ucs`` on a TeXLive based + TeX installation). Else, unexpected and possibly hard-to-spot problems + (i.e. not causing a build crash) may arise in the PDF, in particular + regarding hyperlinks. + + Even if these precautions are taken, PDF build via ``pdflatex`` engine + may crash due to upstream LaTeX not being fully compatible with + ``utf8x``. For example, in certain circumstances related to + code-blocks, or attempting to include images whose filenames contain + Unicode characters. Indeed, starting in 2015, upstream LaTeX with + ``pdflatex`` engine has somewhat enhanced native support for Unicode and + is becoming more and more incompatible with ``utf8x``. In particular, + since the October 2019 LaTeX release, filenames can use Unicode + characters, and even spaces. At Sphinx level this means e.g. that the + :dudir:`image` and :dudir:`figure` directives are now compatible with + such filenames for PDF via LaTeX output. But this is broken if + ``utf8x`` is in use. + + .. versionchanged:: 1.4.3 + Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all + compilers. + +``'cmappkg'`` + "cmap" package inclusion. + + Default: ``'\\usepackage{cmap}'`` + + .. versionadded:: 1.2 + +``'fontenc'`` + Customize this from its default ``'\\usepackage[T1]{fontenc}'`` to: + + - ``'\\usepackage[X2,T1]{fontenc}'`` if you need occasional + Cyrillic letters (физика частиц), + + - ``'\\usepackage[LGR,T1]{fontenc}'`` if you need occasional + Greek letters (Σωματιδιακή φυσική). + + Use ``[LGR,X2,T1]`` rather if both are needed. + + .. attention:: + + - Do not use this key for a :confval:`latex_engine` other than + ``'pdflatex'``. + + - If Greek is main language, do not use this key. Since Sphinx 2.2.1, + ``xelatex`` will be used automatically as :confval:`latex_engine`. + + - The TeX installation may need some extra packages. For example, + on Ubuntu xenial, packages ``texlive-lang-greek`` and ``cm-super`` + are needed for ``LGR`` to work. And ``texlive-lang-cyrillic`` and + ``cm-super`` are needed for support of Cyrillic. + + .. versionchanged:: 1.5 + Defaults to ``'\\usepackage{fontspec}'`` when + :confval:`latex_engine` is ``'xelatex'``. + + .. versionchanged:: 1.6 + ``'lualatex'`` uses ``fontspec`` per default like ``'xelatex'``. + + .. versionchanged:: 2.0 + ``'lualatex'`` executes + ``\defaultfontfeatures[\rmfamily,\sffamily]{}`` to disable TeX + ligatures transforming `<<` and `>>` as escaping working with + ``pdflatex/xelatex`` failed with ``lualatex``. + + .. versionchanged:: 2.0 + Detection of ``LGR``, ``T2A``, ``X2`` to trigger support of + occasional Greek or Cyrillic letters (``'pdflatex'``). + + .. versionchanged:: 2.3.0 + ``'xelatex'`` executes + ``\defaultfontfeatures[\rmfamily,\sffamily]{}`` in order to avoid + contractions of ``--`` into en-dash or transforms of straight quotes + into curly ones in PDF (in non-literal text paragraphs) despite + :confval:`smartquotes` being set to ``False``. + +``'fontsubstitution'`` + Ignored if ``'fontenc'`` was not configured to use ``LGR`` or ``X2`` (or + ``T2A``). In case ``'fontpkg'`` key is configured for usage with some + TeX fonts known to be available in the ``LGR`` or ``X2`` encodings, set + this one to be the empty string. Else leave to its default. + + Ignored with :confval:`latex_engine` other than ``'pdflatex'``. + + .. versionadded:: 4.0.0 + +``'textgreek'`` + For the support of occasional Greek letters. + + It is ignored with ``'platex'``, ``'xelatex'`` or ``'lualatex'`` as + :confval:`latex_engine` and defaults to either the empty string or + to ``'\\usepackage{textalpha}'`` for ``'pdflatex'`` depending on + whether the ``'fontenc'`` key was used with ``LGR`` or not. Only + expert LaTeX users may want to customize this key. + + It can also be used as ``r'\usepackage{textalpha,alphabeta}'`` to let + ``'pdflatex'`` support Greek Unicode input in :rst:dir:`math` context. + For example ``:math:`α``` (U+03B1) will render as :math:`\alpha`. + + Default: ``'\\usepackage{textalpha}'`` or ``''`` if ``fontenc`` does not + include the ``LGR`` option. + + .. versionadded:: 2.0 + +``'geometry'`` + "geometry" package inclusion, the default definition is: + + .. code:: latex + + '\\usepackage{geometry}' + + with an additional ``[dvipdfm]`` for Japanese documents. + The Sphinx LaTeX style file executes: + + .. code:: latex + + \PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry} + + which can be customized via corresponding :ref:`'sphinxsetup' options + <latexsphinxsetup>`. + + Default: ``'\\usepackage{geometry}'`` (or + ``'\\usepackage[dvipdfm]{geometry}'`` for Japanese documents) + + .. versionadded:: 1.5 + + .. versionchanged:: 1.5.2 + ``dvipdfm`` option if :confval:`latex_engine` is ``'platex'``. + + .. versionadded:: 1.5.3 + The :ref:`'sphinxsetup' keys for the margins + <latexsphinxsetuphmargin>`. + + .. versionchanged:: 1.5.3 + The location in the LaTeX file has been moved to after + ``\usepackage{sphinx}`` and ``\sphinxsetup{..}``, hence also after + insertion of ``'fontpkg'`` key. This is in order to handle the paper + layout options in a special way for Japanese documents: the text + width will be set to an integer multiple of the *zenkaku* width, and + the text height to an integer multiple of the baseline. See the + :ref:`hmargin <latexsphinxsetuphmargin>` documentation for more. + +``'hyperref'`` + "hyperref" package inclusion; also loads package "hypcap" and issues + ``\urlstyle{same}``. This is done after :file:`sphinx.sty` file is + loaded and before executing the contents of ``'preamble'`` key. + + .. attention:: + + Loading of packages "hyperref" and "hypcap" is mandatory. + + .. versionadded:: 1.5 + Previously this was done from inside :file:`sphinx.sty`. + +``'maketitle'`` + "maketitle" call. Override if you want to generate a differently styled + title page. + + .. hint:: + + If the key value is set to + ``r'\newcommand\sphinxbackoftitlepage{<Extra + material>}\sphinxmaketitle'``, then ``<Extra material>`` will be + typeset on back of title page (``'manual'`` docclass only). + + Default: ``'\\sphinxmaketitle'`` + + .. versionchanged:: 1.8.3 + Original ``\maketitle`` from document class is not overwritten, + hence is re-usable as part of some custom setting for this key. + + .. versionadded:: 1.8.3 + ``\sphinxbackoftitlepage`` optional macro. It can also be defined + inside ``'preamble'`` key rather than this one. + +``'releasename'`` + Value that prefixes ``'release'`` element on title page. As for *title* and + *author* used in the tuples of :confval:`latex_documents`, it is inserted as + LaTeX markup. + + Default: ``'Release'`` + +``'tableofcontents'`` + "tableofcontents" call. The default of ``'\\sphinxtableofcontents'`` is a + wrapper of unmodified ``\tableofcontents``, which may itself be customized + by user loaded packages. Override if you want to generate a different table + of contents or put content between the title page and the TOC. + + Default: ``'\\sphinxtableofcontents'`` + + .. versionchanged:: 1.5 + Previously the meaning of ``\tableofcontents`` itself was modified + by Sphinx. This created an incompatibility with dedicated packages + modifying it also such as "tocloft" or "etoc". + +``'transition'`` + Commands used to display transitions. Override if you want to display + transitions differently. + + Default: ``'\n\n\\bigskip\\hrule\\bigskip\n\n'`` + + .. versionadded:: 1.2 + + .. versionchanged:: 1.6 + Remove unneeded ``{}`` after ``\\hrule``. + +``'makeindex'`` + "makeindex" call, the last thing before ``\begin{document}``. With + ``'\\usepackage[columns=1]{idxlayout}\\makeindex'`` the index will use + only one column. You may have to install ``idxlayout`` LaTeX package. + + Default: ``'\\makeindex'`` + +``'printindex'`` + "printindex" call, the last thing in the file. Override if you want to + generate the index differently, append some content after the index, or + change the font. As LaTeX uses two-column mode for the index it is + often advisable to set this key to + ``'\\footnotesize\\raggedright\\printindex'``. Or, to obtain a one-column + index, use ``'\\def\\twocolumn[#1]{#1}\\printindex'`` (this trick may fail + if using a custom document class; then try the ``idxlayout`` approach + described in the documentation of the ``'makeindex'`` key). + + Default: ``'\\printindex'`` + +``'fvset'`` + Customization of ``fancyvrb`` LaTeX package. + + The default value is ``'\\fvset{fontsize=auto}'`` which means that the + font size will adjust correctly if a code-block ends up in a footnote. + You may need to modify this if you use custom fonts: + ``'\\fvset{fontsize=\\small}'`` if the monospace font is Courier-like. + + Default: ``'\\fvset{fontsize=auto}'`` + + .. versionadded:: 1.8 + + .. versionchanged:: 2.0 + For ``'xelatex'`` and ``'lualatex'`` defaults to + ``'\\fvset{fontsize=\\small}'`` as this + is adapted to the relative widths of the FreeFont family. + + .. versionchanged:: 4.0.0 + Changed default for ``'pdflatex'``. Previously it was using + ``'\\fvset{fontsize=\\small}'``. + + .. versionchanged:: 4.1.0 + Changed default for Chinese documents to + ``'\\fvset{fontsize=\\small,formatcom=\\xeCJKVerbAddon}'`` + +Keys that are set by other options and therefore should not be overridden are: + +``'docclass'`` +``'classoptions'`` +``'title'`` +``'release'`` +``'author'`` + + +.. _latexsphinxsetup: + +The ``sphinxsetup`` configuration setting +----------------------------------------- + +.. versionadded:: 1.5 + +The ``'sphinxsetup'`` key of :ref:`latex_elements <latex_elements_confval>` +provides a LaTeX-type customization interface:: + + latex_elements = { + 'sphinxsetup': 'key1=value1, key2=value2, ...', + } + +It 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`. + +.. code-block:: latex + + .. raw:: latex + + \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. + } + + +And this is placed at the end of the chapter source to end the scope of +the configuration: + +.. code-block:: latex + + .. 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. + +``bookmarksdepth`` + Controls the depth of the collapsible bookmarks panel in the PDF. + May be either a number (e.g. ``3``) or a LaTeX sectioning name (e.g. + ``subsubsection``, i.e. without backslash). + For details, refer to the ``hyperref`` LaTeX docs. + + Default: ``5`` + + .. versionadded:: 4.0.0 + +.. _latexsphinxsetuphmargin: + +``hmargin, vmargin`` + The dimensions of the horizontal (resp. vertical) margins, passed as + ``hmargin`` (resp. ``vmargin``) option to the ``geometry`` package. + Example:: + + 'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in', + + Japanese documents currently accept only the one-dimension format for + these parameters. The ``geometry`` package is then passed suitable options + to get the text width set to an exact multiple of the *zenkaku* width, and + the text height set to an integer multiple of the baselineskip, with the + closest fit for the margins. + + Default: ``1in`` (equivalent to ``{1in,1in}``) + + .. hint:: + + For Japanese ``'manual'`` docclass with pointsize ``11pt`` or ``12pt``, + use the ``nomag`` extra document class option (cf. + ``'extraclassoptions'`` key of :confval:`latex_elements`) or so-called + TeX "true" units:: + + 'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw', + + .. versionadded:: 1.5.3 + +``marginpar`` + The ``\marginparwidth`` LaTeX dimension. For Japanese documents, the value + is modified to be the closest integer multiple of the *zenkaku* width. + + Default: ``0.5in`` + + .. versionadded:: 1.5.3 + +``verbatimwithframe`` + Boolean to specify if :rst:dir:`code-block`\ s and literal includes are + framed. Setting it to ``false`` does not deactivate use of package + "framed", because it is still in use for the optional background color. + + Default: ``true``. + +``verbatimwrapslines`` + Boolean to specify if long lines in :rst:dir:`code-block`\ 's contents are + 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 + 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. + + Default: ``true`` + +.. _latexsphinxsetupforcewraps: + +``verbatimforcewraps`` + Boolean to specify if long lines in :rst:dir:`code-block`\ 's contents + should be forcefully wrapped to never overflow due to long strings. + + .. note:: + + It is assumed that the Pygments_ LaTeXFormatter has not been used with + its ``texcomments`` or similar options which allow additional + (arbitrary) LaTeX mark-up. + + Also, in case of :confval:`latex_engine` set to ``'pdflatex'``, only + the default LaTeX handling of Unicode code points, i.e. ``utf8`` not + ``utf8x`` is allowed. + + .. _Pygments: https://pygments.org/ + + Default: ``false`` + + .. versionadded:: 3.5.0 + +``verbatimmaxoverfull`` + A number. If an unbreakable long string has length larger than the total + linewidth plus this number of characters, and if ``verbatimforcewraps`` + mode is on, the input line will be reset using the forceful algorithm + which applies breakpoints at each character. + + Default: ``3`` + + .. versionadded:: 3.5.0 + +``verbatimmaxunderfull`` + A number. If ``verbatimforcewraps`` mode applies, and if after applying + the line wrapping at spaces and punctuation, the first part of the split + line is lacking at least that number of characters to fill the available + width, then the input line will be reset using the forceful algorithm. + + As the default is set to a high value, the forceful algorithm is triggered + only in overfull case, i.e. in presence of a string longer than full + linewidth. Set this to ``0`` to force all input lines to be hard wrapped + at the current available linewidth:: + + latex_elements = { + 'sphinxsetup': "verbatimforcewraps, verbatimmaxunderfull=0", + } + + This can be done locally for a given code-block via the use of raw latex + directives to insert suitable ``\sphinxsetup`` (before and after) into the + latex file. + + Default: ``100`` + + .. versionadded:: 3.5.0 + +``verbatimhintsturnover`` + Boolean to specify if code-blocks display "continued on next page" and + "continued from previous page" hints in case of page breaks. + + Default: ``true`` + + .. versionadded:: 1.6.3 + .. versionchanged:: 1.7 + the default changed from ``false`` to ``true``. + +``verbatimcontinuedalign``, ``verbatimcontinuesalign`` + Horizontal position relative to the framed contents: either ``l`` (left + aligned), ``r`` (right aligned) or ``c`` (centered). + + Default: ``r`` + + .. versionadded:: 1.7 + +``parsedliteralwraps`` + Boolean to specify if long lines in :dudir:`parsed-literal`\ 's contents + should wrap. + + Default: ``true`` + + .. versionadded:: 1.5.2 + set this option value to ``false`` to recover former behavior. + +``inlineliteralwraps`` + Boolean to specify if line breaks are allowed inside inline literals: but + extra potential break-points (additionally to those allowed by LaTeX at + spaces or for hyphenation) are currently inserted only after the characters + ``. , ; ? ! /`` and ``\``. Due to TeX internals, white space in the line + will be stretched (or shrunk) in order to accommodate the linebreak. + + Default: ``true`` + + .. versionadded:: 1.5 + set this option value to ``false`` to recover former behavior. + + .. versionchanged:: 2.3.0 + added potential breakpoint at ``\`` characters. + +``verbatimvisiblespace`` + When a long code line is split, the last space character from the source + code line right before the linebreak location is typeset using this. + + Default: ``\textcolor{red}{\textvisiblespace}`` + +``verbatimcontinued`` + A LaTeX macro inserted at start of continuation code lines. Its + (complicated...) default typesets a small red hook pointing to the right:: + + \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}} + + .. versionchanged:: 1.5 + The breaking of long code lines was added at 1.4.2. The default + definition of the continuation symbol was changed at 1.5 to accommodate + various font sizes (e.g. code-blocks can be in footnotes). + +.. note:: + + Values for color keys must either: + + - 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 + ... + + - 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. + + .. _xcolor: https://ctan.org/pkg/xcolor + + .. versionchanged:: 5.3.0 + Formerly only the ``\definecolor`` syntax was accepted. + +``TitleColor`` + The color for titles (as configured via use of package "titlesec".) + + Default: ``{rgb}{0.126,0.263,0.361}`` + +``InnerLinkColor`` + A color passed to ``hyperref`` as value of ``linkcolor`` and + ``citecolor``. + + Default: ``{rgb}{0.208,0.374,0.486}``. + +``OuterLinkColor`` + A color passed to ``hyperref`` as value of ``filecolor``, ``menucolor``, + and ``urlcolor``. + + Default: ``{rgb}{0.216,0.439,0.388}`` + +``VerbatimColor`` + The background color for :rst:dir:`code-block`\ s. + + Default: ``{gray}{0.95}`` + + .. versionchanged:: 6.0.0 + + Formerly, it was ``{rgb}{1,1,1}`` (white). + +``VerbatimBorderColor`` + The frame color. + + Default: ``{RGB}{32,32,32}`` + + .. versionchanged:: 6.0.0 + + Formerly it was ``{rgb}{0,0,0}`` (black). + +``VerbatimHighlightColor`` + The color for highlighted lines. + + Default: ``{rgb}{0.878,1,1}`` + + .. versionadded:: 1.6.6 + +.. _tablecolors: + +``TableRowColorHeader`` + Sets the background color for (all) the header rows of tables. + + It will have an effect only if either the :confval:`latex_table_style` + contains ``'colorrows'`` or if the table is assigned the ``colorrows`` + class. It is ignored for tables with ``nocolorrows`` class. + + As for the other ``'sphinxsetup'`` keys, it can also be set or modified + from a ``\sphinxsetup{...}`` LaTeX command inserted via the :dudir:`raw` + directive, or also from a LaTeX environment associated to a `container + class <latexcontainer_>`_ and using such ``\sphinxsetup{...}``. + + Default: ``{gray}{0.86}`` + + There is also ``TableMergeColorHeader``. If used, sets a specific color + for merged single-row cells in the header. + + .. versionadded:: 5.3.0 + +``TableRowColorOdd`` + Sets the background color for odd rows in tables (the row count starts at + ``1`` at the first non-header row). Has an effect only if the + :confval:`latex_table_style` contains ``'colorrows'`` or for specific + tables assigned the ``colorrows`` class. + + Default: ``{gray}{0.92}`` + + There is also ``TableMergeColorOdd``. + + .. versionadded:: 5.3.0 + +``TableRowColorEven`` + Sets the background color for even rows in tables. + + Default ``{gray}{0.98}`` + + There is also ``TableMergeColorEven``. + + .. versionadded:: 5.3.0 + +``verbatimsep`` + The separation between code lines and the frame. + + See :ref:`additionalcss` for its alias ``pre_padding`` and + additional keys. + + Default: ``\fboxsep`` + +``verbatimborder`` + The width of the frame around :rst:dir:`code-block`\ s. See also + :ref:`additionalcss` for ``pre_border-width``. + + Default: ``\fboxrule`` + +``shadowsep`` + The separation between contents and frame for contents_ and + :dudir:`topic` boxes. + + See :ref:`additionalcss` for the alias ``div.topic_padding``. + + Default: ``5pt`` + +``shadowsize`` + The width of the lateral "shadow" to the right and bottom. + + See :ref:`additionalcss` for ``div.topic_box-shadow`` which allows to + configure separately the widths of the vertical and horizontal shadows. + + Default: ``4pt`` + + .. versionchanged:: 6.1.2 + Fixed a regression introduced at ``5.1.0`` which modified unintentionally + the width of topic boxes and worse had made usage of this key break PDF + builds. + +``shadowrule`` + The width of the frame around :dudir:`topic` boxes. See also + :ref:`additionalcss` for ``div.topic_border-width``. + + Default: ``\fboxrule`` + +|notebdcolors| + The color for the two horizontal rules used by Sphinx in LaTeX for styling + a :dudir:`note` type admonition. + + Default: ``{rgb}{0,0,0}`` (black) + +|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`. + + Default: ``{rgb}{1,1,1}`` (white) + + .. versionadded:: 6.2.0 + +|notetextcolors| + The optional color for the contents. + + Default: unset (uses ambient text color, a priori black) + + .. versionadded:: 6.2.0 + + To be considered experimental until 7.0.0. These options have aliases + ``div.note_TeXcolor`` (etc) described in :ref:`additionalcss`. Using + the latter will let Sphinx switch to a more complex LaTeX code, + which supports the customizability described in :ref:`additionalcss`. + +|notetexextras| + Some extra LaTeX code (such as ``\bfseries`` or ``\footnotesize``) + to be executed at start of the contents. + + Default: empty + + .. versionadded:: 6.2.0 + + To be considered experimental until 7.0.0. These options have aliases + ``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. + + Default: ``0.5pt`` + +.. only:: not latex + + |warningbdcolors| + The color for the admonition frame. + + Default: ``{rgb}{0,0,0}`` (black) + +.. only:: latex + + |wgbdcolorslatex| + The color for the admonition frame. + + Default: ``{rgb}{0,0,0}`` (black) + +|warningbgcolors| + The background colors for the respective admonitions. + + Default: ``{rgb}{1,1,1}`` (white) + +|warningborders| + The width of the frame. See + :ref:`additionalcss` for keys allowing to configure separately each + border width. + + Default: ``1pt`` + +``AtStartFootnote`` + LaTeX macros inserted at the start of the footnote text at bottom of page, + after the footnote number. + + Default: ``\mbox{ }`` + +``BeforeFootnote`` + LaTeX macros inserted before the footnote mark. The default removes + possible space before it (else, TeX could insert a line break there). + + Default: ``\leavevmode\unskip`` + + .. versionadded:: 1.5 + +``HeaderFamily`` + default ``\sffamily\bfseries``. Sets the font used by headings. + + +.. |notebdcolors| replace:: ``noteBorderColor``, ``hintBorderColor``, + ``importantBorderColor``, ``tipBorderColor`` + +.. |notebgcolors| replace:: ``noteBgColor``, ``hintBgColor``, + ``importantBgColor``, ``tipBgColor`` + +.. |notetextcolors| replace:: ``noteTextColor``, ``hintTextColor``, + ``importantTextColor``, ``tipTextColor`` + +.. |notetexextras| replace:: ``noteTeXextras``, ``hintTeXextras``, + ``importantTeXextras``, ``tipTeXextras`` + +.. |warningbdcolors| replace:: ``warningBorderColor``, ``cautionBorderColor``, + ``attentionBorderColor``, ``dangerBorderColor``, + ``errorBorderColor`` + +.. |wgbdcolorslatex| replace:: ``warningBorderColor``, and + ``(caution|attention|danger|error)BorderColor`` + +.. else latex goes into right margin, as it does not hyphenate the names + +.. |warningbgcolors| replace:: ``warningBgColor``, ``cautionBgColor``, + ``attentionBgColor``, ``dangerBgColor``, + ``errorBgColor`` + +.. |warningborders| replace:: ``warningborder``, ``cautionborder``, + ``attentionborder``, ``dangerborder``, + ``errorborder`` + +.. _additionalcss: + +Additional CSS-like ``'sphinxsetup'`` keys +------------------------------------------- + +.. versionadded:: 5.1.0 + + For :rst:dir:`code-block`, :dudir:`topic` and contents_ directive, + and strong-type admonitions (:dudir:`warning`, :dudir:`error`, ...). + +.. versionadded:: 6.2.0 + + Also the :dudir:`note`, :dudir:`hint`, :dudir:`important` and :dudir:`tip` + admonitions can be styled this way. Using for them *any* of the listed + options will trigger usage of a more complex LaTeX code than the one used + per default (``sphinxheavybox`` vs ``sphinxlightbox``). Setting the new + ``noteBgColor`` (or ``hintBgColor``, ...) also triggers usage of + ``sphinxheavybox`` for :dudir:`note` (or :dudir:`hint`, ...). + +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 +inserted via the :dudir:`raw` directive) and the CSS syntax is only imitated. + +.. important:: Low-level LaTeX errors causing a build failure can happen if + 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 + ``\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) + ...<other options> + + * A colon in place of the equal sign will break LaTeX. + + * ``...border-width`` or ``...padding`` expect a *single* dimension: they can not + be used so far with space separated dimensions. + + * ``...top-right-radius`` et al. values may be either a single or *two* space + separated dimensions. + + * Dimension specifications must use TeX units such as ``pt`` or ``cm`` or + ``in``. The ``px`` unit is recognized by ``pdflatex`` and ``lualatex`` + but not by ``xelatex`` or ``platex``. + + * It is allowed for such specifications to be so-called "dimensional + expressions", e.g. ``\fboxsep+2pt`` or ``0.5\baselineskip`` are valid + inputs. The expressions will be evaluated only at the typesetting time. + Be careful though if using as in these examples TeX control sequences to + double the backslash or to employ a raw Python string for the value of + the :ref:`'sphinxsetup' <latexsphinxsetup>` key. + + * As a rule, avoid inserting unneeded spaces in the key values: especially + for the radii an input such ``2 pt 3pt`` will break LaTeX. Beware also + that ``\fboxsep \fboxsep`` will not be seen as space separated in LaTeX. + You must use something such as ``{\fboxsep} \fboxsep``. Or use + directly ``3pt 3pt`` which is a priori equivalent and simpler. + +The options are all named in a similar pattern which depends on a ``prefix``, +which is then followed by an underscore, then the property name. + +.. csv-table:: + :header: Directive, Option prefix, LaTeX environment + + :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``) + +Here are now these options as well as their common defaults. +Replace below ``<prefix>`` by the actual prefix as explained above. Don't +forget the underscore separating the prefix from the property names. + +- | ``<prefix>_border-top-width``, + | ``<prefix>_border-right-width``, + | ``<prefix>_border-bottom-width``, + | ``<prefix>_border-left-width``, + | ``<prefix>_border-width``. 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: + + * ``\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``. + +- ``<prefix>_box-decoration-break`` can be set to either ``clone`` or + ``slice`` and configures the behavior at page breaks. + It defaults to ``slice`` for :rst:dir:`code-block` (i.e. for ``<prefix>=pre``) + since 6.0.0. For other directives the default is ``clone``. +- | ``<prefix>_padding-top``, + | ``<prefix>_padding-right``, + | ``<prefix>_padding-bottom``, + | ``<prefix>_padding-left``, + | ``<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: + + * ``\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. + + .. important:: + + 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. + + * 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``, + | ``<prefix>_border-bottom-left-radius``, + | ``<prefix>_border-radius``. This last key sets the first four to + 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: + + * ``\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. + + See a remark above about traps with spaces in LaTeX. +- ``<prefix>_box-shadow`` is special in so far as it may be: + + * the ``none`` keyword, + * or a single dimension (giving both x-offset and y-offset), + * or two dimensions (separated by a space), + * or two dimensions followed by the keyword ``inset``. + + The x-offset and y-offset may be negative. The default is ``none``, + *except* for the :dudir:`topic` or contents_ directives, for which it is + ``4pt 4pt``, i.e. the shadow has a width of ``4pt`` and extends to the right + and below the frame. The lateral shadow then extends into the page right + margin. +- | ``<prefix>_border-TeXcolor``, + | ``<prefix>_background-TeXcolor``, + | ``<prefix>_box-shadow-TeXcolor``, + | ``<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 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. + + For all other types, the border color defaults to black and the background + color to white. + + 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, + the naming ``TeXcolor`` is to stress that the input syntax is the TeX one + for colors not an HTML/CSS one. If package ``xcolor`` is available in the + LaTeX installation, one can use directly named colors as key values. + Consider passing options such as ``dvipsnames``, ``svgnames`` or ``x11names`` + to ``xcolor`` via ``'passoptionstopackages'`` key of :confval:`latex_elements`. + + If ``<prefix>_TeXcolor`` is set, a ``\color`` command is inserted at + start of the directive contents; for admonitions, this happens after the + heading which reproduces the admonition type. + +- ``<prefix>_TeXextras``: if set, its value must be some LaTeX command or + commands, for example ``\itshape``. These commands will be inserted at the + start of the contents; for admonitions, this happens after the heading which + reproduces the admonition type. + +.. note:: + + - All directives support ``box-decoration-break`` to be set to ``slice``. + + .. versionchanged:: 6.2.0 + + Formerly, only :rst:dir:`code-block` did. The default remains + ``clone`` for all other directives, but this will probably change at + 7.0.0. + + - The corners of rounded boxes may be elliptical. + + .. versionchanged:: 6.2.0 + + Formerly, only circular rounded corners were supported and a rounded + corner forced the whole frame to use the same constant width from + ``<prefix>_border-width``. + + - Inset shadows are incompatible with rounded corners. In case + both are specified the inset shadow will simply be ignored. + + .. versionchanged:: 6.2.0 + + Formerly it was to the contrary the rounded corners which were ignored + in case an inset shadow was specified. + + - ``<prefix>_TeXcolor`` and ``<prefix>_TeXextras`` are new with 6.2.0. + + Usefulness is doubtful in the case of :rst:dir:`code-block`: + + - ``pre_TeXcolor`` will influence only the few non-Pygments highlighted + tokens; it does color the line numbers, but if one wants to color + *only* them one has to go through the ``fancyvrb`` interface. + + - ``pre_TeXextras=\footnotesize`` for example may be replaced by usage of + the :confval:`latex_elements` key ``'fvset'``. For ``'lualatex'`` or + ``'xelatex'`` Sphinx includes in the preamble already + ``\fvset{fontsize=\small}`` and this induces ``fancyvrb`` into + overriding a ``\footnotesize`` coming from ``pre_TeXextras``. One has + to use ``pre_TeXextras=\fvset{fontsize=\footnotesize}`` syntax. + Simpler to set directly the :confval:`latex_elements` key + ``'fvset'``... + + Consider these options experimental and that some implementation details + may change. For example if the ``pre_TeXextras`` LaTeX commands were put + by Sphinx in another location it could override the ``'fvset'`` effect, + perhaps this is what will be done in a future release. + + - Rounded boxes are done using the pict2e_ interface to some basic PDF + graphics operations. If this LaTeX package can not be found the build + will proceed and render all boxes with straight corners. + + - Elliptic corners use the ellipse_ LaTeX package which extends pict2e_. + If this LaTeX package can not be found rounded corners will be circular + arcs (or straight if pict2e_ is not available). + +.. _pict2e: https://ctan.org/pkg/pict2e +.. _ellipse: https://ctan.org/pkg/ellipse + + +The following legacy behavior is currently not customizable: + +- For :rst:dir:`code-block`, padding and border-width and shadow (if one adds + one) will go into the margin; the code lines remain at the same place + independently of the values of the padding and border-width, except for + being shifted vertically of course to not overwrite other text due to the + width of the border or external shadow. + +- For :dudir:`topic` (and contents_) the shadow (if on right) goes into the + page margin, but the border and the extra padding are kept within the text + area. Same for admonitions. + +- The contents_ and :dudir:`topic` directives are governed by the same options + with ``div.topic`` prefix: the Sphinx LaTeX mark-up uses for both directives + the same ``sphinxShadowBox`` environment which has currently no additional + branching, contrarily to the ``sphinxadmonition`` environment which branches + according to the admonition directive name, e.g. either to ``sphinxnote`` + or ``sphinxwarning`` etc... + + +LaTeX macros and environments +----------------------------- + +The "LaTeX package" file :file:`sphinx.sty` loads various components +providing support macros (aka commands), and environments, which are used in +the mark-up produced on output from the ``latex`` builder, before conversion +to ``pdf`` via the LaTeX toolchain. Also the "LaTeX class" files +:file:`sphinxhowto.cls` and :file:`sphinxmanual.cls` define or customize some +environments. All of these files can be found in the latex build repertory. + +Some of these provide facilities not available from pre-existing LaTeX +packages and work around LaTeX limitations with lists, table cells, verbatim +rendering, footnotes, etc... + +Others simply define macros with public names to make overwriting their +defaults easy via user-added contents to the preamble. We will survey most of +those public names here, but defaults have to be looked at in their respective +definition files. + +.. hint:: + + Sphinx LaTeX support code is split across multiple smaller-sized files. + Rather than adding code to the preamble via + `latex_elements <latex_elements_confval_>`_\ [``'preamble'``] it is + also possible to replace entirely one of the component files of Sphinx + LaTeX code with a custom version, simply by including a modified copy in + the project source and adding the filename to the + :confval:`latex_additional_files` list. Check the LaTeX build repertory + for the filenames and contents. + +.. versionchanged:: 4.0.0 + split of :file:`sphinx.sty` into multiple smaller units, to facilitate + customization of many aspects simultaneously. + +.. _latex-macros: + +Macros +~~~~~~ + +- Text styling commands: + + .. csv-table:: + :header: Name, ``maps argument #1 to:`` + :align: left + :class: longtable + :delim: ; + + ``\sphinxstrong``; ``\textbf{#1}`` + ``\sphinxcode``; ``\texttt{#1}`` + ``\sphinxbfcode``; ``\textbf{\sphinxcode{#1}}`` + ``\sphinxemail``; ``\textsf{#1}`` + ``\sphinxtablecontinued``; ``\textsf{#1}`` + ``\sphinxtitleref``; ``\emph{#1}`` + ``\sphinxmenuselection``; ``\emph{#1}`` + ``\sphinxguilabel``; ``\emph{#1}`` + ``\sphinxkeyboard``; ``\sphinxcode{#1}`` + ``\sphinxaccelerator``; ``\underline{#1}`` + ``\sphinxcrossref``; ``\emph{#1}`` + ``\sphinxtermref``; ``\emph{#1}`` + ``\sphinxsamedocref``; ``\emph{#1}`` + ``\sphinxparam``; ``\emph{#1}`` + ``\sphinxtypeparam``; ``\emph{#1}`` + ``\sphinxoptional``; ``[#1]`` with larger brackets, see source + + .. versionadded:: 1.4.5 + Use of ``\sphinx`` prefixed macro names to limit possibilities of conflict + with LaTeX packages. + + .. versionadded:: 1.8 + ``\sphinxguilabel`` + + .. versionadded:: 3.0 + ``\sphinxkeyboard`` + + .. versionadded:: 6.2.0 + ``\sphinxparam``, ``\sphinxsamedocref`` + + .. versionadded:: 7.1.0 + ``\sphinxparamcomma`` which defaults to a comma followed by a space and + ``\sphinxparamcommaoneperline`` which is used for one-parameter-per-line + signatures (see :confval:`maximum_signature_line_length`). It defaults + to ``\texttt{,}`` to make these end-of-line separators more distinctive. + + Signatures of Python functions are rendered as ``name<space>(parameters)`` + or ``name<space>[type parameters]<space>(parameters)`` (see :pep:`695`) + where the length of ``<space>`` is set to ``0pt`` by default. + This can be changed via ``\setlength{\sphinxsignaturelistskip}{1ex}`` + for instance. + +- More text styling: + + .. csv-table:: + :header: Name, ``maps argument #1 to:`` + :align: left + :class: longtable + :delim: ; + + ``\sphinxstyleindexentry``; ``\texttt{#1}`` + ``\sphinxstyleindexextra``; ``(\emph{#1})`` (with a space upfront) + ``\sphinxstyleindexpageref``; ``, \pageref{#1}`` + ``\sphinxstyleindexpagemain``; ``\textbf{#1}`` + ``\sphinxstyleindexlettergroup``; ``{\Large\sffamily#1}\nopagebreak\vspace{1mm}`` + ``\sphinxstyleindexlettergroupDefault``; check source, too long for here + ``\sphinxstyletopictitle``; ``\textbf{#1}\par\medskip`` + ``\sphinxstylesidebartitle``; ``\textbf{#1}\par\medskip`` + ``\sphinxstyleothertitle``; ``\textbf{#1}`` + ``\sphinxstylesidebarsubtitle``; ``~\\\textbf{#1} \smallskip`` + ``\sphinxstyletheadfamily``; ``\sffamily`` (*this one has no argument*) + ``\sphinxstyleemphasis``; ``\emph{#1}`` + ``\sphinxstyleliteralemphasis``; ``\emph{\sphinxcode{#1}}`` + ``\sphinxstylestrong``; ``\textbf{#1}`` + ``\sphinxstyleliteralstrong``; ``\sphinxbfcode{#1}`` + ``\sphinxstyleabbreviation``; ``\textsc{#1}`` + ``\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`` + + .. versionadded:: 1.5 + These macros were formerly hard-coded as non customizable ``\texttt``, + ``\emph``, etc... + + .. versionadded:: 1.6 + ``\sphinxstyletheadfamily`` which defaults to ``\sffamily`` and allows + multiple paragraphs in header cells of tables. + + .. versionadded:: 1.6.3 + ``\sphinxstylecodecontinued`` and ``\sphinxstylecodecontinues``. + + .. versionadded:: 1.8 + ``\sphinxstyleindexlettergroup``, ``\sphinxstyleindexlettergroupDefault``. + + .. 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: + + .. code-block:: latex + + \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 + } + +- ``\sphinxtableofcontents``: A wrapper (defined differently in + :file:`sphinxhowto.cls` and in :file:`sphinxmanual.cls`) of standard + ``\tableofcontents``. The macro ``\sphinxtableofcontentshook`` is executed + during its expansion right before ``\tableofcontents`` itself. + + .. versionchanged:: 1.5 + Formerly, the meaning of ``\tableofcontents`` was modified by Sphinx. + + .. versionchanged:: 2.0 + Hard-coded redefinitions of ``\l@section`` and ``\l@subsection`` formerly + done during loading of ``'manual'`` docclass are now executed later via + ``\sphinxtableofcontentshook``. This macro is also executed by the + ``'howto'`` docclass, but defaults to empty with it. + + .. hint:: + + If adding to preamble the loading of ``tocloft`` package, also add to + preamble ``\renewcommand\sphinxtableofcontentshook{}`` else it will reset + ``\l@section`` and ``\l@subsection`` cancelling ``tocloft`` customization. + +- ``\sphinxmaketitle``: Used as the default setting of the ``'maketitle'`` + :confval:`latex_elements` key. + Defined in the class files :file:`sphinxmanual.cls` and + :file:`sphinxhowto.cls`. + + .. versionchanged:: 1.8.3 + Formerly, ``\maketitle`` from LaTeX document class was modified by + Sphinx. + +- ``\sphinxbackoftitlepage``: For ``'manual'`` docclass, and if it is + defined, it gets executed at end of ``\sphinxmaketitle``, before the final + ``\clearpage``. Use either the ``'maketitle'`` key or the ``'preamble'`` key + of :confval:`latex_elements` to add a custom definition of + ``\sphinxbackoftitlepage``. + + .. versionadded:: 1.8.3 + +- ``\sphinxcite``: A wrapper of standard ``\cite`` for citation references. + + +.. _sphinxbox: + +The ``\sphinxbox`` command +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 6.2.0 + +The ``\sphinxbox[key=value,...]{inline text}`` command can be used to "box" +inline text elements with all the customizability which has been described in +:ref:`additionalcss`. It is a LaTeX command with one optional argument, which +is a comma-separated list of key=value pairs, as for :ref:`latexsphinxsetup`. +Here is the complete list of keys. They don't use any prefix. + +- ``border-width``, +- ``border-top-width``, ``border-right-width``, ``border-bottom-width``, + ``border-left-width``, +- ``padding``, +- ``padding-top``, ``padding-right``, ``padding-bottom``, ``padding-left``, +- ``border-radius``, +- ``border-top-left-radius``, ``border-top-right-radius``, + ``border-bottom-right-radius``, ``border-bottom-left-radius``, +- ``box-shadow``, +- ``border-TeXcolor``, ``background-TeXcolor``, ``box-shadow-TeXcolor``, + ``TeXcolor``, +- ``TeXextras``, +- and ``addstrut`` which is a boolean key, i.e. to be used as ``addstrut=true``, + or ``addstrut`` alone where ``=true`` is omitted, or ``addstrut=false``. + +This last key is specific to ``\sphinxbox`` and it means to add a ``\strut`` +so that heights and depths are equalized across various instances on the same +line with varying contents. The default is ``addstrut=false``. + +.. important:: + + Perhaps the default will turn into ``addstrut=true`` at 7.0.0 depending on + feedback until then. + +The combination ``addstrut, padding-bottom=0pt, padding-top=1pt`` is often +satisfactory. + +Refer to :ref:`additionalcss` for important syntax information regarding the +other keys. The default +configuration uses no shadow, a border-width of ``\fboxrule``, a padding of +``\fboxsep``, circular corners with radii ``\fboxsep`` and background and +border colors as for the default rendering of code-blocks. + +When a ``\sphinxbox`` usage is nested within another one, it will ignore the +options of the outer one: it first resets all options to their default state +as they were prior to applying the outer box options, then it applies its own +specific ones. + +One can modify these defaults via the command ``\sphinxboxsetup{key=value,...}``. +The effect is cumulative, if one uses this command multiple times. Here the +options are a mandatory argument so are within curly braces, not square +brackets. + +Here is some example of use: + +.. code-block:: latex + + latex_elements = { + 'preamble': r''' + % modify globally the defaults + \sphinxboxsetup{border-width=2pt,% + border-radius=4pt,% + background-TeXcolor=yellow!20} + % configure some styling element with some extra specific options: + \protected\def\sphinxkeyboard#1{\sphinxbox[border-TeXcolor=green]{\sphinxcode{#1}}} + ''', + } + +A utility ``\newsphinxbox`` is provided to create a new boxing macro, say +``\foo`` which will act exactly like ``\sphinxbox`` but with a given extra +configuration: + +.. code-block:: latex + + % the specific options to \foo are within brackets + \newsphinxbox[border-radius=0pt, box-shadow=2pt 2pt]{\foo} + % then use this \foo, possibly with some extra options still: + \protected\def\sphinxguilabel#1{\foo{#1}} + \protected\def\sphinxmenuselection#1{\foo[box-shadow-TeXcolor=gray]{#1}} + +Boxes rendered with ``\foo`` obey as the ones using directly ``\sphinxbox`` +the current configuration as set possibly mid-way in document via +``\sphinxboxsetup`` (from a :dudir:`raw` LaTeX mark-up), the only difference +is that they have an initial additional set of default extras. + +In the above examples, you can probably use ``\renewcommand`` syntax if you +prefer it to ``\protected\def`` (with ``[1]`` in place of ``#1`` then). + + +Environments +~~~~~~~~~~~~ + +- A :dudir:`figure` may have an optional legend with arbitrary body + elements: they are rendered in a ``sphinxlegend`` environment. The default + definition issues ``\small``, and ends with ``\par``. + + .. versionadded:: 1.5.6 + Formerly, the ``\small`` was hardcoded in LaTeX writer and the ending + ``\par`` was lacking. + +- Environments associated with admonitions: + + - ``sphinxnote``, + - ``sphinxhint``, + - ``sphinximportant``, + - ``sphinxtip``, + - ``sphinxwarning``, + - ``sphinxcaution``, + - ``sphinxattention``, + - ``sphinxdanger``, + - ``sphinxerror``. + + They may be ``\renewenvironment`` + 'd individually, and must then be defined with one argument (it is the heading + of the notice, for example ``Warning:`` for :dudir:`warning` directive, if + English is the document language). Their default definitions use either the + *sphinxheavybox* (for the last 5 ones) or the *sphinxlightbox* + environments, configured to use the parameters (colors, border thickness) + specific to each type, which can be set via ``'sphinxsetup'`` string. + + .. versionchanged:: 1.5 + Use of public environment names, separate customizability of the + parameters, such as ``noteBorderColor``, ``noteborder``, + ``warningBgColor``, ``warningBorderColor``, ``warningborder``, ... + +- Environment for the :rst:dir:`seealso` directive: ``sphinxseealso``. + It takes one argument which will be the localized string ``See also`` + followed with a colon. + + .. versionadded:: 6.1.0 + .. versionchanged:: 6.2.0 + + Colon made part of the mark-up rather than being inserted by the + environment for coherence with how admonitions are handled generally. + +- The contents_ directive (with ``:local:`` option) and the + :dudir:`topic` directive are implemented by environment ``sphinxShadowBox``. + + .. versionadded:: 1.4.2 + Former code refactored into an environment allowing page breaks. + + .. versionchanged:: 1.5 + Options ``shadowsep``, ``shadowsize``, ``shadowrule``. + +- The literal blocks (via ``::`` or :rst:dir:`code-block`), are + implemented using ``sphinxVerbatim`` environment which is a wrapper of + ``Verbatim`` environment from package ``fancyvrb.sty``. It adds the handling + of the top caption and the wrapping of long lines, and a frame which allows + page breaks. Inside tables the used + environment is ``sphinxVerbatimintable`` (it does not draw a frame, but + allows a caption). + + .. versionchanged:: 1.5 + ``Verbatim`` keeps exact same meaning as in ``fancyvrb.sty`` (also + under the name ``OriginalVerbatim``); ``sphinxVerbatimintable`` is used + inside tables. + + .. versionadded:: 1.5 + Options ``verbatimwithframe``, ``verbatimwrapslines``, + ``verbatimsep``, ``verbatimborder``. + + .. versionadded:: 1.6.6 + Support for ``:emphasize-lines:`` option + + .. versionadded:: 1.6.6 + Easier customizability of the formatting via exposed to user LaTeX macros + such as ``\sphinxVerbatimHighlightLine``. + +- The bibliography uses ``sphinxthebibliography`` and the Python Module index + as well as the general index both use ``sphinxtheindex``; these environments + are wrappers of the ``thebibliography`` and respectively ``theindex`` + environments as provided by the document class (or packages). + + .. versionchanged:: 1.5 + Formerly, the original environments were modified by Sphinx. + +Miscellany +~~~~~~~~~~ + +- Every text paragraph in document body starts with ``\sphinxAtStartPar``. + Currently, this is used to insert a zero width horizontal skip which + is a trick to allow TeX hyphenation of the first word of a paragraph + in a narrow context (like a table cell). For ``'lualatex'`` which + does not need the trick, the ``\sphinxAtStartPar`` does nothing. + + .. versionadded:: 3.5.0 + +- The section, subsection, ... headings are set using *titlesec*'s + ``\titleformat`` command. + +- For the ``'manual'`` docclass, the chapter headings can be customized using + *fncychap*'s commands ``\ChNameVar``, ``\ChNumVar``, ``\ChTitleVar``. File + :file:`sphinx.sty` has custom re-definitions in case of *fncychap* + option ``Bjarne``. + + .. versionchanged:: 1.5 + Formerly, use of *fncychap* with other styles than ``Bjarne`` was + dysfunctional. + +.. _latexcontainer: + +- Docutils :dudir:`container` directives are supported in LaTeX output: to + let a container class with name ``foo`` influence the final PDF via LaTeX, + it is only needed to define in the preamble an environment + ``sphinxclassfoo``. A simple example would be: + + .. code-block:: latex + + \newenvironment{sphinxclassred}{\color{red}}{} + + Currently the class names must contain only ascii characters and avoid + characters special to LaTeX such as ``\``. + + .. versionadded:: 4.1.0 + +.. 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 + 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). + + .. versionadded:: 1.6 + currently all template variables are unstable and undocumented. + +.. raw:: latex + + \endgroup diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 0000000..e2bd7ea --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,32 @@ +@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=python ../sphinx/cmd/build.py
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.https://www.sphinx-doc.org/
+ exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
diff --git a/doc/man/index.rst b/doc/man/index.rst new file mode 100644 index 0000000..1468022 --- /dev/null +++ b/doc/man/index.rst @@ -0,0 +1,22 @@ +Command-Line Tools +================== + +These are the applications provided as part of Sphinx. + +Core Applications +----------------- + +.. toctree:: + :maxdepth: 3 + + sphinx-quickstart + sphinx-build + +Additional Applications +----------------------- + +.. toctree:: + :maxdepth: 3 + + sphinx-apidoc + sphinx-autogen diff --git a/doc/man/sphinx-apidoc.rst b/doc/man/sphinx-apidoc.rst new file mode 100644 index 0000000..efc8230 --- /dev/null +++ b/doc/man/sphinx-apidoc.rst @@ -0,0 +1,171 @@ +sphinx-apidoc +============= + +Synopsis +-------- + +**sphinx-apidoc** [*OPTIONS*] -o <*OUTPUT_PATH*> <*MODULE_PATH*> +[*EXCLUDE_PATTERN* ...] + +Description +----------- + +:program:`sphinx-apidoc` is a tool for automatic generation of Sphinx sources +that, using the :py:mod:`~sphinx.ext.autodoc` extension, document a whole +package in the style of other automatic API documentation tools. + +*MODULE_PATH* is the path to a Python package to document, and *OUTPUT_PATH* is +the directory where the generated sources are placed. Any *EXCLUDE_PATTERN*\s +given are `fnmatch-style`_ file and/or directory patterns that will be excluded +from generation. + +.. _fnmatch-style: https://docs.python.org/3/library/fnmatch.html + +.. warning:: + + ``sphinx-apidoc`` generates source files that use :mod:`sphinx.ext.autodoc` + to document all found modules. 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. + +Options +------- + +.. program:: sphinx-apidoc + +.. option:: -o <OUTPUT_PATH> + + Directory to place the output files. If it does not exist, it is created. + +.. option:: -q + + Do not output anything on standard output, only write warnings and errors to + standard error. + +.. option:: -f, --force + + Force overwriting of any existing generated files. + +.. option:: -l, --follow-links + + Follow symbolic links. Defaults to ``False``. + +.. option:: -n, --dry-run + + Do not create any files. + +.. option:: -s <suffix> + + Suffix for the source files generated. Defaults to ``rst``. + +.. option:: -d <MAXDEPTH> + + Maximum depth for the generated table of contents file. Defaults to ``4``. + +.. option:: --tocfile + + Filename for a table of contents file. Defaults to ``modules``. + +.. option:: -T, --no-toc + + Do not create a table of contents file. Ignored when :option:`--full` is + provided. + +.. option:: -F, --full + + Generate a full Sphinx project (``conf.py``, ``Makefile`` etc.) using + the same mechanism as :program:`sphinx-quickstart`. + +.. option:: -e, --separate + + Put documentation for each module on its own page. + + .. versionadded:: 1.2 + +.. option:: -E, --no-headings + + Do not create headings for the modules/packages. This is useful, for + example, when docstrings already contain headings. + +.. option:: -P, --private + + Include "_private" modules. + + .. versionadded:: 1.2 + +.. option:: --implicit-namespaces + + By default sphinx-apidoc processes sys.path searching for modules only. + Python 3.3 introduced :pep:`420` implicit namespaces that allow module path + structures such as ``foo/bar/module.py`` or ``foo/bar/baz/__init__.py`` + (notice that ``bar`` and ``foo`` are namespaces, not modules). + + Interpret paths recursively according to PEP-0420. + +.. option:: -M, --module-first + + Put module documentation before submodule documentation. + +These options are used when :option:`--full` is specified: + +.. option:: -a + + Append module_path to sys.path. + +.. option:: -H <project> + + Sets the project name to put in generated files (see :confval:`project`). + +.. option:: -A <author> + + Sets the author name(s) to put in generated files (see + :confval:`copyright`). + +.. option:: -V <version> + + Sets the project version to put in generated files (see :confval:`version`). + +.. option:: -R <release> + + Sets the project release to put in generated files (see :confval:`release`). + +.. rubric:: Project templating + +.. versionadded:: 2.2 + Project templating options for sphinx-apidoc + +.. option:: -t, --templatedir=TEMPLATEDIR + + Template directory for template files. You can modify the templates of + 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`` + + In detail, please refer the system template files Sphinx provides. + (``sphinx/templates/apidoc`` and ``sphinx/templates/quickstart``) + +Environment +----------- + +.. envvar:: SPHINX_APIDOC_OPTIONS + + A comma-separated list of option to append to generated ``automodule`` + directives. Defaults to ``members,undoc-members,show-inheritance``. + +See also +-------- + +:manpage:`sphinx-build(1)`, :manpage:`sphinx-autogen(1)` + +.. _fnmatch: https://docs.python.org/3/library/fnmatch.html diff --git a/doc/man/sphinx-autogen.rst b/doc/man/sphinx-autogen.rst new file mode 100644 index 0000000..caeb44b --- /dev/null +++ b/doc/man/sphinx-autogen.rst @@ -0,0 +1,97 @@ +sphinx-autogen +============== + +Synopsis +-------- + +**sphinx-autogen** [*options*] <sourcefile> ... + +Description +----------- + +:program:`sphinx-autogen` is a tool for automatic generation of Sphinx sources +that, using the :py:mod:`~sphinx.ext.autodoc` extension, document items included +in :rst:dir:`autosummary` listing(s). + +*sourcefile* is the path to one or more reStructuredText documents containing +:rst:dir:`autosummary` entries with the ``:toctree::`` option set. *sourcefile* +can be an :py:mod:`fnmatch`-style pattern. + +Options +------- + +.. program:: sphinx-autogen + +.. option:: -o <outputdir> + + Directory to place the output file. If it does not exist, it is created. + Defaults to the value passed to the ``:toctree:`` option. + +.. option:: -s <suffix>, --suffix <suffix> + + Default suffix to use for generated files. Defaults to ``rst``. + +.. option:: -t <templates>, --templates <templates> + + Custom template directory. Defaults to ``None``. + +.. option:: -i, --imported-members + + Document imported members. + +.. option:: -a, --respect-module-all + + Document exactly the members in a module's ``__all__`` attribute. + +Example +------- + +Given the following directory structure:: + + docs + ├── index.rst + └── ... + foobar + ├── foo + │ └── __init__.py + └── bar + ├── __init__.py + └── baz + └── __init__.py + +and assuming ``docs/index.rst`` contained the following: + +.. code-block:: rst + + Modules + ======= + + .. autosummary:: + :toctree: modules + + foobar.foo + foobar.bar + foobar.bar.baz + +If you run the following: + +.. code-block:: console + + $ PYTHONPATH=. sphinx-autogen docs/index.rst + +then the following stub files will be created in ``docs``:: + + docs + ├── index.rst + └── modules + ├── foobar.bar.rst + ├── foobar.bar.baz.rst + └── foobar.foo.rst + +and each of those files will contain a :py:mod:`~sphinx.ext.autodoc` directive +and some other information. + +See also +-------- + +:manpage:`sphinx-build(1)`, :manpage:`sphinx-apidoc(1)` diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst new file mode 100644 index 0000000..a1fb9be --- /dev/null +++ b/doc/man/sphinx-build.rst @@ -0,0 +1,355 @@ +sphinx-build +============ + +Synopsis +-------- + +**sphinx-build** [*options*] <*sourcedir*> <*outputdir*> [*filenames* ...] + +Description +----------- + +:program:`sphinx-build` generates documentation from the files in +``<sourcedir>`` and places it in the ``<outputdir>``. + +:program:`sphinx-build` looks for ``<sourcedir>/conf.py`` for the configuration +settings. :manpage:`sphinx-quickstart(1)` may be used to generate template +files, including ``conf.py``. + +:program:`sphinx-build` can create documentation in different formats. A +format is selected by specifying the builder name on the command line; it +defaults to HTML. Builders can also perform other tasks related to +documentation processing. For a list of available builders, refer to +:option:`sphinx-build -b`. + +By default, everything that is outdated is built. Output only for selected +files can be built by specifying individual filenames. + +Options +------- + +.. program:: sphinx-build + +.. option:: -b buildername + + The most important option: it selects a builder. The most common builders + are: + + **html** + Build HTML pages. This is the default builder. + + **dirhtml** + Build HTML pages, but with a single directory per document. Makes for + prettier URLs (no ``.html``) if served from a webserver. + + **singlehtml** + Build a single HTML with the whole content. + + **htmlhelp**, **qthelp**, **devhelp**, **epub** + Build HTML files with additional information for building a documentation + collection in one of these formats. + + **applehelp** + Build an Apple Help Book. Requires :program:`hiutil` and + :program:`codesign`, which are not Open Source and presently only + available on Mac OS X 10.6 and higher. + + **latex** + Build LaTeX sources that can be compiled to a PDF document using + :program:`pdflatex`. + + **man** + Build manual pages in groff format for UNIX systems. + + **texinfo** + Build Texinfo files that can be processed into Info files using + :program:`makeinfo`. + + **text** + Build plain text files. + + **gettext** + Build gettext-style message catalogs (``.pot`` files). + + **doctest** + Run all doctests in the documentation, if the :mod:`~sphinx.ext.doctest` + extension is enabled. + + **linkcheck** + Check the integrity of all external links. + + **xml** + Build Docutils-native XML files. + + **pseudoxml** + Build compact pretty-printed "pseudo-XML" files displaying the + internal structure of the intermediate document trees. + + See :doc:`/usage/builders/index` for a list of all builders shipped with + Sphinx. Extensions can add their own builders. + +.. _make_mode: + +.. option:: -M buildername + + Alternative to :option:`-b`. Uses the Sphinx :program:`make_mode` module, + which provides the same build functionality as a default :ref:`Makefile or + Make.bat <makefile_options>`. In addition to all Sphinx + :doc:`/usage/builders/index`, the following build pipelines are available: + + **latexpdf** + Build LaTeX files and run them through :program:`pdflatex`, or as per + :confval:`latex_engine` setting. + If :confval:`language` is set to ``'ja'``, will use automatically + the :program:`platex/dvipdfmx` latex to PDF pipeline. + + **info** + Build Texinfo files and run them through :program:`makeinfo`. + + .. important:: + Sphinx only recognizes the ``-M`` option if it is placed first. + + .. versionadded:: 1.2.1 + +.. option:: -a + + If given, always write all output files. The default is to only write output + files for new and changed source files. (This may not apply to all + builders.) + +.. option:: -E + + Don't use a saved :term:`environment` (the structure caching all + cross-references), but rebuild it completely. The default is to only read + and parse source files that are new or have changed since the last run. + +.. option:: -t tag + + Define the tag *tag*. This is relevant for :rst:dir:`only` directives that + only include their content if this tag is set. + + .. versionadded:: 0.6 + +.. option:: -d path + + Since Sphinx has to read and parse all source files before it can write an + output file, the parsed source files are cached as "doctree pickles". + Normally, these files are put in a directory called :file:`.doctrees` under + the build directory; with this option you can select a different cache + directory (the doctrees can be shared between all builders). + +.. option:: -j N, --jobs N + + 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*. + + .. versionadded:: 1.2 + This option should be considered *experimental*. + + .. versionchanged:: 1.7 + Support ``auto`` argument. + + .. versionchanged:: 6.2 + Add ``--jobs`` long option. + +.. option:: -c path + + Don't look for the :file:`conf.py` in the source directory, but use the given + configuration directory instead. Note that various other files and paths + given by configuration values are expected to be relative to the + configuration directory, so they will have to be present at this location + too. + + .. versionadded:: 0.3 + +.. option:: -C + + Don't look for a configuration file; only take options via the ``-D`` option. + + .. versionadded:: 0.5 + +.. option:: -D setting=value + + Override a configuration value set in the :file:`conf.py` file. The value + must be a number, string, list or dictionary value. + + For lists, you can separate elements with a comma like this: ``-D + html_theme_path=path1,path2``. + + For dictionary values, supply the setting name and key like this: + ``-D latex_elements.docclass=scrartcl``. + + For boolean values, use ``0`` or ``1`` as the value. + + .. versionchanged:: 0.6 + The value can now be a dictionary value. + + .. versionchanged:: 1.3 + The value can now also be a list value. + +.. option:: -A name=value + + Make the *name* assigned to *value* in the HTML templates. + + .. versionadded:: 0.5 + +.. option:: -n + + Run in nit-picky 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". + +.. option:: -N, --no-color + + Do not emit colored output. + + .. versionchanged:: 1.6 + Add ``--no-color`` long option. + +.. option:: --color + + Emit colored output. Auto-detected by default. + + .. versionadded:: 1.6 + +.. option:: -v + + Increase verbosity (loglevel). This option can be given up to three times + to get more debug logging output. It implies :option:`-T`. + + .. versionadded:: 1.2 + +.. option:: -q + + Do not output anything on standard output, only write warnings and errors to + standard error. + +.. option:: -Q + + Do not output anything on standard output, also suppress warnings. Only + errors are written to standard error. + +.. option:: -w file + + Write warnings (and errors) to the given file, in addition to standard error. + +.. option:: -W + + Turn warnings into errors. This means that the build stops at the first + warning and ``sphinx-build`` exits with exit status 1. + +.. option:: --keep-going + + With -W option, keep going processing when getting warnings to the end + of build, and ``sphinx-build`` exits with exit status 1. + + .. versionadded:: 1.8 + +.. option:: -T + + Display the full traceback when an unhandled exception occurs. Otherwise, + only a summary is displayed and the traceback information is saved to a file + for further analysis. + + .. versionadded:: 1.2 + +.. option:: -P + + (Useful for debugging only.) Run the Python debugger, :mod:`pdb`, if an + unhandled exception occurs while building. + +.. option:: -h, --help, --version + + Display usage summary or Sphinx version. + + .. versionadded:: 1.2 + +You can also give one or more filenames on the command line after the source +and build directories. Sphinx will then try to build only these output files +(and their dependencies). + +Environment Variables +--------------------- + +The :program:`sphinx-build` refers following environment variables: + +.. describe:: MAKE + + A path to make command. A command name is also allowed. + :program:`sphinx-build` uses it to invoke sub-build process on make-mode. + +.. _makefile_options: + +.. rubric:: Makefile Options + +The :file:`Makefile` and :file:`make.bat` files created by +:program:`sphinx-quickstart` usually run :program:`sphinx-build` only with the +:option:`-b` and :option:`-d` options. However, they support the following +variables to customize behavior: + +.. describe:: PAPER + + This sets the ``'papersize'`` key of :confval:`latex_elements`: + i.e. ``PAPER=a4`` sets it to ``'a4paper'`` and ``PAPER=letter`` to + ``'letterpaper'``. + + .. note:: + + Usage of this environment variable got broken at Sphinx 1.5 as + ``a4`` or ``letter`` ended up as option to LaTeX document in + place of the needed ``a4paper``, resp. ``letterpaper``. Fixed at + 1.7.7. + +.. describe:: SPHINXBUILD + + The command to use instead of ``sphinx-build``. + +.. describe:: BUILDDIR + + The build directory to use instead of the one chosen in + :program:`sphinx-quickstart`. + +.. describe:: SPHINXOPTS + + Additional options for :program:`sphinx-build`. These options can + also be set via the shortcut variable **O** (capital 'o'). + +.. describe:: NO_COLOR + + When set (regardless of value), :program:`sphinx-build` will not use color + in terminal output. ``NO_COLOR`` takes precedence over ``FORCE_COLOR``. See + `no-color.org <https://no-color.org/>`__ for other libraries supporting this + community standard. + + .. versionadded:: 4.5.0 + +.. describe:: FORCE_COLOR + + When set (regardless of value), :program:`sphinx-build` will use color in + terminal output. ``NO_COLOR`` takes precedence over ``FORCE_COLOR``. + + .. versionadded:: 4.5.0 + +.. _when-deprecation-warnings-are-displayed: + +Deprecation Warnings +-------------------- + +If any deprecation warning like ``RemovedInSphinxXXXWarning`` are displayed +when building a user's document, some Sphinx extension is using deprecated +features. In that case, please report it to author of the extension. + +To disable the deprecation warnings, please set ``PYTHONWARNINGS=`` environment +variable to your environment. For example: + +* ``PYTHONWARNINGS= make html`` (Linux/Mac) +* ``export PYTHONWARNINGS=`` and do ``make html`` (Linux/Mac) +* ``set PYTHONWARNINGS=`` and do ``make html`` (Windows) +* modify your Makefile/make.bat and set the environment variable + +See also +-------- + +:manpage:`sphinx-quickstart(1)` diff --git a/doc/man/sphinx-quickstart.rst b/doc/man/sphinx-quickstart.rst new file mode 100644 index 0000000..d050a29 --- /dev/null +++ b/doc/man/sphinx-quickstart.rst @@ -0,0 +1,169 @@ +sphinx-quickstart +================= + +Synopsis +-------- + +**sphinx-quickstart** + +Description +----------- + +:program:`sphinx-quickstart` is an interactive tool that asks some questions +about your project and then generates a complete documentation directory and +sample Makefile to be used with :manpage:`sphinx-build(1)`. + +Options +------- + +.. program:: sphinx-quickstart + +.. option:: -q, --quiet + + Quiet mode that skips the interactive wizard for specifying options. + This option requires `-p`, `-a` and `-v` options. + +.. option:: -h, --help, --version + + Display usage summary or Sphinx version. + +.. rubric:: Structure Options + +.. option:: --sep + + If specified, separate source and build directories. + +.. option:: --no-sep + + If specified, create build directory under source directory. + +.. option:: --dot=DOT + + Inside the root directory, two more directories will be created; + "_templates" for custom HTML templates and "_static" for custom stylesheets + and other static files. You can enter another prefix (such as ".") to + replace the underscore. + +.. rubric:: Project Basic Options + +.. option:: -p PROJECT, --project=PROJECT + + Project name will be set. (see :confval:`project`). + +.. option:: -a AUTHOR, --author=AUTHOR + + Author names. (see :confval:`copyright`). + +.. option:: -v VERSION + + Version of project. (see :confval:`version`). + +.. option:: -r RELEASE, --release=RELEASE + + Release of project. (see :confval:`release`). + +.. option:: -l LANGUAGE, --language=LANGUAGE + + Document language. (see :confval:`language`). + +.. option:: --suffix=SUFFIX + + Source file suffix. (see :confval:`source_suffix`). + +.. option:: --master=MASTER + + Master document name. (see :confval:`root_doc`). + +.. rubric:: Extension Options + +.. option:: --ext-autodoc + + Enable :py:mod:`sphinx.ext.autodoc` extension. + +.. option:: --ext-doctest + + Enable `sphinx.ext.doctest` extension. + +.. option:: --ext-intersphinx + + Enable `sphinx.ext.intersphinx` extension. + +.. option:: --ext-todo + + Enable `sphinx.ext.todo` extension. + +.. option:: --ext-coverage + + Enable `sphinx.ext.coverage` extension. + +.. option:: --ext-imgmath + + Enable `sphinx.ext.imgmath` extension. + +.. option:: --ext-mathjax + + Enable `sphinx.ext.mathjax` extension. + +.. option:: --ext-ifconfig + + Enable `sphinx.ext.ifconfig` extension. + +.. option:: --ext-viewcode + + Enable `sphinx.ext.viewcode` extension. + +.. option:: --ext-githubpages + + Enable `sphinx.ext.githubpages` extension. + +.. option:: --extensions=EXTENSIONS + + Enable arbitrary extensions. + +.. rubric:: Makefile and Batchfile Creation Options + +.. option:: --use-make-mode (-m), --no-use-make-mode (-M) + + :file:`Makefile/make.bat` uses (or doesn't use) :ref:`make-mode <make_mode>`. + Default is ``use``, which generates a more concise :file:`Makefile/make.bat`. + + .. versionchanged:: 1.5 + make-mode is default. + +.. option:: --makefile, --no-makefile + + Create (or not create) makefile. + +.. option:: --batchfile, --no-batchfile + + Create (or not create) batchfile + +.. rubric:: Project templating + +.. versionadded:: 1.5 + Project templating options for sphinx-quickstart + +.. option:: -t, --templatedir=TEMPLATEDIR + + Template directory for template files. You can modify the templates of + 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`` + + In detail, please refer the system template files Sphinx provides. + (``sphinx/templates/quickstart``) + +.. option:: -d NAME=VALUE + + Define a template variable + +See also +-------- + +:manpage:`sphinx-build(1)` diff --git a/doc/support.rst b/doc/support.rst new file mode 100644 index 0000000..b7c6f01 --- /dev/null +++ b/doc/support.rst @@ -0,0 +1,20 @@ +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_. + +.. _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 + +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. + +.. _tutorial: http://matplotlib.sourceforge.net/sampledoc/ + +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 new file mode 100644 index 0000000..b47673d --- /dev/null +++ b/doc/tutorial/automatic-doc-generation.rst @@ -0,0 +1,165 @@ +Automatic documentation generation from code +============================================ + +In the :ref:`previous section <tutorial-describing-objects>` of the tutorial +you manually documented a Python function in Sphinx. However, the description +was out of sync with the code itself, since the function signature was not +the same. Besides, it would be nice to reuse :pep:`Python docstrings +<257#what-is-a-docstring>` in the documentation, rather than having to write +the information in two places. + +Fortunately, :doc:`the autodoc extension </usage/extensions/autodoc>` provides this +functionality. + +Reusing signatures and docstrings with autodoc +---------------------------------------------- + +To use autodoc, first add it to the list of enabled extensions: + +.. code-block:: python + :caption: docs/source/conf.py + :emphasize-lines: 4 + + extensions = [ + 'sphinx.ext.duration', + 'sphinx.ext.doctest', + 'sphinx.ext.autodoc', + ] + +Next, move the content of the ``.. py:function`` directive to the function +docstring in the original Python file, as follows: + +.. code-block:: python + :caption: lumache.py + :emphasize-lines: 2-11 + + def get_random_ingredients(kind=None): + """ + Return a list of random ingredients as strings. + + :param kind: Optional "kind" of ingredients. + :type kind: list[str] or None + :raise lumache.InvalidKindError: If the kind is invalid. + :return: The ingredients list. + :rtype: list[str] + + """ + return ["shells", "gorgonzola", "parsley"] + +Finally, replace the ``.. py:function`` directive from the Sphinx documentation +with :rst:dir:`autofunction`: + +.. code-block:: rst + :caption: docs/source/usage.rst + :emphasize-lines: 3 + + you can use the ``lumache.get_random_ingredients()`` function: + + .. autofunction:: lumache.get_random_ingredients + +If you now build the HTML documentation, the output will be the same! +With the advantage that it is generated from the code itself. +Sphinx took the reStructuredText from the docstring and included it, +also generating proper cross-references. + +You can also autogenerate documentation from other objects. For example, add +the code for the ``InvalidKindError`` exception: + +.. code-block:: python + :caption: lumache.py + + class InvalidKindError(Exception): + """Raised if the kind is invalid.""" + pass + +And replace the ``.. py:exception`` directive with :rst:dir:`autoexception` +as follows: + +.. code-block:: rst + :caption: docs/source/usage.rst + :emphasize-lines: 4 + + or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients` + will raise an exception. + + .. autoexception:: lumache.InvalidKindError + +And again, after running ``make html``, the output will be the same as before. + +Generating comprehensive API references +--------------------------------------- + +While using ``sphinx.ext.autodoc`` makes keeping the code and the documentation +in sync much easier, it still requires you to write an ``auto*`` directive +for every object you want to document. Sphinx provides yet another level of +automation: the :doc:`autosummary </usage/extensions/autosummary>` extension. + +The :rst:dir:`autosummary` directive generates documents that contain all the +necessary ``autodoc`` directives. To use it, first enable the autosummary +extension: + +.. code-block:: python + :caption: docs/source/conf.py + :emphasize-lines: 5 + + extensions = [ + 'sphinx.ext.duration', + 'sphinx.ext.doctest', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + ] + +Next, create a new ``api.rst`` file with these contents: + +.. code-block:: rst + :caption: docs/source/api.rst + + API + === + + .. autosummary:: + :toctree: generated + + lumache + +Remember to include the new document in the root toctree: + +.. code-block:: rst + :caption: docs/source/index.rst + :emphasize-lines: 7 + + Contents + -------- + + .. toctree:: + + usage + api + +Finally, after you build the HTML documentation running ``make html``, it will +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.rst`` and containing a summary of members of the module, + in this case one function and one exception. + +.. figure:: /_static/tutorial/lumache-autosummary.png + :width: 80% + :align: center + :alt: Summary page created by autosummary + + Summary page created by autosummary + +Each of the links in the summary page will take you to the places where you +originally used the corresponding ``autodoc`` directive, in this case in the +``usage.rst`` document. + +.. note:: + + The generated files are based on `Jinja2 + templates <https://jinja2docs.readthedocs.io/>`_ that + :ref:`can be customized <autosummary-customizing-templates>`, + but that is out of scope for this tutorial. diff --git a/doc/tutorial/deploying.rst b/doc/tutorial/deploying.rst new file mode 100644 index 0000000..e16abdf --- /dev/null +++ b/doc/tutorial/deploying.rst @@ -0,0 +1,281 @@ +Appendix: Deploying a Sphinx project online +=========================================== + +When you are ready to show your documentation project to the world, there are +many options available to do so. Since the HTML generated by Sphinx is static, +you can decouple the process of building your HTML documentation from hosting +such files in the platform of your choice. You will not need a sophisticated +server running Python: virtually every web hosting service will suffice. + +Therefore, the challenge is less how or where to serve the static HTML, but +rather how to pick a workflow that automatically updates the deployed +documentation every time there is a change in the source files. + +The following sections describe some of the available options to deploy +your online documentation, and give some background information. If you want +to go directly to the practical part, you can skip to :ref:`publishing-sources`. + +Sphinx-friendly deployment options +---------------------------------- + +There are several possible options you have to host your Sphinx documentation. +Some of them are: + +**Read the Docs** + `Read the Docs`_ is an online service specialized in hosting technical + documentation written in Sphinx, as well as MkDocs. They have a + number of extra features, such as versioned documentation, traffic and + search analytics, custom domains, user-defined redirects, and more. + +**GitHub Pages** + `GitHub Pages`_ is a simple static web hosting tightly integrated with + `GitHub`_: static HTML is served from one of the branches of a project, + and usually sources are stored in another branch so that the output + can be updated every time the sources change (for example using `GitHub + Actions`_). It is free to use and supports custom domains. + +**GitLab Pages** + `GitLab Pages`_ is a similar concept to GitHub Pages, integrated with + `GitLab`_ and usually automated with `GitLab CI`_ instead. + +**Netlify** + `Netlify`_ is a sophisticated hosting for static sites enhanced by + client-side web technologies like JavaScript (so-called `"Jamstack"`_). + They offer support for headless content management systems and + serverless computing. + +**Your own server** + You can always use your own web server to host Sphinx HTML documentation. + It is the option that gives more flexibility, but also more complexity. + +All these options have zero cost, with the option of paying for extra features. + +.. _Read the Docs: https://readthedocs.org/ +.. _GitHub Pages: https://pages.github.com/ +.. _GitHub: https://github.com/ +.. _GitHub Actions: https://github.com/features/actions +.. _GitLab Pages: https://about.gitlab.com/stages-devops-lifecycle/pages/ +.. _GitLab: https://gitlab.com/ +.. _GitLab CI: https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/ +.. _Netlify: https://www.netlify.com/ +.. _"Jamstack": https://jamstack.org/ + +Embracing the "Docs as Code" philosophy +--------------------------------------- + +The free offerings of most of the options listed above require your +documentation sources to be publicly available. Moreover, these services +expect you to use a `Version Control System`_, a technology that tracks the +evolution of a collection of files as a series of snapshots ("commits"). +The practice of writing documentation in plain text files with the same tools +as the ones used for software development is commonly known as `"Docs as Code"`_. + +The most popular Version Control System nowadays is Git_, a free and open +source tool that is the backbone of services like GitHub and GitLab. +Since both Read the Docs and Netlify have integrations with GitHub and GitLab, +and both GitHub and GitLab have an integrated Pages product, the most effective +way of automatically build your documentation online is to upload your sources +to either of these Git hosting services. + +.. _Version Control System: https://en.wikipedia.org/wiki/Version_control +.. _"Docs as Code": https://www.writethedocs.org/guide/docs-as-code/ +.. _Git: https://git-scm.com/ + +.. _publishing-sources: + +Publishing your documentation sources +------------------------------------- + +GitHub +~~~~~~ + +The quickest way to upload an existing project to GitHub is to: + +1. `Sign up for a GitHub account <https://github.com/signup>`_. +2. `Create a new repository <https://github.com/new>`_. +3. Open `the "Upload files" page`_ of your new repository. +4. Select the files on your operating system file browser (in your case + ``README.rst``, ``lumache.py``, the makefiles under the ``docs`` directory, + and everything under ``docs/source``) and drag them to the GitHub interface + to upload them all. +5. Click on the :guilabel:`Commit changes` button. + +.. _the "Upload files" page: https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository + +.. note:: + + Make sure you don't upload the ``docs/build`` directory, as it contains the + output generated by Sphinx and it will change every time you change the + sources, complicating your workflow. + +These steps do not require access to the command line or installing any +additional software. To learn more, you can: + +- Follow `this interactive GitHub course`_ to learn more about how the GitHub + interface works. +- Read `this quickstart tutorial`_ to install extra software on your machine + and have more flexibility. You can either use the Git command line, or the + GitHub Desktop application. + +.. _this interactive GitHub course: https://lab.github.com/githubtraining/introduction-to-github +.. _this quickstart tutorial: https://docs.github.com/en/get-started/quickstart + +GitLab +~~~~~~ + +Similarly to GitHub, the fastest way to upload your project to GitLab is +using the web interface: + +1. `Sign up for a GitLab account <https://gitlab.com/users/sign_up>`_. +2. `Create a new blank project <https://gitlab.com/projects/new>`_. +3. Upload the project files (in your case ``README.rst``, ``lumache.py``, the + makefiles under the ``docs`` directory, and everything under + ``docs/source``) one by one using the :guilabel:`Upload File` button [#f1]_. + +Again, these steps do not require additional software on your computer. To +learn more, you can: + +- Follow `this tutorial`_ to install Git on your machine. +- Browse the `GitLab User documentation`_ to understand the possibilities of + the platform. + +.. _this tutorial: https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html +.. _GitLab User documentation: https://docs.gitlab.com/ee/user/index.html + +.. note:: + + Make sure you don't upload the ``docs/build`` directory, as it contains the + output generated by Sphinx and it will change every time you change the + sources, complicating your workflow. + +.. [#f1] At the time of writing, `uploading whole directories to GitLab using + only the web + interface <https://gitlab.com/gitlab-org/gitlab/-/issues/228490>`_ is + not yet implemented. + +Publishing your HTML documentation +---------------------------------- + +Read the Docs +~~~~~~~~~~~~~ + +`Read the Docs`_ offers integration with both GitHub and GitLab. The quickest +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`. +If you choose GitLab instead, the process is similar. + +GitHub Pages +~~~~~~~~~~~~ + +`GitHub Pages`_ requires you to :ref:`publish your +sources <publishing-sources>` on `GitHub`_. After that, you will need an +automated process that performs the ``make html`` step every time the sources +change. That can be achieved using `GitHub Actions`_. + +After you have published your sources on GitHub, create a file named +``.github/workflows/sphinx.yml`` in your repository with the following +contents: + +.. code-block:: yaml + :caption: .github/workflows/ + + name: "Sphinx: Render docs" + + on: push + + jobs: + build: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - uses: actions/checkout@v3 + - name: Build HTML + uses: ammaraskar/sphinx-action@master + - name: Upload artifacts + uses: actions/upload-artifact@v3 + with: + name: html-docs + path: docs/build/html/ + - name: Deploy + uses: peaceiris/actions-gh-pages@v3 + if: github.ref == 'refs/heads/main' + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: docs/build/html + +This contains a GitHub Actions workflow with a single job of four steps: + +1. Checkout the code. +2. Build the HTML documentation using Sphinx. +3. Attach the HTML output the artifacts to the GitHub Actions job, for easier + inspection. +4. If the change happens on the default branch, take the contents of + ``docs/build/html`` and push it to the ``gh-pages`` branch. + +Next, you need to specify the dependencies for the ``make html`` step to be +successful. For that, create a file ``docs/requirements.txt`` and add the +following contents: + +.. code-block:: + :caption: docs/requirements.txt + + furo==2021.11.16 + +And finally, you are ready to `enable GitHub Pages on your repository`_. For +that, go to :guilabel:`Settings`, then :guilabel:`Pages` on the left sidebar, +select the ``gh-pages`` branch in the "Source" dropdown menu, and click +:guilabel:`Save`. After a few minutes, you should be able to see your HTML at +the designated URL. + +.. _enable GitHub Pages on your repository: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site + +GitLab Pages +~~~~~~~~~~~~ + +`GitLab Pages`_, on the other hand, requires you to :ref:`publish your +sources <publishing-sources>` on `GitLab`_. When you are ready, you can +automate the process of running ``make html`` using `GitLab CI`_. + +After you have published your sources on GitLab, create a file named +``.gitlab-ci.yml`` in your repository with these contents: + +.. code-block:: yaml + :caption: .gitlab-ci.yml + + stages: + - deploy + + pages: + stage: deploy + image: python:3.9-slim + before_script: + - apt-get update && apt-get install make --no-install-recommends -y + - python -m pip install sphinx furo + script: + - cd docs && make html + after_script: + - mv docs/build/html/ ./public/ + artifacts: + paths: + - public + rules: + - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH + +This contains a GitLab CI workflow with one job of several steps: + +1. Install the necessary dependencies. +2. Build the HTML documentation using Sphinx. +3. Move the output to a known artifacts location. + +.. note:: + You will need to `validate your account`_ by entering a payment method + (you will be charged a small amount that will then be reimbursed). + +.. _validate your account: https://about.gitlab.com/blog/2021/05/17/prevent-crypto-mining-abuse/#validating-an-account + +After that, if the pipeline is successful, you should be able to see your HTML +at the designated URL. diff --git a/doc/tutorial/describing-code.rst b/doc/tutorial/describing-code.rst new file mode 100644 index 0000000..24fea38 --- /dev/null +++ b/doc/tutorial/describing-code.rst @@ -0,0 +1,276 @@ +Describing code in Sphinx +========================= + +In the :doc:`previous sections of the tutorial </tutorial/index>` you can read +how to write narrative or prose documentation in Sphinx. In this section you +will describe code objects instead. + +Sphinx supports documenting code objects in several languages, namely Python, +C, C++, JavaScript, and reStructuredText. Each of them can be documented using +a series of directives and roles grouped by +:doc:`domain </usage/restructuredtext/domains>`. For the remainder of the +tutorial you will use the Python domain, but all the concepts seen in this +section apply for the other domains as well. + +.. _tutorial-describing-objects: + +Python +------ + +Documenting Python objects +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sphinx offers several roles and directives to document Python objects, +all grouped together in :ref:`the Python domain <python-domain>`. For example, +you can use the :rst:dir:`py:function` directive to document a Python function, +as follows: + +.. code-block:: rst + :caption: docs/source/usage.rst + + Creating recipes + ---------------- + + To retrieve a list of random ingredients, + you can use the ``lumache.get_random_ingredients()`` function: + + .. py:function:: lumache.get_random_ingredients(kind=None) + + Return a list of random ingredients as strings. + + :param kind: Optional "kind" of ingredients. + :type kind: list[str] or None + :return: The ingredients list. + :rtype: list[str] + +Which will render like this: + +.. figure:: /_static/tutorial/lumache-py-function.png + :width: 80% + :align: center + :alt: HTML result of documenting a Python function in Sphinx + + The rendered result of documenting a Python function in Sphinx + +Notice several things: + +- Sphinx parsed the argument of the ``.. py:function`` directive and + highlighted the module, the function name, and the parameters appropriately. +- The directive content includes a one-line description of the function, + as well as an :ref:`info field list <info-field-lists>` containing the function + parameter, its expected type, the return value, and the return type. + +.. note:: + + The ``py:`` prefix specifies the :term:`domain`. You may configure the + default domain so you can omit the prefix, either globally using the + :confval:`primary_domain` configuration, or use the + :rst:dir:`default-domain` directive to change it from the point it is called + until the end of the file. + For example, if you set it to ``py`` (the default), you can write + ``.. function::`` directly. + +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, +you can use :rst:role:`py:func` for that, as follows: + +.. code-block:: rst + :caption: docs/source/usage.rst + + The ``kind`` parameter should be either ``"meat"``, ``"fish"``, + or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients` + will raise an exception. + +When generating code documentation, Sphinx will generate a +cross-reference automatically just by using the name of the object, +without you having to explicitly use a role for that. For example, you +can describe the custom exception raised by the function using the +:rst:dir:`py:exception` directive: + +.. code-block:: rst + :caption: docs/source/usage.rst + + .. py:exception:: lumache.InvalidKindError + + Raised if the kind is invalid. + +Then, add this exception to the original description of the function: + +.. code-block:: rst + :caption: docs/source/usage.rst + :emphasize-lines: 7 + + .. py:function:: lumache.get_random_ingredients(kind=None) + + Return a list of random ingredients as strings. + + :param kind: Optional "kind" of ingredients. + :type kind: list[str] or None + :raise lumache.InvalidKindError: If the kind is invalid. + :return: The ingredients list. + :rtype: list[str] + +And finally, this is how the result would look: + +.. figure:: /_static/tutorial/lumache-py-function-full.png + :width: 80% + :align: center + :alt: HTML result of documenting a Python function in Sphinx + with cross-references + + HTML result of documenting a Python function in Sphinx with cross-references + +Beautiful, isn't it? + +Including doctests in your documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Since you are now describing code from a Python library, it will become useful +to keep both the documentation and the code as synchronized as possible. +One of the ways to do that in Sphinx is to include code snippets in the +documentation, called *doctests*, that are executed when the documentation is +built. + +To demonstrate doctests and other Sphinx features covered in this tutorial, +Sphinx will need to be able to import the code. To achieve that, write this +at the beginning of ``conf.py``: + +.. code-block:: python + :caption: docs/source/conf.py + :emphasize-lines: 3-5 + + # If extensions (or modules to document with autodoc) are in another directory, + # add these directories to sys.path here. + import pathlib + import sys + sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix()) + +.. note:: + + An alternative to changing the :py:data:`sys.path` variable is to create a + ``pyproject.toml`` file and make the code installable, + so it behaves like any other Python library. However, the ``sys.path`` + approach is simpler. + +Then, before adding doctests to your documentation, enable the +:doc:`doctest </usage/extensions/doctest>` extension in ``conf.py``: + +.. code-block:: python + :caption: docs/source/conf.py + :emphasize-lines: 3 + + extensions = [ + 'sphinx.ext.duration', + 'sphinx.ext.doctest', + ] + +Next, write a doctest block as follows: + +.. code-block:: rst + :caption: docs/source/usage.rst + + >>> import lumache + >>> lumache.get_random_ingredients() + ['shells', 'gorgonzola', 'parsley'] + +Doctests include the Python instructions to be run preceded by ``>>>``, +the standard Python interpreter prompt, as well as the expected output +of each instruction. This way, Sphinx can check whether the actual output +matches the expected one. + +To observe how a doctest failure looks like (rather than a code error as +above), let's write the return value incorrectly first. Therefore, add a +function ``get_random_ingredients`` like this: + +.. code-block:: python + :caption: lumache.py + + def get_random_ingredients(kind=None): + return ["eggs", "bacon", "spam"] + +You can now run ``make doctest`` to execute the doctests of your documentation. +Initially this will display an error, since the actual code does not behave +as specified: + +.. code-block:: console + + (.venv) $ make doctest + Running Sphinx v4.2.0 + loading pickled environment... done + ... + running tests... + + Document: usage + --------------- + ********************************************************************** + File "usage.rst", line 44, in default + Failed example: + lumache.get_random_ingredients() + Expected: + ['shells', 'gorgonzola', 'parsley'] + Got: + ['eggs', 'bacon', 'spam'] + ********************************************************************** + ... + make: *** [Makefile:20: doctest] Error 1 + +As you can see, doctest reports the expected and the actual results, +for easy examination. It is now time to fix the function: + +.. code-block:: python + :caption: lumache.py + :emphasize-lines: 2 + + def get_random_ingredients(kind=None): + return ["shells", "gorgonzola", "parsley"] + +And finally, ``make test`` reports success! + +For big projects though, this manual approach can become a bit tedious. +In the next section, you will see :doc:`how to automate the +process </tutorial/automatic-doc-generation>`. + +Other languages (C, C++, others) +-------------------------------- + +Documenting and cross-referencing objects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sphinx also supports documenting and cross-referencing objects written in +other programming languages. There are four additional built-in domains: +C, C++, JavaScript, and reStructuredText. Third-party extensions may +define domains for more languages, such as + +- `Fortran <https://sphinx-fortran.readthedocs.io>`_, +- `Julia <http://bastikr.github.io/sphinx-julia>`_, or +- `PHP <https://github.com/markstory/sphinxcontrib-phpdomain>`_. + +For example, to document a C++ type definition, you would use the built-in +:rst:dir:`cpp:type` directive, as follows: + +.. code-block:: rst + + .. cpp:type:: std::vector<int> CustomList + + A typedef-like declaration of a type. + +Which would give the following result: + +.. cpp:type:: std::vector<int> CustomList + + A typedef-like declaration of a type. + +All such directives then generate references that can be +cross-referenced by using the corresponding role. For example, to reference +the previous type definition, you can use the :rst:role:`cpp:type` role +as follows: + +.. code-block:: rst + + Cross reference to :cpp:type:`CustomList`. + +Which would produce a hyperlink to the previous definition: :cpp:type:`CustomList`. diff --git a/doc/tutorial/end.rst b/doc/tutorial/end.rst new file mode 100644 index 0000000..9f35b07 --- /dev/null +++ b/doc/tutorial/end.rst @@ -0,0 +1,6 @@ +Where to go from here +===================== + +This tutorial covered the very first steps to create a documentation project +with Sphinx. To continue learning more about Sphinx, check out the `rest of the +documentation <../contents.html>`__. diff --git a/doc/tutorial/first-steps.rst b/doc/tutorial/first-steps.rst new file mode 100644 index 0000000..fd5c631 --- /dev/null +++ b/doc/tutorial/first-steps.rst @@ -0,0 +1,92 @@ +First steps to document your project using Sphinx +================================================= + +Building your HTML documentation +-------------------------------- + +The ``index.rst`` file that ``sphinx-quickstart`` created has some content +already, and it gets rendered as the front page of your HTML documentation. It +is written in reStructuredText, a powerful markup language. + +Modify the file as follows: + +.. code-block:: rst + :caption: docs/source/index.rst + + Welcome to Lumache's documentation! + =================================== + + **Lumache** (/lu'make/) is a Python library for cooks and food lovers that + creates recipes mixing random ingredients. It pulls data from the `Open Food + Facts database <https://world.openfoodfacts.org/>`_ and offers a *simple* and + *intuitive* API. + + .. note:: + + This project is under active development. + +This showcases several features of the reStructuredText syntax, including: + +- a **section header** using ``===`` for the underline, +- two examples of :ref:`rst-inline-markup`: ``**strong emphasis**`` (typically + bold) and ``*emphasis*`` (typically italics), +- an **inline external link**, +- and a ``note`` **admonition** (one of the available :ref:`directives + <rst-directives>`) + +Now to render it with the new content, you can use the ``sphinx-build`` command +as before, or leverage the convenience script as follows: + +.. code-block:: console + + (.venv) $ cd docs + (.venv) $ make html + +After running this command, you will see that ``index.html`` reflects the new +changes! + +Building your documentation in other formats +-------------------------------------------- + +Sphinx supports a variety of formats apart from HTML, including PDF, EPUB, +:ref:`and more <builders>`. For example, to build your documentation +in EPUB format, run this command from the ``docs`` directory: + +.. code-block:: console + + (.venv) $ make epub + +After that, you will see the files corresponding to the e-book under +``docs/build/epub/``. You can either open ``Lumache.epub`` with an +EPUB-compatible e-book viewer, like `Calibre <https://calibre-ebook.com/>`_, +or preview ``index.xhtml`` on a web browser. + +.. note:: + + To quickly display a complete list of possible output formats, plus some + extra useful commands, you can run :code:`make help`. + +Each output format has some specific configuration options that you can tune, +:ref:`including EPUB <epub-options>`. For instance, the default value of +:confval:`epub_show_urls` is ``inline``, which means that, by default, URLs are +shown right after the corresponding link, in parentheses. You can change that +behavior by adding the following code at the end of your ``conf.py``: + +.. code-block:: python + + # EPUB options + epub_show_urls = 'footnote' + +With this configuration value, and after running ``make epub`` again, you will +notice that URLs appear now as footnotes, which avoids cluttering the text. +Sweet! Read on to explore :doc:`other ways to customize +Sphinx </tutorial/more-sphinx-customization>`. + +.. note:: + + Generating a PDF using Sphinx can be done running ``make latexpdf``, + provided that the system has a working LaTeX installation, + as explained in the documentation of :class:`sphinx.builders.latex.LaTeXBuilder`. + Although this is perfectly feasible, such installations are often big, + and in general LaTeX requires careful configuration in some cases, + so PDF generation is out of scope for this tutorial. diff --git a/doc/tutorial/getting-started.rst b/doc/tutorial/getting-started.rst new file mode 100644 index 0000000..5cf0b38 --- /dev/null +++ b/doc/tutorial/getting-started.rst @@ -0,0 +1,120 @@ +Getting started +=============== + +Setting up your project and development environment +--------------------------------------------------- + +In a new directory, create a file called ``README.rst`` with the following +content. + +.. code-block:: rst + :caption: README.rst + + Lumache + ======= + + **Lumache** (/lu'make/) is a Python library for cooks and food lovers that + creates recipes mixing random ingredients. + +It is a good moment to create a Python virtual environment and install the +required tools. For that, open a command line terminal, ``cd`` into the +directory you just created, and run the following commands: + +.. code-block:: console + + $ python -m venv .venv + $ source .venv/bin/activate + (.venv) $ python -m pip install sphinx + +.. note:: + + The installation method used above is described in more detail in + :ref:`install-pypi`. For the rest of this tutorial, the instructions will + assume a Python virtual environment. + +If you executed these instructions correctly, you should have the Sphinx command +line tools available. You can do a basic verification running this command: + +.. code-block:: console + + (.venv) $ sphinx-build --version + sphinx-build 4.0.2 + +If you see a similar output, you are on the right path! + +Creating the documentation layout +--------------------------------- + +Then from the command line, run the following command: + +.. code-block:: console + + (.venv) $ sphinx-quickstart docs + +This will present to you a series of questions required to create the basic +directory and configuration layout for your project inside the ``docs`` folder. +To proceed, answer each question as follows: + +- ``> Separate source and build directories (y/n) [n]``: Write "``y``" (without + quotes) and press :kbd:`Enter`. +- ``> Project name``: Write "``Lumache``" (without quotes) and press + :kbd:`Enter`. +- ``> Author name(s)``: Write "``Graziella``" (without quotes) and press + :kbd:`Enter`. +- ``> Project release []``: Write "``0.1``" (without quotes) and press + :kbd:`Enter`. +- ``> Project language [en]``: Leave it empty (the default, English) and press + :kbd:`Enter`. + +After the last question, you will see the new ``docs`` directory with the +following content. + +.. code-block:: text + + docs + ├── build + ├── make.bat + ├── Makefile + └── source + ├── conf.py + ├── index.rst + ├── _static + └── _templates + +The purpose of each of these files is: + +``build/`` + An empty directory (for now) that will hold the rendered documentation. + +``make.bat`` and ``Makefile`` + Convenience scripts to simplify some common Sphinx operations, such as + rendering the content. + +``source/conf.py`` + A Python script holding the configuration of the Sphinx project. It contains + the project name and release you specified to ``sphinx-quickstart``, as well + as some extra configuration keys. + +``source/index.rst`` + The :term:`root document` of the project, which serves as welcome page and + contains the root of the "table of contents tree" (or *toctree*). + +Thanks to this bootstrapping step, you already have everything needed to render +the documentation as HTML for the first time. To do that, run this command: + +.. code-block:: console + + (.venv) $ sphinx-build -b html docs/source/ docs/build/html + +And finally, open ``docs/build/html/index.html`` in your browser. You should see +something like this: + +.. figure:: /_static/tutorial/lumache-first-light.png + :width: 80% + :align: center + :alt: Freshly created documentation of Lumache + + Freshly created documentation of Lumache + +There we go! You created your first HTML documentation using Sphinx. +Now you can start :doc:`customizing it </tutorial/first-steps>`. diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst new file mode 100644 index 0000000..d7f4861 --- /dev/null +++ b/doc/tutorial/index.rst @@ -0,0 +1,39 @@ +.. _tutorial: + +================================== +Tutorial: 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, +handwritten documentation, as well as autogenerated API documentation. + +The tutorial is aimed towards Sphinx newcomers willing to learn the fundamentals +of how projects are created and structured. You will create a fictional +software library to generate random food recipes that will serve as a guide +throughout the process, with the objective of properly documenting it. + +To showcase Sphinx capabilities for code documentation you will use Python, +which also supports *automatic* documentation generation. + +.. note:: + + Several other languages are natively supported in Sphinx for *manual* code + documentation, however they require extensions for *automatic* code + documentation, like `Breathe <https://breathe.readthedocs.io/>`_. + +To follow the instructions you will need access to a Linux-like command line and +a basic understanding of how it works, as well as a working Python installation +for development, since you will use *Python virtual environments* to create the +project. + +.. toctree:: + + getting-started + first-steps + more-sphinx-customization + narrative-documentation + describing-code + automatic-doc-generation + deploying + end diff --git a/doc/tutorial/more-sphinx-customization.rst b/doc/tutorial/more-sphinx-customization.rst new file mode 100644 index 0000000..c28263c --- /dev/null +++ b/doc/tutorial/more-sphinx-customization.rst @@ -0,0 +1,78 @@ +More Sphinx customization +========================= + +There are two main ways to customize your documentation beyond what is possible +with core Sphinx: extensions and themes. + +Enabling a built-in extension +----------------------------- + +In addition to these configuration values, you can customize Sphinx even more +by using :doc:`extensions </usage/extensions/index>`. Sphinx ships several +:ref:`builtin ones <builtin-extensions>`, and there are many more +:ref:`maintained by the community <third-party-extensions>`. + +For example, to enable the :mod:`sphinx.ext.duration` extension, +locate the ``extensions`` list in your ``conf.py`` and add one element as +follows: + +.. code-block:: python + :caption: docs/source/conf.py + + # Add any Sphinx extension module names here, as strings. They can be + # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom + # ones. + extensions = [ + 'sphinx.ext.duration', + ] + +After that, every time you generate your documentation, you will see a short +durations report at the end of the console output, like this one: + +.. code-block:: console + + (.venv) $ make html + ... + The HTML pages are in build/html. + + ====================== slowest reading durations ======================= + 0.042 temp/source/index + +Using a third-party HTML theme +------------------------------ + +Themes, on the other hand, are a way to customize the appearance of your +documentation. Sphinx has several :ref:`builtin themes <builtin-themes>`, and +there are also `third-party ones <https://sphinx-themes.org/>`_. + +For example, to use the `Furo <https://pradyunsg.me/furo/>`_ third-party theme +in your HTML documentation, first you will need to install it with ``pip`` in +your Python virtual environment, like this: + +.. code-block:: console + + (.venv) $ pip install furo + +And then, locate the ``html_theme`` variable on your ``conf.py`` and replace +its value as follows: + +.. code-block:: python + :caption: docs/source/conf.py + + # The theme to use for HTML and HTML Help pages. See the documentation for + # a list of builtin themes. + # + html_theme = 'furo' + +With this change, you will notice that your HTML documentation has now a new +appearance: + +.. figure:: /_static/tutorial/lumache-furo.png + :width: 80% + :align: center + :alt: HTML documentation of Lumache with the Furo theme + + HTML documentation of Lumache with the Furo theme + +It is now time to :doc:`expand the narrative documentation and split it into +several documents </tutorial/narrative-documentation>`. diff --git a/doc/tutorial/narrative-documentation.rst b/doc/tutorial/narrative-documentation.rst new file mode 100644 index 0000000..a81204d --- /dev/null +++ b/doc/tutorial/narrative-documentation.rst @@ -0,0 +1,130 @@ +Narrative documentation in Sphinx +================================= + +Structuring your documentation across multiple pages +---------------------------------------------------- + +The file ``index.rst`` created by ``sphinx-quickstart`` is the :term:`root +document`, whose main function is to serve as a welcome page and to contain the +root of the "table of contents tree" (or *toctree*). Sphinx allows you to +assemble a project from different files, which is helpful when the project +grows. + +As an example, create a new file ``docs/source/usage.rst`` (next to +``index.rst``) with these contents: + +.. code-block:: rst + :caption: docs/source/usage.rst + + Usage + ===== + + Installation + ------------ + + To use Lumache, first install it using pip: + + .. code-block:: console + + (.venv) $ pip install lumache + +This new file contains two :ref:`section <rst-sections>` headers, normal +paragraph text, and a :rst:dir:`code-block` directive that renders +a block of content as source code, with appropriate syntax highlighting +(in this case, generic ``console`` text). + +The structure of the document is determined by the succession of heading +styles, which means that, by using ``---`` for the "Installation" section +after ``===`` for the "Usage" section, you have declared "Installation" to +be a *subsection* of "Usage". + +To complete the process, add a ``toctree`` :ref:`directive <rst-directives>` at +the end of ``index.rst`` including the document you just created, as follows: + +.. code-block:: rst + :caption: docs/source/index.rst + + Contents + -------- + + .. toctree:: + + usage + +This step inserts that document in the root of the *toctree*, so now it belongs +to the structure of your project, which so far looks like this: + +.. code-block:: text + + index + └── usage + +If you build the HTML documentation running ``make html``, you will see +that the ``toctree`` gets rendered as a list of hyperlinks, and this allows you +to navigate to the new page you just created. Neat! + +.. warning:: + + Documents outside a *toctree* will result in ``WARNING: document isn't + included in any toctree`` messages during the build process, and will be + unreachable for users. + +Adding cross-references +----------------------- + +One powerful feature of Sphinx is the ability to seamlessly add +:ref:`cross-references <xref-syntax>` to specific parts of the documentation: +a document, a section, a figure, a code object, etc. This tutorial is full of +them! + +To add a cross-reference, write this sentence right after the +introduction paragraph in ``index.rst``: + +.. code-block:: rst + :caption: docs/source/index.rst + + Check out the :doc:`usage` section for further information. + +The :rst:role:`doc` :ref:`role <rst-roles-alt>` you used automatically +references a specific document in the project, in this case the ``usage.rst`` +you created earlier. + +Alternatively, you can also add a cross-reference to an arbitrary part of the +project. For that, you need to use the :rst:role:`ref` role, and add an +explicit *label* that acts as :duref:`a target <hyperlink-targets>`. + +For example, to reference the "Installation" subsection, add a label right +before the heading, as follows: + +.. code-block:: rst + :caption: docs/source/usage.rst + :emphasize-lines: 4 + + Usage + ===== + + .. _installation: + + Installation + ------------ + + ... + +And make the sentence you added in ``index.rst`` look like this: + +.. code-block:: rst + :caption: docs/source/index.rst + + Check out the :doc:`usage` section for further information, including how to + :ref:`install <installation>` the project. + +Notice a trick here: the ``install`` part specifies how the link will look like +(we want it to be a specific word, so the sentence makes sense), whereas the +``<installation>`` part refers to the actual label we want to add a +cross-reference to. If you do not include an explicit title, hence using +``:ref:`installation```, the section title will be used (in this case, +``Installation``). Both the ``:doc:`` and the ``:ref:`` roles will be rendered +as hyperlinks in the HTML documentation. + +What about :doc:`documenting code objects in Sphinx </tutorial/describing-code>`? +Read on! diff --git a/doc/usage/advanced/intl.rst b/doc/usage/advanced/intl.rst new file mode 100644 index 0000000..ae6e7dc --- /dev/null +++ b/doc/usage/advanced/intl.rst @@ -0,0 +1,372 @@ +.. _intl: + +Internationalization +==================== + +.. versionadded:: 1.1 + +Complementary to translations provided for Sphinx-generated messages such as +navigation bars, Sphinx provides mechanisms facilitating the translation of +*documents*. See the :ref:`intl-options` for details on configuration. + +.. figure:: /_static/translation.* + :width: 100% + + Workflow visualization of translations in Sphinx. (The figure is created by + `plantuml <https://plantuml.com>`_.) + +.. contents:: + :local: + +Sphinx internationalization details +----------------------------------- + +**gettext** [1]_ is an established standard for internationalization and +localization. It naively maps messages in a program to a translated string. +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 -b 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 +paragraphs will remain as coarsely-grained as they were in the original +document. This grants seamless document updates while still providing a little +bit of context for translators in free-text passages. It is the maintainer's +task to split up paragraphs which are too large as there is no sane automated +way to do that. + +After Sphinx successfully ran the +:class:`~sphinx.builders.gettext.MessageCatalogBuilder` you will find a +collection of ``.pot`` files in your output directory. These are **catalog +templates** and contain messages in your original language *only*. + +They can be delivered to translators which will transform them to ``.po`` files +--- so called **message catalogs** --- containing a mapping from the original +messages to foreign-language strings. + +*gettext* compiles them into a binary format known as **binary catalogs** +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 +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 + (where ``es`` is the language code for Spanish.) :: + + msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo" + +* Set :confval:`locale_dirs` to ``["locale/"]``. +* Set :confval:`language` to ``es`` (also possible via + :option:`-D <sphinx-build -D>`). +* Run your desired build. + + +In order to protect against mistakes, a warning is emitted if +cross-references in the translated paragraph do not match those from the +original. This can be turned off globally using the +:confval:`suppress_warnings` configuration variable. Alternatively, to +turn it off for one message only, end the message with ``#noqa`` like +this:: + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse + risus tortor, luctus id ultrices at. #noqa + +(Write ``\#noqa`` in case you want to have "#noqa" literally in the +text. This does not apply to code blocks, where ``#noqa`` is ignored +because code blocks do not contain references anyway.) + +.. versionadded:: 4.5 + The ``#noqa`` mechanism. + + +Translating with sphinx-intl +---------------------------- + +Quick guide +~~~~~~~~~~~ + +`sphinx-intl`_ is a useful tool to work with Sphinx translation flow. This +section describe an easy way to translate with *sphinx-intl*. + +#. Install `sphinx-intl`_. + + .. code-block:: console + + $ pip install sphinx-intl + +#. Add configurations to ``conf.py``. + + :: + + locale_dirs = ['locale/'] # path is example but recommended. + gettext_compact = False # optional. + + This case-study assumes that BUILDDIR is set to ``_build``, + :confval:`locale_dirs` is set to ``locale/`` and :confval:`gettext_compact` + is set to ``False`` (the Sphinx document is already configured as such). + +#. Extract translatable messages into pot files. + + .. code-block:: console + + $ make gettext + + The generated pot files will be placed in the ``_build/gettext`` directory. + +#. Generate po files. + + We'll use the pot files generated in the above step. + + .. code-block:: console + + $ sphinx-intl update -p _build/gettext -l de -l ja + + Once completed, the generated po files will be placed in the below + directories: + + * ``./locale/de/LC_MESSAGES/`` + * ``./locale/ja/LC_MESSAGES/`` + +#. 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 + given below. + + .. code-block:: po + + # a5600c3d2e3d48fc8c261ea0284db79b + #: ../../builders.rst:4 + msgid "Available builders" + msgstr "<FILL HERE BY TARGET LANGUAGE>" + + Another case, msgid is multi-line text and contains reStructuredText syntax: + + .. code-block:: po + + # 302558364e1d41c69b3277277e34b184 + #: ../../builders.rst:9 + msgid "" + "These are the built-in Sphinx builders. More builders can be added by " + ":ref:`extensions <extensions>`." + msgstr "" + "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. + +#. Build translated document. + + You need a :confval:`language` parameter in ``conf.py`` or you may also + specify the parameter on the command line. + + For BSD/GNU make, run: + + .. code-block:: console + + $ make -e SPHINXOPTS="-D language='de'" html + + For Windows :command:`cmd.exe`, run: + + .. code-block:: console + + > set SPHINXOPTS=-D language=de + > .\make.bat html + + For PowerShell, run: + + .. code-block:: console + + > Set-Item env:SPHINXOPTS "-D language=de" + > .\make.bat html + +Congratulations! You got the translated documentation in the ``_build/html`` +directory. + +.. versionadded:: 1.3 + + :program:`sphinx-build` that is invoked by make command will build po files + into mo files. + + If you are using 1.2.x or earlier, please invoke :command:`sphinx-intl build` + command before :command:`make` command. + +Translating +~~~~~~~~~~~ + +Update your po files by new pot files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If a document is updated, it is necessary to generate updated pot files and to +apply differences to translated po files. In order to apply the updates from a +pot file to the po file, use the :command:`sphinx-intl update` command. + +.. code-block:: console + + $ sphinx-intl update -p _build/gettext + + +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 +easy to fetch and push translations. + +.. TODO: why use transifex? + + +#. Install `transifex-client`_. + + You need :command:`tx` command to upload resources (pot files). + + .. code-block:: console + + $ pip install transifex-client + + .. seealso:: `Transifex Client documentation`_ + +#. Create your Transifex_ account and create new project 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 + your project name. + + For example: + + :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. + + This process will create ``.tx/config`` in the current directory, as well as + a ``~/.transifexrc`` file that includes auth information. + + .. code-block:: console + + $ tx init + Creating .tx folder... + Transifex instance [https://www.transifex.com]: + ... + Please enter your transifex username: <transifex-username> + Password: <transifex-password> + ... + Done. + +#. Upload pot files to Transifex service. + + Register pot files to ``.tx/config`` file: + + .. code-block:: console + + $ cd /your/document/root + $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \ + --transifex-project-name sphinx-document-test_1_0 + + 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. + +#. Forward the translation on Transifex. + + .. TODO: write this section + +#. Pull translated po files and make translated HTML. + + Get translated catalogs and build mo files. For example, to build mo files + for German (de): + + .. code-block:: console + + $ 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. + + Invoke :command:`make html` (for BSD/GNU make): + + .. code-block:: console + + $ make -e SPHINXOPTS="-D language='de'" html + +That's all! + +.. tip:: Translating locally and on Transifex + + If you want to push all language's po files, you can be done by using + :command:`tx push -t` command. Watch out! This operation overwrites + translations in Transifex. + + In other words, if you have updated each in the service and local po files, + it would take much time and effort to integrate them. + + +Using Weblate service for team translation +------------------------------------------ + +Read more in `Weblate's documentation`_. + + +Contributing to Sphinx reference translation +-------------------------------------------- + +The recommended way for new contributors to translate Sphinx reference is to +join the translation team on Transifex. + +There is a `sphinx translation page`_ for Sphinx (master) documentation. + +1. Login to Transifex_ service. +2. Go to `sphinx translation page`_. +3. Click ``Request language`` and fill form. +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 + + +Translation progress and statistics +----------------------------------- + +.. versionadded:: 7.1.0 + +During the rendering process, +Sphinx marks each translatable node with a ``translated`` attribute, +indicating if a translation was found for the text in that node. + +The :confval:`translation_progress_classes` configuration value +can be used to add a class to each element, +depending on the value of the ``translated`` attribute. + +The ``|translation progress|`` substitution can be used to display the +percentage of nodes that have been translated on a per-document basis. + +.. rubric:: Footnotes + +.. [1] See the `GNU gettext utilities + <https://www.gnu.org/software/gettext/manual/gettext.html#Introduction>`_ + for details on that software suite. +.. [2] Because nobody expects the Spanish Inquisition! + +.. _`transifex-client`: https://pypi.org/project/transifex-client/ +.. _`sphinx-intl`: https://pypi.org/project/sphinx-intl/ +.. _Transifex: https://www.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/ diff --git a/doc/usage/advanced/websupport/api.rst b/doc/usage/advanced/websupport/api.rst new file mode 100644 index 0000000..79b51ee --- /dev/null +++ b/doc/usage/advanced/websupport/api.rst @@ -0,0 +1,80 @@ +.. _websupportapi: + +.. currentmodule:: sphinxcontrib.websupport + +The WebSupport Class +==================== + +.. class:: WebSupport + + The main API class for the web support package. All interactions with the + web support package should occur through this class. + + The class takes the following keyword arguments: + + srcdir + The directory containing reStructuredText source files. + + builddir + The directory that build data and static files should be placed in. This + should be used when creating a :class:`WebSupport` object that will be + used to build data. + + datadir + The directory that the web support data is in. This should be used when + creating a :class:`WebSupport` object that will be used to retrieve data. + + search + This may contain either a string (e.g. 'xapian') referencing a built-in + search adapter to use, or an instance of a subclass of + :class:`~.search.BaseSearch`. + + storage + This may contain either a string representing a database uri, or an + instance of a subclass of :class:`~.storage.StorageBackend`. If this is + not provided, a new sqlite database will be created. + + moderation_callback + A callable to be called when a new comment is added that is not + displayed. It must accept one argument: a dictionary representing the + comment that was added. + + staticdir + If the static files should be created in a different location + **and not in** ``'/static'``, this should be a string with the name of + that location (e.g. ``builddir + '/static_files'``). + + .. note:: + If you specify ``staticdir``, you will typically want to adjust + ``staticroot`` accordingly. + + staticroot + If the static files are not served from ``'/static'``, this should be a + string with the name of that location (e.g. ``'/static_files'``). + + docroot + If the documentation is not served from the base path of a URL, this + should be a string specifying that path (e.g. ``'docs'``). + + +.. versionchanged:: 1.6 + + WebSupport class is moved to sphinxcontrib.websupport from sphinx.websupport. + Please add ``sphinxcontrib-websupport`` package in your dependency and use + moved class instead. + + +Methods +------- + +.. automethod:: sphinxcontrib.websupport.WebSupport.build + +.. automethod:: sphinxcontrib.websupport.WebSupport.get_document + +.. automethod:: sphinxcontrib.websupport.WebSupport.get_data + +.. automethod:: sphinxcontrib.websupport.WebSupport.add_comment + +.. automethod:: sphinxcontrib.websupport.WebSupport.process_vote + +.. automethod:: sphinxcontrib.websupport.WebSupport.get_search_results diff --git a/doc/usage/advanced/websupport/index.rst b/doc/usage/advanced/websupport/index.rst new file mode 100644 index 0000000..0816640 --- /dev/null +++ b/doc/usage/advanced/websupport/index.rst @@ -0,0 +1,16 @@ +.. _websupport: + +Sphinx Web Support +================== + +.. versionadded:: 1.1 + +Sphinx provides a Python API to easily integrate Sphinx documentation into your +web application. To learn more read the :ref:`websupportquickstart`. + +.. toctree:: + + quickstart + api + searchadapters + storagebackends diff --git a/doc/usage/advanced/websupport/quickstart.rst b/doc/usage/advanced/websupport/quickstart.rst new file mode 100644 index 0000000..1cdd23f --- /dev/null +++ b/doc/usage/advanced/websupport/quickstart.rst @@ -0,0 +1,255 @@ +.. _websupportquickstart: + +Web Support Quick Start +======================= + +Building Documentation Data +---------------------------- + +To make use of the web support package in your application you'll need to build +the data it uses. This data includes pickle files representing documents, +search indices, and node data that is used to track where comments and other +things are in a document. To do this you will need to create an instance of the +:class:`~.WebSupport` class and call its :meth:`~.WebSupport.build` method:: + + from sphinxcontrib.websupport import WebSupport + + support = WebSupport(srcdir='/path/to/rst/sources/', + builddir='/path/to/build/outdir', + search='xapian') + + support.build() + +This will read reStructuredText sources from ``srcdir`` and place the necessary +data in ``builddir``. The ``builddir`` will contain two sub-directories: 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". + +.. note:: + + If you wish to serve static files from a path other than "/static", you can + do so by providing the *staticdir* keyword argument when creating the + :class:`~.WebSupport` object. + + +Integrating Sphinx Documents Into Your Webapp +---------------------------------------------- + +Now that the data is built, it's time to do something useful with it. Start off +by creating a :class:`~.WebSupport` object for your application:: + + from sphinxcontrib.websupport import WebSupport + + support = WebSupport(datadir='/path/to/the/data', + search='xapian') + +You'll only need one of these for each set of documentation you will be working +with. You can then call its :meth:`~.WebSupport.get_document` method to access +individual documents:: + + contents = support.get_document('contents') + +This will return a dictionary containing the following items: + +* **body**: The main body of the document as HTML +* **sidebar**: The sidebar of the document as HTML +* **relbar**: A div containing links to related documents +* **title**: The title of the document +* **css**: Links to CSS files used by Sphinx +* **script**: JavaScript containing comment options + +This dict can then be used as context for templates. The goal is to be easy to +integrate with your existing templating system. An example using `Jinja2 +<https://jinja.palletsprojects.com/>`_ is: + +.. code-block:: html+jinja + + {%- extends "layout.html" %} + + {%- block title %} + {{ document.title }} + {%- endblock %} + + {% block css %} + {{ super() }} + {{ document.css|safe }} + <link rel="stylesheet" href="/static/websupport-custom.css" type="text/css"> + {% endblock %} + + {%- block script %} + {{ super() }} + {{ document.script|safe }} + {%- endblock %} + + {%- block relbar %} + {{ document.relbar|safe }} + {%- endblock %} + + {%- block body %} + {{ document.body|safe }} + {%- endblock %} + + {%- block sidebar %} + {{ document.sidebar|safe }} + {%- endblock %} + + +Authentication +~~~~~~~~~~~~~~ + +To use certain features such as voting, it must be possible to authenticate +users. The details of the authentication are left to your application. Once a +user has been authenticated you can pass the user's details to certain +:class:`~.WebSupport` methods using the *username* and *moderator* keyword +arguments. The web support package will store the username with comments and +votes. The only caveat is that if you allow users to change their username you +must update the websupport package's data:: + + support.update_username(old_username, new_username) + +*username* should be a unique string which identifies a user, and *moderator* +should be a boolean representing whether the user has moderation privileges. +The default value for *moderator* is ``False``. + +An example `Flask <https://flask.palletsprojects.com/>`_ function that checks +whether a user is logged in and then retrieves a document is:: + + from sphinxcontrib.websupport.errors import * + + @app.route('/<path:docname>') + def doc(docname): + username = g.user.name if g.user else '' + moderator = g.user.moderator if g.user else False + try: + document = support.get_document(docname, username, moderator) + except DocumentNotFoundError: + abort(404) + return render_template('doc.html', document=document) + +The first thing to notice is that the *docname* is just the request path. This +makes accessing the correct document easy from a single view. If the user is +authenticated, then the username and moderation status are passed along with the +docname to :meth:`~.WebSupport.get_document`. The web support package will then +add this data to the ``COMMENT_OPTIONS`` that are used in the template. + +.. note:: + + This only works if your documentation is served from your + document root. If it is served from another directory, you will + need to prefix the url route with that directory, and give the `docroot` + keyword argument when creating the web support object:: + + support = WebSupport(..., docroot='docs') + + @app.route('/docs/<path:docname>') + + +Performing Searches +------------------- + +To use the search form built-in to the Sphinx sidebar, create a function to +handle requests to the URL 'search' relative to the documentation root. The +user's search query will be in the GET parameters, with the key `q`. Then use +the :meth:`~sphinxcontrib.websupport.WebSupport.get_search_results` method to +retrieve search results. In `Flask <https://flask.palletsprojects.com/>`_ that +would be like this:: + + @app.route('/search') + def search(): + q = request.args.get('q') + document = support.get_search_results(q) + return render_template('doc.html', document=document) + +Note that we used the same template to render our search results as we did to +render our documents. That's because :meth:`~.WebSupport.get_search_results` +returns a context dict in the same format that :meth:`~.WebSupport.get_document` +does. + + +Comments & Proposals +-------------------- + +Now that this is done it's time to define the functions that handle the AJAX +calls from the script. You will need three functions. The first function is +used to add a new comment, and will call the web support method +:meth:`~.WebSupport.add_comment`:: + + @app.route('/docs/add_comment', methods=['POST']) + def add_comment(): + parent_id = request.form.get('parent', '') + node_id = request.form.get('node', '') + text = request.form.get('text', '') + proposal = request.form.get('proposal', '') + username = g.user.name if g.user is not None else 'Anonymous' + comment = support.add_comment(text, node_id='node_id', + parent_id='parent_id', + username=username, proposal=proposal) + return jsonify(comment=comment) + +You'll notice that both a ``parent_id`` and ``node_id`` are sent with the +request. If the comment is being attached directly to a node, ``parent_id`` +will be empty. If the comment is a child of another comment, then ``node_id`` +will be empty. Then next function handles the retrieval of comments for a +specific node, and is aptly named +:meth:`~sphinxcontrib.websupport.WebSupport.get_data`:: + + @app.route('/docs/get_comments') + def get_comments(): + username = g.user.name if g.user else None + moderator = g.user.moderator if g.user else False + node_id = request.args.get('node', '') + data = support.get_data(node_id, username, moderator) + return jsonify(**data) + +The final function that is needed will call :meth:`~.WebSupport.process_vote`, +and will handle user votes on comments:: + + @app.route('/docs/process_vote', methods=['POST']) + def process_vote(): + if g.user is None: + abort(401) + comment_id = request.form.get('comment_id') + value = request.form.get('value') + if value is None or comment_id is None: + abort(400) + support.process_vote(comment_id, g.user.id, value) + return "success" + + +Comment Moderation +------------------ + +By default, all comments added through :meth:`~.WebSupport.add_comment` are +automatically displayed. If you wish to have some form of moderation, you can +pass the ``displayed`` keyword argument:: + + comment = support.add_comment(text, node_id='node_id', + parent_id='parent_id', + username=username, proposal=proposal, + displayed=False) + +You can then create a new view to handle the moderation of comments. It +will be called when a moderator decides a comment should be accepted and +displayed:: + + @app.route('/docs/accept_comment', methods=['POST']) + def accept_comment(): + moderator = g.user.moderator if g.user else False + comment_id = request.form.get('id') + support.accept_comment(comment_id, moderator=moderator) + return 'OK' + +Rejecting comments happens via comment deletion. + +To perform a custom action (such as emailing a moderator) when a new comment is +added but not displayed, you can pass callable to the :class:`~.WebSupport` +class when instantiating your support object:: + + def moderation_callback(comment): + """Do something...""" + + support = WebSupport(..., moderation_callback=moderation_callback) + +The moderation callback must take one argument, which will be the same comment +dict that is returned by :meth:`.WebSupport.add_comment`. diff --git a/doc/usage/advanced/websupport/searchadapters.rst b/doc/usage/advanced/websupport/searchadapters.rst new file mode 100644 index 0000000..262d666 --- /dev/null +++ b/doc/usage/advanced/websupport/searchadapters.rst @@ -0,0 +1,49 @@ +.. _searchadapters: + +.. currentmodule:: sphinxcontrib.websupport.search + +Search Adapters +=============== + +To create a custom search adapter you will need to subclass the +:class:`BaseSearch` class. Then create an instance of the new class and pass +that as the `search` keyword argument when you create the :class:`~.WebSupport` +object:: + + support = WebSupport(srcdir=srcdir, + builddir=builddir, + search=MySearch()) + +For more information about creating a custom search adapter, please see the +documentation of the :class:`BaseSearch` class below. + +.. class:: BaseSearch + + Defines an interface for search adapters. + +.. versionchanged:: 1.6 + + BaseSearch class is moved to sphinxcontrib.websupport.search from + sphinx.websupport.search. + +Methods +------- + +The following methods are defined in the BaseSearch class. Some methods do not +need to be overridden, but some (:meth:`~BaseSearch.add_document` and +:meth:`~BaseSearch.handle_query`) must be overridden in your subclass. For a +working example, look at the built-in adapter for whoosh. + +.. automethod:: BaseSearch.init_indexing + +.. automethod:: BaseSearch.finish_indexing + +.. automethod:: BaseSearch.feed + +.. automethod:: BaseSearch.add_document + +.. automethod:: BaseSearch.query + +.. automethod:: BaseSearch.handle_query + +.. automethod:: BaseSearch.extract_context diff --git a/doc/usage/advanced/websupport/storagebackends.rst b/doc/usage/advanced/websupport/storagebackends.rst new file mode 100644 index 0000000..ccb00b6 --- /dev/null +++ b/doc/usage/advanced/websupport/storagebackends.rst @@ -0,0 +1,49 @@ +.. _storagebackends: + +.. currentmodule:: sphinxcontrib.websupport.storage + +Storage Backends +================ + +To create a custom storage backend you will need to subclass the +:class:`StorageBackend` class. Then create an instance of the new class and +pass that as the `storage` keyword argument when you create the +:class:`~.WebSupport` object:: + + support = WebSupport(srcdir=srcdir, + builddir=builddir, + storage=MyStorage()) + +For more information about creating a custom storage backend, please see the +documentation of the :class:`StorageBackend` class below. + +.. class:: StorageBackend + + Defines an interface for storage backends. + +.. versionchanged:: 1.6 + + StorageBackend class is moved to sphinxcontrib.websupport.storage from + sphinx.websupport.storage. + + +Methods +------- + +.. automethod:: StorageBackend.pre_build + +.. automethod:: StorageBackend.add_node + +.. automethod:: StorageBackend.post_build + +.. automethod:: StorageBackend.add_comment + +.. automethod:: StorageBackend.delete_comment + +.. automethod:: StorageBackend.get_data + +.. automethod:: StorageBackend.process_vote + +.. automethod:: StorageBackend.update_username + +.. automethod:: StorageBackend.accept_comment diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst new file mode 100644 index 0000000..ce2c5dc --- /dev/null +++ b/doc/usage/builders/index.rst @@ -0,0 +1,565 @@ +.. _builders: + +======== +Builders +======== + +.. module:: sphinx.builders + :synopsis: Available built-in builder classes. + +These are the built-in Sphinx builders. More builders can be added by +:doc:`extensions </usage/extensions/index>`. + +The builder's "name" must be given to the **-b** command-line option of +:program:`sphinx-build` to select a builder. + + +.. module:: sphinx.builders.html +.. 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. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + +.. module:: sphinx.builders.dirhtml +.. class:: DirectoryHTMLBuilder + + This is a subclass of the standard HTML builder. Its output is a directory + with HTML files, where each file is called ``index.html`` and placed in a + subdirectory named like its page name. For example, the document + ``markup/rest.rst`` will not result in an output file ``markup/rest.html``, + but ``markup/rest/index.html``. When generating links between pages, the + ``index.html`` is omitted, so that the URL would look like ``markup/rest/``. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionadded:: 0.6 + +.. module:: sphinx.builders.singlehtml +.. class:: SingleFileHTMLBuilder + + This is an HTML builder that combines the whole project in one output file. + (Obviously this only works with smaller projects.) The file is named like + the root document. No indices will be generated. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionadded:: 1.0 + +.. module:: sphinxcontrib.htmlhelp +.. class:: HTMLHelpBuilder + + This builder produces the same output as the standalone HTML builder, but + also generates HTML Help support files that allow the Microsoft HTML Help + Workshop to compile them into a CHM file. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + +.. module:: sphinxcontrib.qthelp +.. class:: QtHelpBuilder + + This builder produces the same output as the standalone HTML builder, but + also generates `Qt help`_ collection support files that allow the Qt + collection generator to compile them. + + .. versionchanged:: 2.0 + + Moved to sphinxcontrib.qthelp from sphinx.builders package. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. _Qt help: https://doc.qt.io/qt-4.8/qthelp-framework.html + +.. module:: sphinxcontrib.applehelp +.. class:: AppleHelpBuilder + + This builder produces an Apple Help Book based on the same output as the + standalone HTML builder. + + If the source directory contains any ``.lproj`` folders, the one + corresponding to the selected language will have its contents merged with + the generated output. These folders will be ignored by all other + documentation types. + + In order to generate a valid help book, this builder requires the command + line tool :program:`hiutil`, which is only available on Mac OS X 10.6 and + above. You can disable the indexing step by setting + :confval:`applehelp_disable_external_tools` to ``True``, in which case the + output will not be valid until :program:`hiutil` has been run on all of the + ``.lproj`` folders within the bundle. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionadded:: 1.3 + + .. versionchanged:: 2.0 + + Moved to sphinxcontrib.applehelp from sphinx.builders package. + +.. module:: sphinxcontrib.devhelp +.. class:: DevhelpBuilder + + This builder produces the same output as the standalone HTML builder, but + also generates `GNOME Devhelp <https://wiki.gnome.org/Apps/Devhelp>`__ + support file that allows the GNOME Devhelp reader to view them. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionchanged:: 2.0 + + Moved to sphinxcontrib.devhelp from sphinx.builders package. + +.. module:: sphinx.builders.epub3 +.. class:: Epub3Builder + + This builder produces the same output as the standalone HTML builder, but + also generates an *epub* file for ebook readers. See :ref:`epub-faq` for + details about it. For definition of the epub format, have a look at + `<http://idpf.org/epub>`_ or `<https://en.wikipedia.org/wiki/EPUB>`_. + The builder creates *EPUB 3* files. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionadded:: 1.4 + + .. versionchanged:: 1.5 + + Since Sphinx 1.5, the epub3 builder is used as the default epub builder. + +.. module:: sphinx.builders.latex +.. class:: LaTeXBuilder + + This builder produces LaTeX source files in the output directory. The + actual PDF builds happen inside this output directory and need to be + triggered in a second step. This can be done via + :program:`make all-pdf` there. + To combine the two steps into only one, use :option:`sphinx-build -M` + (i.e. ``-M latexpdf`` not ``-b latexpdf``) or :program:`make latexpdf` + at the project root. + + See :confval:`latex_documents` and the chapter :ref:`latex-options` for + available options. + + PDF builds need a sufficiently complete LaTeX installation. + The testing is currently (since 5.3.0) done on Ubuntu 22.04LTS, + whose LaTeX distribution matches upstream TeXLive 2021 as of 2022/02/04, + but PDF builds can be successfully done on much older LaTeX installations. + + At any rate, on Ubuntu for example, following packages must all be present: + + * ``texlive-latex-recommended`` + * ``texlive-fonts-recommended`` + * ``tex-gyre`` (if :confval:`latex_engine` left to default) + * ``texlive-latex-extra`` + * ``latexmk`` + + .. versionchanged:: 4.0.0 + TeX Gyre fonts now required for ``'pdflatex'`` engine (default). + + Additional packages are needed in some circumstances: + + * ``texlive-lang-cyrillic`` for Cyrillic (and also then + ``cm-super`` if using the default fonts), + * ``texlive-lang-greek`` for Greek (and also then + ``cm-super`` if using the default fonts), + * ``texlive-xetex`` if :confval:`latex_engine` is ``'xelatex'``, + * ``texlive-luatex`` if :confval:`latex_engine` is ``'lualatex'``, + * ``fonts-freefont-otf`` if :confval:`latex_engine` is either + ``'xelatex'`` or ``'lualatex'``. + + .. note:: + + Since 1.6, ``make latexpdf`` uses on GNU/Linux and macOS + :program:`latexmk`, as it + makes sure the needed number of runs is automatically executed. + On Windows the PDF builds execute a fix number of LaTeX runs + (three, then ``makeindex``, then two more). + + One can pass to ``latexmk`` options via the ``LATEXMKOPTS`` + Makefile variable. For example: + + .. code-block:: console + + make latexpdf LATEXMKOPTS="-silent" + + reduces console output to a minimum. + + Also, if ``latexmk`` is at version 4.52b or higher (January 2017) + ``LATEXMKOPTS="-xelatex"`` speeds up PDF builds via XeLateX in case + of numerous graphics inclusions. + + To pass options directly to the ``(pdf|xe|lua)latex`` binary, use + variable ``LATEXOPTS``, for example: + + .. code-block:: console + + make latexpdf LATEXOPTS="--halt-on-error" + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + +Note that a direct PDF builder is being provided by `rinohtype`_. The builder's +name is ``rinoh``. Refer to the `rinohtype manual`_ for details. + +.. _rinohtype: https://github.com/brechtm/rinohtype +.. _rinohtype manual: https://www.mos6581.org/rinohtype/master/quickstart.html#sphinx-builder + +.. 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. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionadded:: 0.4 + +.. module:: sphinx.builders.manpage +.. class:: ManualPageBuilder + + This builder produces manual pages in the groff format. You have to specify + which documents are to be included in which manual pages via the + :confval:`man_pages` configuration value. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionadded:: 1.0 + + +.. module:: sphinx.builders.texinfo +.. class:: TexinfoBuilder + + This builder produces Texinfo files that can be processed into Info files by + the :program:`makeinfo` program. You have to specify which documents are to + be included in which Texinfo files via the :confval:`texinfo_documents` + configuration value. + + The Info format is the basis of the on-line help system used by GNU Emacs and + the terminal-based program :program:`info`. See :ref:`texinfo-faq` for more + details. The Texinfo format is the official documentation system used by the + GNU project. More information on Texinfo can be found at + `<https://www.gnu.org/software/texinfo/>`_. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionadded:: 1.1 + + +.. currentmodule:: sphinxcontrib.serializinghtml +.. class:: SerializingHTMLBuilder + + This builder uses a module that implements the Python serialization API + (`pickle`, `simplejson`, `phpserialize`, and others) to dump the generated + HTML documentation. The pickle builder is a subclass of it. + + A concrete subclass of this builder serializing to the `PHP serialization`_ + format could look like this:: + + import phpserialize + + class PHPSerializedBuilder(SerializingHTMLBuilder): + name = 'phpserialized' + implementation = phpserialize + out_suffix = '.file.phpdump' + globalcontext_filename = 'globalcontext.phpdump' + searchindex_filename = 'searchindex.phpdump' + + .. _PHP serialization: https://pypi.org/project/phpserialize/ + + .. attribute:: implementation + + A module that implements `dump()`, `load()`, `dumps()` and `loads()` + functions that conform to the functions with the same names from the + pickle module. Known modules implementing this interface are + `simplejson`, `phpserialize`, `plistlib`, and others. + + .. attribute:: out_suffix + + The suffix for all regular files. + + .. attribute:: globalcontext_filename + + The filename for the file that contains the "global context". This + is a dict with some general configuration values such as the name + of the project. + + .. attribute:: searchindex_filename + + The filename for the search index Sphinx generates. + + See :ref:`serialization-details` for details about the output format. + + .. versionadded:: 0.5 + +.. class:: PickleHTMLBuilder + + This builder produces a directory with pickle files containing mostly HTML + fragments and TOC information, for use of a web application (or custom + postprocessing tool) that doesn't use the standard HTML templates. + + See :ref:`serialization-details` for details about the output format. + + .. autoattribute:: name + + The old name ``web`` still works as well. + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + The file suffix is ``.fpickle``. The global context is called + ``globalcontext.pickle``, the search index ``searchindex.pickle``. + +.. class:: JSONHTMLBuilder + + This builder produces a directory with JSON files containing mostly HTML + fragments and TOC information, for use of a web application (or custom + postprocessing tool) that doesn't use the standard HTML templates. + + See :ref:`serialization-details` for details about the output format. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + The file suffix is ``.fjson``. The global context is called + ``globalcontext.json``, the search index ``searchindex.json``. + + .. versionadded:: 0.5 + +.. module:: sphinx.builders.gettext +.. class:: MessageCatalogBuilder + + This builder produces gettext-style message catalogs. Each top-level file or + subdirectory grows a single ``.pot`` catalog template. + + See the documentation on :ref:`intl` for further reference. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionadded:: 1.1 + +.. module:: sphinx.builders.changes +.. class:: ChangesBuilder + + This builder produces an HTML overview of all :rst:dir:`versionadded`, + :rst:dir:`versionchanged` and :rst:dir:`deprecated` directives for the + current :confval:`version`. This is useful to generate a ChangeLog file, for + example. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + +.. module:: sphinx.builders.dummy +.. class:: DummyBuilder + + This builder produces no output. The input is only parsed and checked for + consistency. This is useful for linting purposes. + + .. autoattribute:: name + + .. autoattribute:: supported_image_types + + .. versionadded:: 1.4 + +.. module:: sphinx.builders.linkcheck +.. class:: CheckExternalLinksBuilder + + This builder scans all documents for external links, tries to open them with + ``requests``, and writes an overview which ones are broken and redirected to + standard output and to :file:`output.txt` in the output directory. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionchanged:: 1.5 + + Since Sphinx 1.5, the linkcheck builder uses the requests module. + + .. versionchanged:: 3.4 + + The linkcheck builder retries links when servers apply rate limits. + +.. module:: sphinx.builders.xml +.. class:: XMLBuilder + + This builder produces Docutils-native XML files. The output can be + transformed with standard XML tools such as XSLT processors into arbitrary + final forms. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionadded:: 1.2 + +.. class:: PseudoXMLBuilder + + This builder is used for debugging the Sphinx/Docutils "Reader to Transform + to Writer" pipeline. It produces compact pretty-printed "pseudo-XML", files + where nesting is indicated by indentation (no end-tags). External + attributes for all elements are output, and internal attributes for any + leftover "pending" elements are also given. + + .. autoattribute:: name + + .. autoattribute:: format + + .. autoattribute:: supported_image_types + + .. versionadded:: 1.2 + + +Built-in Sphinx extensions that offer more builders are: + +* :mod:`~sphinx.ext.doctest` +* :mod:`~sphinx.ext.coverage` + + +.. _serialization-details: + +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. + +The :class:`.PickleHTMLBuilder` is a builtin subclass that implements the pickle +serialization interface. + +The files per source file have the extensions of +:attr:`~.SerializingHTMLBuilder.out_suffix`, and are arranged in directories +just as the source files are. They unserialize to a dictionary (or dictionary +like structure) with these keys: + +``body`` + The HTML "body" (that is, the HTML rendering of the source file), as rendered + by the HTML translator. + +``title`` + The title of the document, as HTML (may contain markup). + +``toc`` + The table of contents for the file, rendered as an HTML ``<ul>``. + +``display_toc`` + A boolean that is ``True`` if the ``toc`` contains more than one entry. + +``current_page_name`` + The document name of the current file. + +``parents``, ``prev`` and ``next`` + Information about related chapters in the TOC tree. Each relation is a + dictionary with the keys ``link`` (HREF for the relation) and ``title`` + (title of the related document, as HTML). ``parents`` is a list of + relations, while ``prev`` and ``next`` are a single relation. + +``sourcename`` + The name of the source file under ``_sources``. + +The special files are located in the root output directory. They are: + +:attr:`.SerializingHTMLBuilder.globalcontext_filename` + A pickled dict with these keys: + + ``project``, ``copyright``, ``release``, ``version`` + The same values as given in the configuration file. + + ``style`` + :confval:`html_style`. + + ``last_updated`` + Date of last build. + + ``builder`` + Name of the used builder, in the case of pickles this is always + ``'pickle'``. + + ``titles`` + A dictionary of all documents' titles, as HTML strings. + +:attr:`.SerializingHTMLBuilder.searchindex_filename` + An index that can be used for searching the documentation. It is a pickled + list with these entries: + + * A list of indexed docnames. + * A list of document titles, as HTML strings, in the same order as the first + list. + * A dict mapping word roots (processed by an English-language stemmer) to a + list of integers, which are indices into the first list. + +``environment.pickle`` + The build environment. This is always a pickle file, independent of the + builder and a copy of the environment that was used when the builder was + started. + + .. todo:: Document common members. + + Unlike the other pickle files this pickle file requires that the ``sphinx`` + package is available on unpickling. diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst new file mode 100644 index 0000000..d440132 --- /dev/null +++ b/doc/usage/configuration.rst @@ -0,0 +1,3094 @@ +.. highlight:: python + +.. _build-config: + +============= +Configuration +============= + +.. module:: conf + :synopsis: Build configuration file. + +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. + +An optional file `docutils.conf`_ can be added to the configuration +directory to adjust `Docutils`_ configuration if not otherwise overridden or +set by Sphinx. + +.. _`docutils`: https://docutils.sourceforge.io/ +.. _`docutils.conf`: https://docutils.sourceforge.io/docs/user/config.html + +The configuration file is executed as Python code at build time (using +:func:`importlib.import_module`, and with the current directory set to its +containing directory), and therefore can execute arbitrarily complex code. +Sphinx then reads simple names from the file's namespace as its configuration. + +Important points to note: + +* If not otherwise documented, values must be strings, and their default is the + empty string. + +* The term "fully-qualified name" refers to a string that names an importable + Python object inside a module; for example, the FQN + ``"sphinx.builders.Builder"`` means the ``Builder`` class in the + ``sphinx.builders`` module. + +* Remember that document names use ``/`` as the path separator and don't + contain the file name extension. + +* Since :file:`conf.py` is read as a Python file, the usual rules apply for + encodings and Unicode support. + +* The contents of the config namespace are pickled (so that Sphinx can find out + when configuration changes), so it may not contain unpickleable values -- + delete them from the namespace with ``del`` if appropriate. Modules are + removed automatically, so you don't need to ``del`` your imports after use. + + .. _conf-tags: + +* 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. + + +Project information +------------------- + +.. confval:: project + + The documented project's name. + +.. confval:: author + + The author name(s) of the document. The default value is ``'unknown'``. + +.. confval:: copyright + + A copyright statement in the style ``'2008, Author Name'``. + + .. 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 + + An alias of :confval:`copyright`. + + .. versionadded:: 3.5 + +.. 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``. + +.. confval:: release + + The full project version, used as the replacement for ``|release|`` and + e.g. in the HTML templates. For example, for the Python documentation, this + may be something like ``2.6.0rc1``. + + If you don't need the separation provided between :confval:`version` and + :confval:`release`, just set them both to the same value. + + +General configuration +--------------------- + +.. confval:: extensions + + 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. + + 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:: + + import sys, os + + sys.path.append(os.path.abspath('sphinxext')) + + extensions = ['extname'] + + That way, you can load an extension called ``extname`` from the subdirectory + ``sphinxext``. + + The configuration file itself can be an extension; for that, you only need + to provide a :func:`setup` function in it. + +.. confval:: source_suffix + + The file extensions of source files. Sphinx considers the files with this + suffix as sources. The value can be a dictionary mapping file extensions + to file types. For example:: + + source_suffix = { + '.rst': 'restructuredtext', + '.txt': 'restructuredtext', + '.md': 'markdown', + } + + By default, Sphinx only supports ``'restructuredtext'`` file type. You can + add a new file type using source parser extensions. Please read a document + of the extension to know which file type the extension supports. + + The value may also be a list of file extensions: then Sphinx will consider + that they all map to the ``'restructuredtext'`` file type. + + Default is ``{'.rst': 'restructuredtext'}``. + + .. note:: file extensions have to start with a dot (e.g. ``.rst``). + + .. versionchanged:: 1.3 + Can now be a list of extensions. + + .. versionchanged:: 1.8 + Support file type mapping + +.. confval:: source_encoding + + The encoding of all reST source files. The recommended encoding, and the + default value, is ``'utf-8-sig'``. + + .. versionadded:: 0.5 + Previously, Sphinx accepted only UTF-8 encoded sources. + +.. confval:: source_parsers + + If given, a dictionary of parser classes for different source suffices. The + keys are the suffix, the values can be either a class or a string giving a + fully-qualified name of a parser class. The parser class can be either + ``docutils.parsers.Parser`` or :class:`sphinx.parsers.Parser`. Files with a + suffix that is not in the dictionary will be parsed with the default + reStructuredText parser. + + For example:: + + source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'} + + .. note:: + + Refer to :doc:`/usage/markdown` for more information on using Markdown + with Sphinx. + + .. 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:: master_doc + + Same as :confval:`root_doc`. + + .. versionchanged:: 4.0 + Renamed ``master_doc`` to ``root_doc``. + +.. confval:: root_doc + + The document name of the "root" document, that is, the document that + contains the root :rst:dir:`toctree` directive. Default is ``'index'``. + + .. versionchanged:: 2.0 + The default is changed to ``'index'`` from ``'contents'``. + .. versionchanged:: 4.0 + Renamed ``root_doc`` from ``master_doc``. + +.. confval:: exclude_patterns + + A list of glob-style patterns [1]_ that should be excluded when looking for + source files. They are matched against the source file names relative + to the source directory, using slashes as directory separators on all + platforms. + + Example patterns: + + - ``'library/xml.rst'`` -- ignores the ``library/xml.rst`` file + - ``'library/xml'`` -- ignores the ``library/xml`` directory + - ``'library/xml*'`` -- ignores all files and directories starting with + ``library/xml`` + - ``'**/.svn'`` -- ignores all ``.svn`` directories + + :confval:`exclude_patterns` is also consulted when looking for static files + in :confval:`html_static_path` and :confval:`html_extra_path`. + + .. versionadded:: 1.0 + +.. confval:: include_patterns + + A list of glob-style patterns [1]_ that are used to find source files. They + are matched against the source file names relative to the source directory, + using slashes as directory separators on all platforms. The default is ``**``, + meaning that all files are recursively included from the source directory. + + Example patterns: + + - ``'**'`` -- all files in the source directory and subdirectories, recursively + - ``'library/xml'`` -- just the ``library/xml`` directory + - ``'library/xml*'`` -- all files and directories starting with ``library/xml`` + - ``'**/doc'`` -- all ``doc`` directories (this might be useful if + documentation is co-located with source files) + + .. versionadded:: 5.1 + +.. confval:: templates_path + + A list of paths that contain extra templates (or templates that overwrite + builtin/theme-specific templates). Relative paths are taken as relative to + the configuration directory. + + .. versionchanged:: 1.3 + As these files are not meant to be built, they are automatically added to + :confval:`exclude_patterns`. + +.. confval:: template_bridge + + 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.) + +.. confval:: rst_epilog + + .. index:: pair: global; substitutions + + A string of reStructuredText that will be included at the end of every source + file that is read. This is a possible place to add substitutions that should + be available in every file (another being :confval:`rst_prolog`). An + example:: + + rst_epilog = """ + .. |psf| replace:: Python Software Foundation + """ + + .. versionadded:: 0.6 + +.. confval:: rst_prolog + + .. index:: pair: global; substitutions + + 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:: + + rst_prolog = """ + .. |psf| replace:: Python Software Foundation + """ + + .. versionadded:: 1.0 + +.. confval:: primary_domain + + .. index:: default; domain + primary; domain + + The name of the default :doc:`domain </usage/restructuredtext/domains>`. + 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"). + + .. versionadded:: 1.0 + +.. confval:: default_role + + .. index:: default; role + + The name of a reST role (builtin or Sphinx extension) to use as the default + role, that is, for text marked up ```like this```. This can be set to + ``'py:obj'`` to make ```filter``` a cross-reference to the Python function + "filter". The default is ``None``, which doesn't reassign the default role. + + The default role can always be set within individual documents using the + standard reST :dudir:`default-role` directive. + + .. versionadded:: 0.4 + +.. confval:: keep_warnings + + If true, keep warnings as "system message" paragraphs in the built + documents. Regardless of this setting, warnings are always written to the + standard error stream when ``sphinx-build`` is run. + + The default is ``False``, the pre-0.5 behavior was to always keep them. + + .. versionadded:: 0.5 + +.. confval:: suppress_warnings + + A list of warning types to suppress arbitrary warning messages. + + Sphinx supports following warning types: + + * ``app.add_node`` + * ``app.add_directive`` + * ``app.add_role`` + * ``app.add_generic_role`` + * ``app.add_source_parser`` + * ``autosectionlabel.*`` + * ``download.not_readable`` + * ``epub.unknown_project_files`` + * ``epub.duplicated_toc_entry`` + * ``i18n.inconsistent_references`` + * ``index`` + * ``image.not_readable`` + * ``ref.term`` + * ``ref.ref`` + * ``ref.numref`` + * ``ref.keyword`` + * ``ref.option`` + * ``ref.citation`` + * ``ref.footnote`` + * ``ref.doc`` + * ``ref.python`` + * ``misc.highlighting_failure`` + * ``toc.circular`` + * ``toc.excluded`` + * ``toc.not_readable`` + * ``toc.secnum`` + + You can choose from these types. You can also give only the first + component to exclude all warnings attached to it. + + Now, this option should be considered *experimental*. + + .. versionadded:: 1.4 + + .. versionchanged:: 1.5 + + Added ``misc.highlighting_failure`` + + .. versionchanged:: 1.5.1 + + Added ``epub.unknown_project_files`` + + .. versionchanged:: 1.6 + + Added ``ref.footnote`` + + .. versionchanged:: 2.1 + + Added ``autosectionlabel.*`` + + .. versionchanged:: 3.3.0 + + Added ``epub.duplicated_toc_entry`` + + .. versionchanged:: 4.3 + + Added ``toc.excluded`` and ``toc.not_readable`` + + .. versionadded:: 4.5 + + Added ``i18n.inconsistent_references`` + + .. versionadded:: 7.1 + + Added ``index`` warning type. + +.. confval:: needs_sphinx + + If set to a ``major.minor`` version string like ``'1.1'``, Sphinx will + compare it with its version and refuse to build if it is too old. Default + is no requirement. + + .. versionadded:: 1.0 + + .. versionchanged:: 1.4 + also accepts micro version string + +.. confval:: needs_extensions + + This value can be a dictionary specifying version requirements for + extensions in :confval:`extensions`, e.g. ``needs_extensions = + {'sphinxcontrib.something': '1.5'}``. The version strings should be in the + form ``major.minor``. Requirements do not have to be specified for all + extensions, only for those you want to check. + + This requires that the extension specifies its version to Sphinx (see + :ref:`dev-extensions` for how to do that). + + .. versionadded:: 1.3 + +.. confval:: manpages_url + + A URL to cross-reference :rst:role:`manpage` roles. If this is + defined to ``https://manpages.debian.org/{path}``, the + :literal:`:manpage:`man(1)`` role will link to + <https://manpages.debian.org/man(1)>. The patterns available are: + + * ``page`` - the manual page (``man``) + * ``section`` - the manual section (``1``) + * ``path`` - the original manual page and section specified (``man(1)``) + + This also supports manpages specified as ``man.1``. + + .. note:: This currently affects only HTML writers but could be + expanded in the future. + + .. versionadded:: 1.7 + +.. confval:: nitpicky + + If true, Sphinx will warn about *all* references where the target cannot be + found. Default is ``False``. You can activate this mode temporarily using + the :option:`-n <sphinx-build -n>` command-line switch. + + .. versionadded:: 1.0 + +.. confval:: nitpick_ignore + + A set or list of ``(type, target)`` tuples (by default empty) that should be + ignored when generating warnings in "nitpicky mode". Note that ``type`` + should include the domain name if present. Example entries would be + ``('py:func', 'int')`` or ``('envvar', 'LD_LIBRARY_PATH')``. + + .. versionadded:: 1.1 + .. versionchanged:: 6.2 + Changed allowable container types to a set, list, or tuple + +.. confval:: nitpick_ignore_regex + + An extended version of :confval:`nitpick_ignore`, which instead interprets + the ``type`` and ``target`` strings as regular expressions. Note, that the + regular expression must match the whole string (as if the ``^`` and ``$`` + markers were inserted). + + For example, ``(r'py:.*', r'foo.*bar\.B.*')`` will ignore nitpicky warnings + for all python entities that start with ``'foo'`` and have ``'bar.B'`` in + them, such as ``('py:const', 'foo_package.bar.BAZ_VALUE')`` or + ``('py:class', 'food.bar.Barman')``. + + .. versionadded:: 4.1 + .. versionchanged:: 6.2 + Changed allowable container types to a set, list, or tuple + +.. confval:: numfig + + 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``. + + .. note:: + + The LaTeX builder always assigns numbers whether this option is enabled + or not. + + .. versionadded:: 1.3 + +.. confval:: numfig_format + + A dictionary mapping ``'figure'``, ``'table'``, ``'code-block'`` and + ``'section'`` to strings that are used for format of figure numbers. + As a special character, ``%s`` will be replaced to figure number. + + Default is to use ``'Fig. %s'`` for ``'figure'``, ``'Table %s'`` for + ``'table'``, ``'Listing %s'`` for ``'code-block'`` and ``'Section %s'`` for + ``'section'``. + + .. versionadded:: 1.3 + +.. confval:: numfig_secnum_depth + + - if set to ``0``, figures, tables and code-blocks are continuously numbered + starting at ``1``. + - if ``1`` (default) numbers will be ``x.1``, ``x.2``, ... with ``x`` + the section number (top level sectioning; no ``x.`` if no section). + This naturally applies only if section numbering has been activated via + the ``:numbered:`` option of the :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... + + .. versionadded:: 1.3 + + .. versionchanged:: 1.7 + The LaTeX builder obeys this setting (if :confval:`numfig` is set to + ``True``). + +.. confval:: smartquotes + + If true, the `Docutils Smart Quotes transform`__, originally based on + `SmartyPants`__ (limited to English) and currently applying to many + languages, will be used to convert quotes and dashes to typographically + correct entities. Default: ``True``. + + __ https://docutils.sourceforge.io/docs/user/smartquotes.html + __ https://daringfireball.net/projects/smartypants/ + + .. 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`.) + + 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. + + __ https://docutils.sourceforge.io/docs/user/config.html + __ https://docutils.sourceforge.io/docs/user/config.html#smart-quotes + +.. confval:: smartquotes_action + + 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:: 1.6.6 + + __ https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/ + +.. confval:: smartquotes_excludes + + This is a ``dict`` whose default is:: + + {'languages': ['ja'], 'builders': ['man', 'text']} + + 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. + + .. 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. + + .. 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: + + .. code-block:: console + + make latex O="-D smartquotes_action=" + + This can follow some ``make html`` with no problem, in contrast to the + situation from the prior note. + + .. versionadded:: 1.6.6 + +.. confval:: user_agent + + A User-Agent of Sphinx. It is used for a header on HTTP access (ex. + linkcheck, intersphinx and so on). Default is ``"Sphinx/X.Y.Z + requests/X.Y.Z python/X.Y.Z"``. + + .. versionadded:: 2.3 + +.. confval:: tls_verify + + If true, Sphinx verifies server certifications. Default is ``True``. + + .. versionadded:: 1.5 + +.. confval:: tls_cacerts + + A path to a certification file of CA or a path to directory which + contains the certificates. This also allows a dictionary mapping + hostname to the path to certificate file. + The certificates are used to verify server certifications. + + .. versionadded:: 1.5 + + .. tip:: Sphinx uses requests_ as a HTTP library internally. + Therefore, Sphinx refers a certification file on the + directory pointed ``REQUESTS_CA_BUNDLE`` environment + variable if ``tls_cacerts`` not set. + + .. _requests: https://requests.readthedocs.io/en/master/ + +.. confval:: today + today_fmt + + These values determine how to format the current date, used as the + replacement for ``|today|``. + + * 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`. + + 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). + +.. confval:: highlight_language + + The default language to highlight source code in. The default is + ``'default'``. It is similar to ``'python3'``; it is mostly a superset of + ``'python'`` but it fallbacks to ``'none'`` without warning if failed. + ``'python3'`` and other languages will emit warning if failed. + + The value should be a valid Pygments lexer name, see + :ref:`code-examples` for more details. + + .. versionadded:: 0.5 + + .. 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 + + 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>`_. + + Example:: + + highlight_options = { + 'default': {'stripall': True}, + 'php': {'startinline': True}, + } + + A single dictionary of options are also allowed. Then it is recognized + as options to the lexer specified by :confval:`highlight_language`:: + + # configuration for the ``highlight_language`` + highlight_options = {'stripall': True} + + .. versionadded:: 1.3 + .. versionchanged:: 3.5 + + Allow to configure highlight options for multiple languages + +.. confval:: pygments_style + + The style name to use for Pygments highlighting of source code. If not set, + either the theme's default style or ``'sphinx'`` is selected for HTML + output. + + .. versionchanged:: 0.3 + If the value is a fully-qualified name of a custom Pygments style class, + this is then used as custom style. + +.. 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 ``None`` (the default), there is no maximum length and the entire + signature will be displayed on a single logical line. + + A 'logical line' is similar to a hard line break---builders or themes may + choose to 'soft wrap' a single logical line, and this setting does not affect + that behaviour. + + Domains may provide options to suppress any hard wrapping on an individual + object directive, such as seen in the C, C++, and Python domains (e.g. + :rst:dir:`py:function:single-line-parameter-list`). + + .. versionadded:: 7.1 + +.. confval:: add_function_parentheses + + A boolean that decides whether parentheses are appended to function and + method role text (e.g. the content of ``:func:`input```) to signify that the + name is callable. Default is ``True``. + +.. confval:: add_module_names + + A boolean that decides whether module names are prepended to all + :term:`object` names (for object types where a "module" of some kind is + defined), e.g. for :rst:dir:`py:function` directives. Default is ``True``. + +.. confval:: toc_object_entries + + Create table of contents entries for domain objects (e.g. functions, classes, + attributes, etc.). Default is ``True``. + +.. confval:: toc_object_entries_show_parents + + A string that determines how domain objects (e.g. functions, classes, + attributes, etc.) are displayed in their table of contents entry. + + Use ``domain`` to allow the domain to determine the appropriate number of + parents to show. For example, the Python domain would show ``Class.method()`` + and ``function()``, leaving out the ``module.`` level of parents. + This is the default setting. + + Use ``hide`` to only show the name of the element without any parents + (i.e. ``method()``). + + Use ``all`` to show the fully-qualified name for the object + (i.e. ``module.Class.method()``), displaying all parents. + + .. versionadded:: 5.2 + +.. confval:: show_authors + + A boolean that decides whether :rst:dir:`codeauthor` and + :rst:dir:`sectionauthor` directives produce any output in the built files. + +.. confval:: modindex_common_prefix + + A list of prefixes that are ignored for sorting the Python module index + (e.g., if this is set to ``['foo.']``, then ``foo.bar`` is shown under ``B``, + not ``F``). This can be handy if you document a project that consists of a + single package. Works only for the HTML builder currently. Default is + ``[]``. + + .. versionadded:: 0.6 + +.. confval:: trim_footnote_reference_space + + Trim spaces before footnote references that are necessary for the reST + parser to recognize the footnote, but do not look too nice in the output. + + .. versionadded:: 0.6 + +.. confval:: trim_doctest_flags + + If true, doctest flags (comments looking like ``# doctest: FLAG, ...``) at + the ends of lines and ``<BLANKLINE>`` markers are removed for all code + blocks showing interactive Python sessions (i.e. doctests). Default is + ``True``. See the extension :mod:`~sphinx.ext.doctest` for more + possibilities of including doctests. + + .. versionadded:: 1.0 + .. versionchanged:: 1.1 + Now also removes ``<BLANKLINE>``. + +.. confval:: strip_signature_backslash + + Default is ``False``. + When backslash stripping is enabled then every occurrence of ``\\`` in a + domain directive will be changed to ``\``, even within string literals. + This was the behaviour before version 3.0, and setting this variable to + ``True`` will reinstate that behaviour. + + .. versionadded:: 3.0 + +.. confval:: option_emphasise_placeholders + + 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. + + .. versionadded:: 5.1 + +.. _intl-options: + +Options for internationalization +-------------------------------- + +These options influence Sphinx's *Native Language Support*. See the +documentation on :ref:`intl` for details. + +.. confval:: language + + The code for the language the docs are written in. Any text automatically + generated by Sphinx will be in that language. Also, Sphinx will try to + substitute individual paragraphs from your documents with the translation + sets obtained from :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:: 0.5 + + .. versionchanged:: 1.4 + + Support figure substitution + + .. versionchanged:: 5.0 + + Currently supported languages by Sphinx are: + + * ``ar`` -- Arabic + * ``bg`` -- Bulgarian + * ``bn`` -- Bengali + * ``ca`` -- Catalan + * ``cak`` -- Kaqchikel + * ``cs`` -- Czech + * ``cy`` -- Welsh + * ``da`` -- Danish + * ``de`` -- German + * ``el`` -- Greek + * ``en`` -- English (default) + * ``eo`` -- Esperanto + * ``es`` -- Spanish + * ``et`` -- Estonian + * ``eu`` -- Basque + * ``fa`` -- Iranian + * ``fi`` -- Finnish + * ``fr`` -- French + * ``he`` -- Hebrew + * ``hi`` -- Hindi + * ``hi_IN`` -- Hindi (India) + * ``hr`` -- Croatian + * ``hu`` -- Hungarian + * ``id`` -- Indonesian + * ``it`` -- Italian + * ``ja`` -- Japanese + * ``ko`` -- Korean + * ``lt`` -- Lithuanian + * ``lv`` -- Latvian + * ``mk`` -- Macedonian + * ``nb_NO`` -- Norwegian Bokmal + * ``ne`` -- Nepali + * ``nl`` -- Dutch + * ``pl`` -- Polish + * ``pt`` -- Portuguese + * ``pt_BR`` -- Brazilian Portuguese + * ``pt_PT`` -- European Portuguese + * ``ro`` -- Romanian + * ``ru`` -- Russian + * ``si`` -- Sinhala + * ``sk`` -- Slovak + * ``sl`` -- Slovenian + * ``sq`` -- Albanian + * ``sr`` -- Serbian + * ``sr@latin`` -- Serbian (Latin) + * ``sr_RS`` -- Serbian (Cyrillic) + * ``sv`` -- Swedish + * ``ta`` -- Tamil + * ``te`` -- Telugu + * ``tr`` -- Turkish + * ``uk_UA`` -- Ukrainian + * ``ur`` -- Urdu + * ``vi`` -- Vietnamese + * ``zh_CN`` -- Simplified Chinese + * ``zh_TW`` -- Traditional Chinese + +.. confval:: locale_dirs + + .. versionadded:: 0.5 + + 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. + + 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`. + + The default is ``['locales']``. + + .. 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 + +.. confval:: gettext_allow_fuzzy_translations + + If true, "fuzzy" messages in the message catalogs are used for translation. + The default is ``False``. + + .. versionadded:: 4.3 + +.. confval:: gettext_compact + + .. versionadded:: 1.1 + + If true, a document's text domain is its docname if it is a top-level + project file and its very base directory otherwise. + + If set to string, all document's text domain is this string, making all + documents use single text domain. + + By default, the document ``markup/code.rst`` ends up in the ``markup`` text + domain. With this option set to ``False``, it is ``markup/code``. + + .. versionchanged:: 3.3 + The string value is now accepted. + +.. confval:: gettext_uuid + + If true, Sphinx generates uuid information for version tracking in message + catalogs. It is used for: + + * Add uid line for each msgids in .pot files. + * Calculate similarity between new msgids and previously saved old msgids. + This calculation takes a long time. + + If you want to accelerate the calculation, you can use + ``python-levenshtein`` 3rd-party package written in C by using + :command:`pip install python-levenshtein`. + + The default is ``False``. + + .. versionadded:: 1.3 + +.. confval:: gettext_location + + If true, Sphinx generates location information for messages in message + catalogs. + + The default is ``True``. + + .. versionadded:: 1.3 + +.. confval:: gettext_auto_build + + If true, Sphinx builds mo file for each translation catalog files. + + The default is ``True``. + + .. versionadded:: 1.3 + +.. confval:: gettext_additional_targets + + To specify names to enable gettext extracting and translation applying for + i18n additionally. You can specify below names: + + :index: index terms + :literal-block: literal blocks (``::`` annotation and ``code-block`` directive) + :doctest-block: doctest block + :raw: raw content + :image: image/figure uri + + For example: ``gettext_additional_targets = ['literal-block', 'image']``. + + The default is ``[]``. + + .. versionadded:: 1.3 + .. versionchanged:: 4.0 + + The alt text for image is translated by default. + +.. confval:: figure_language_filename + + The filename format for language-specific figures. The default value is + ``{root}.{language}{ext}``. It will be expanded to + ``dirname/filename.en.png`` from ``.. image:: dirname/filename.png``. + The available format tokens are: + + * ``{root}`` - the filename, including any path component, without the file + extension, e.g. ``dirname/filename`` + * ``{path}`` - the directory path component of the filename, with a trailing + slash if non-empty, e.g. ``dirname/`` + * ``{docpath}`` - the directory path component for the current document, with + a trailing slash if non-empty. + * ``{basename}`` - the filename without the directory path or file extension + components, e.g. ``filename`` + * ``{ext}`` - the file extension, e.g. ``.png`` + * ``{language}`` - the translation language, e.g. ``en`` + + For example, setting this to ``{path}{language}/{basename}{ext}`` will + expand to ``dirname/en/filename.png`` instead. + + .. versionadded:: 1.4 + + .. versionchanged:: 1.5 + Added ``{path}`` and ``{basename}`` tokens. + + .. versionchanged:: 3.2 + Added ``{docpath}`` token. + +.. confval:: translation_progress_classes + + Control which, if any, classes are added to indicate translation progress. + This setting would likely only be used by translators of documentation, + in order to quickly indicate translated and untranslated content. + + * ``True``: add ``translated`` and ``untranslated`` classes + to all nodes with translatable content. + * ``translated``: only add the ``translated`` class. + * ``untranslated``: only add the ``untranslated`` class. + * ``False``: do not add any classes to indicate translation progress. + + Defaults to ``False``. + + .. versionadded:: 7.1 + +.. _math-options: + +Options for Math +---------------- + +These options influence Math notations. + +.. confval:: math_number_all + + Set this option to ``True`` if you want all displayed math to be numbered. + The default is ``False``. + +.. confval:: math_eqref_format + + A string used for formatting the labels of references to equations. + The ``{number}`` place-holder stands for the equation number. + + Example: ``'Eq.{number}'`` gets rendered as, for example, ``Eq.10``. + +.. confval:: math_numfig + + If ``True``, displayed math equations are numbered across pages when + :confval:`numfig` is enabled. The :confval:`numfig_secnum_depth` setting + is respected. The :rst:role:`eq`, not :rst:role:`numref`, role + must be used to reference equation numbers. Default is ``True``. + + .. versionadded:: 1.7 + + +.. _html-options: + +Options for HTML output +----------------------- + +These options influence HTML as well as HTML Help output, and other builders +that use Sphinx's HTMLWriter class. + +.. confval:: html_theme + + The "theme" that the HTML output should use. See the :doc:`section about + theming </usage/theming>`. The default is ``'alabaster'``. + + .. versionadded:: 0.6 + +.. confval:: html_theme_options + + A dictionary of options that influence the look and feel of the selected + theme. These are theme-specific. For the options understood by the builtin + themes, see :ref:`this section <builtin-themes>`. + + .. versionadded:: 0.6 + +.. confval:: html_theme_path + + A list of paths that contain custom themes, either as subdirectories or as + zip files. Relative paths are taken as relative to the configuration + directory. + + .. versionadded:: 0.6 + +.. confval:: html_style + + 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. + +.. confval:: html_title + + The "title" for HTML documentation generated with Sphinx's own templates. + This is appended to the ``<title>`` tag of individual pages, and used in the + navigation bar as the "topmost" element. It defaults to :samp:`'{<project>} + v{<revision>} documentation'`. + +.. confval:: html_short_title + + A shorter "title" for the HTML docs. This is used for links in the + header and in the HTML Help docs. If not given, it defaults to the value of + :confval:`html_title`. + + .. versionadded:: 0.4 + +.. confval:: html_baseurl + + The base URL which points to the root of the HTML documentation. It is used + to indicate the location of document using `The Canonical Link Relation`_. + Default: ``''``. + + .. _The Canonical Link Relation: https://datatracker.ietf.org/doc/html/rfc6596 + + .. versionadded:: 1.8 + +.. confval:: html_codeblock_linenos_style + + The style of line numbers for code-blocks. + + * ``'table'`` -- display line numbers using ``<table>`` tag + * ``'inline'`` -- display line numbers using ``<span>`` tag (default) + + .. versionadded:: 3.2 + .. versionchanged:: 4.0 + + It defaults to ``'inline'``. + + .. deprecated:: 4.0 + +.. confval:: html_context + + A dictionary of values to pass into the template engine's context for all + pages. Single values can also be put in this dictionary using the + :option:`-A <sphinx-build -A>` command-line option of ``sphinx-build``. + + .. versionadded:: 0.5 + +.. confval:: html_logo + + 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``. + + .. 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. + + .. versionchanged:: 4.0 + Also accepts the URL for the logo file. + +.. confval:: html_favicon + + 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``. + + .. 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. + + .. versionchanged:: 4.0 + Also accepts the URL for the favicon. + +.. 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 ``https://example.org/style.css``. The *attributes* is used + for attributes of ``<link>`` tag. It defaults to an empty list. + + Example:: + + html_css_files = ['custom.css', + 'https://example.com/css/custom.css', + ('print.css', {'media': 'print'})] + + As a special attribute, *priority* can be set as an integer to load the CSS + file earlier or lazier step. For more information, refer + :meth:`.Sphinx.add_css_file()`. + + .. versionadded:: 1.8 + .. versionchanged:: 3.5 + + Support priority attribute + +.. confval:: html_js_files + + A list of JavaScript *filename*. The entry must be a *filename* string or a + tuple containing the *filename* string and the *attributes* dictionary. The + *filename* must be relative to the :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. + + Example:: + + html_js_files = ['script.js', + 'https://example.com/scripts/custom.js', + ('custom.js', {'async': 'async'})] + + As a special attribute, *priority* can be set as an integer to load the CSS + file earlier or lazier step. For more information, refer + :meth:`.Sphinx.add_css_file()`. + + .. versionadded:: 1.8 + .. versionchanged:: 3.5 + + Support priority attribute + +.. confval:: html_static_path + + A list of paths that contain custom static files (such as style + sheets or script files). Relative paths are taken as relative to + the configuration directory. They are copied to the output's + :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. + + .. note:: + + For security reasons, dotfiles under ``html_static_path`` will + not be copied. If you would like to copy them intentionally, please + add each filepath to this setting:: + + html_static_path = ['_static', '_static/.htaccess'] + + Another way to do that, you can also use + :confval:`html_extra_path`. It allows to copy dotfiles under + the directories. + + .. versionchanged:: 0.4 + The paths in :confval:`html_static_path` can now contain subdirectories. + + .. versionchanged:: 1.0 + The entries in :confval:`html_static_path` can now be single files. + + .. versionchanged:: 1.8 + The files under :confval:`html_static_path` are excluded from source + files. + +.. confval:: html_extra_path + + 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. + + 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 + files and directories, and ignores if path matches to patterns. + +.. confval:: html_last_updated_fmt + + 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`. + +.. confval:: html_permalinks + + Add link anchors for each heading and description environment. + Default: ``True``. + + .. versionadded:: 3.5 + +.. confval:: html_permalinks_icon + + Text for link anchors for each heading and description environment. + HTML entities and Unicode are allowed. Default: a paragraph sign; ``¶`` + + .. versionadded:: 3.5 + +.. confval:: html_sidebars + + Custom sidebar templates, must be a dictionary that maps document names to + template names. + + The keys can contain glob-style patterns [1]_, in which case all matching + documents will get the specified sidebars. (A warning is emitted when a + more than one glob-style pattern matches for any document.) + + The values can be either lists or single strings. + + * If a value is a list, it specifies the complete list of sidebar templates + to include. If all or some of the default sidebars are to be included, + they must be put into this list as well. + + The default sidebars (for documents that don't match any pattern) are + defined by theme itself. Builtin themes are using these templates by + default: ``['localtoc.html', 'relations.html', 'sourcelink.html', + 'searchbox.html']``. + + * If a value is a single string, it specifies a custom sidebar to be added + between the ``'sourcelink.html'`` and ``'searchbox.html'`` entries. This + is for compatibility with Sphinx versions before 1.0. + + .. deprecated:: 1.7 + + a single string value for ``html_sidebars`` will be removed in 2.0 + + Builtin sidebar templates that can be rendered are: + + * **localtoc.html** -- a fine-grained table of contents of the current + document + * **globaltoc.html** -- a coarse-grained table of contents for the whole + documentation set, collapsed + * **relations.html** -- two links to the previous and next documents + * **sourcelink.html** -- a link to the source of the current document, if + enabled in :confval:`html_show_sourcelink` + * **searchbox.html** -- the "quick search" box + + Example:: + + html_sidebars = { + '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'], + 'using/windows': ['windowssidebar.html', 'searchbox.html'], + } + + This will render the custom template ``windowssidebar.html`` and the quick + search box within the sidebar of the given document, and render the default + sidebars for all other pages (except that the local TOC is replaced by the + global TOC). + + .. 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. + +.. confval:: html_additional_pages + + Additional templates that should be rendered to HTML pages, must be a + dictionary that maps document names to template names. + + Example:: + + html_additional_pages = { + 'download': 'customdownload.html', + } + + This will render the template ``customdownload.html`` as the page + ``download.html``. + +.. confval:: html_domain_indices + + If true, generate domain-specific indices in addition to the general index. + For e.g. the Python domain, this is the global module index. Default is + ``True``. + + This value can be a bool or a list of index names that should be generated. + To find out the index name for a specific index, look at the HTML file name. + For example, the Python module index has the name ``'py-modindex'``. + + .. versionadded:: 1.0 + +.. confval:: html_use_index + + If true, add an index to the HTML documents. Default is ``True``. + + .. versionadded:: 0.4 + +.. confval:: html_split_index + + If true, the index is generated twice: once as a single page with all the + entries, and once as one page per starting letter. Default is ``False``. + + .. versionadded:: 0.4 + +.. confval:: html_copy_source + + If true, the reST sources are included in the HTML build as + :file:`_sources/{name}`. The default is ``True``. + +.. confval:: html_show_sourcelink + + 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``. + + .. versionadded:: 0.6 + +.. confval:: html_sourcelink_suffix + + Suffix to be appended to source links (see :confval:`html_show_sourcelink`), + unless they have this suffix already. Default is ``'.txt'``. + + .. versionadded:: 1.5 + +.. confval:: html_use_opensearch + + 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 ``''``. + +.. confval:: html_file_suffix + + 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"``. + + .. versionadded:: 0.4 + +.. confval:: html_link_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). + + .. versionadded:: 0.6 + +.. confval:: html_show_copyright + + If true, "(C) Copyright ..." is shown in the HTML footer. Default is + ``True``. + + .. versionadded:: 1.0 + +.. confval:: html_show_search_summary + + If true, the text around the keyword is shown as summary of each search result. + Default is ``True``. + + .. versionadded:: 4.5 + +.. confval:: html_show_sphinx + + If true, "Created using Sphinx" is shown in the HTML footer. Default is + ``True``. + + .. versionadded:: 0.4 + +.. confval:: html_output_encoding + + Encoding of HTML output files. Default is ``'utf-8'``. Note that this + encoding name must both be a valid Python encoding name and a valid HTML + ``charset`` value. + + .. versionadded:: 1.0 + +.. confval:: html_compact_lists + + If true, a list all whose items consist of a single paragraph and/or a + sub-list all whose items etc... (recursive definition) will not use the + ``<p>`` element for any of its items. This is standard docutils behavior. + Default: ``True``. + + .. versionadded:: 1.0 + +.. confval:: html_secnumber_suffix + + Suffix for section numbers. Default: ``". "``. Set to ``" "`` to suppress + the final dot on section numbers. + + .. versionadded:: 1.0 + +.. confval:: html_search_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. + + Support is present for these languages: + + * ``da`` -- Danish + * ``nl`` -- Dutch + * ``en`` -- English + * ``fi`` -- Finnish + * ``fr`` -- French + * ``de`` -- German + * ``hu`` -- Hungarian + * ``it`` -- Italian + * ``ja`` -- Japanese + * ``no`` -- Norwegian + * ``pt`` -- Portuguese + * ``ro`` -- Romanian + * ``ru`` -- Russian + * ``es`` -- Spanish + * ``sv`` -- Swedish + * ``tr`` -- Turkish + * ``zh`` -- Chinese + + .. admonition:: Accelerating build speed + + Each language (except Japanese) provides its own stemming algorithm. + Sphinx uses a Python implementation by default. You can use a C + implementation to accelerate building the index file. + + * `PorterStemmer <https://pypi.org/project/PorterStemmer/>`_ (``en``) + * `PyStemmer <https://pypi.org/project/PyStemmer/>`_ (all languages) + + .. versionadded:: 1.1 + With support for ``en`` and ``ja``. + + .. versionchanged:: 1.3 + Added additional languages. + +.. confval:: html_search_options + + A dictionary with options for the search language support, empty by default. + The meaning of these options depends on the language selected. + + The English support has no options. + + The Japanese support has these options: + + :type: + _`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'. + + .. 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. + +.. confval:: html_search_scorer + + The name of a JavaScript file (relative to the configuration directory) that + implements a search results scorer. If empty, the default will be used. + + .. XXX describe interface for scorer here + + .. versionadded:: 1.2 + +.. confval:: html_scaled_image_link + + If true, image itself links to the original image if it doesn't have + 'target' option or scale related options: 'scale', 'width', 'height'. + The default is ``True``. + + Document authors can disable this feature manually with giving + ``no-scaled-link`` class to the image: + + .. 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 + +.. confval:: html_math_renderer + + The name of math_renderer extension for HTML output. The default is + ``'mathjax'``. + + .. 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 +------------------------------- + +.. confval:: singlehtml_sidebars + + Custom sidebar templates, must be a dictionary that maps document names to + template names. And it only allows a key named `'index'`. All other keys + are ignored. For more information, refer to :confval:`html_sidebars`. By + default, it is same as :confval:`html_sidebars`. + + +.. _htmlhelp-options: + +Options for HTML help output +----------------------------- + +.. confval:: htmlhelp_basename + + Output file base name for HTML help builder. Default is ``'pydoc'``. + +.. confval:: htmlhelp_file_suffix + + This is the file name suffix for generated HTML help files. The + default is ``".html"``. + + .. versionadded:: 2.0 + +.. confval:: htmlhelp_link_suffix + + Suffix for generated links to HTML files. The default is ``".html"``. + + .. versionadded:: 2.0 + + +.. _applehelp-options: + +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. + +.. 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. + + 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_bundle_name + + The basename for the Apple Help Book. Defaults to the :confval:`project` + name. + +.. confval:: applehelp_bundle_id + + The bundle ID for the help book bundle. + + .. warning:: + + You *must* set this value in order to generate Apple Help. + +.. confval:: applehelp_dev_region + + The development region. Defaults to ``'en-us'``, which is Apple’s + recommended setting. + +.. confval:: applehelp_bundle_version + + The bundle version (as a string). Defaults to ``'1'``. + +.. confval:: applehelp_icon + + The help bundle icon file, or ``None`` for no icon. According to Apple's + documentation, this should be a 16-by-16 pixel version of the application's + icon with a transparent background, saved as a PNG file. + +.. confval:: applehelp_kb_product + + The product tag for use with :confval:`applehelp_kb_url`. Defaults to + :samp:`'{<project>}-{<release>}'`. + +.. confval:: applehelp_kb_url + + The URL for your knowledgebase server, + e.g. ``https://example.com/kbsearch.py?p='product'&q='query'&l='lang'``. + Help Viewer will replace the values ``'product'``, ``'query'`` and + ``'lang'`` at runtime with the contents of :confval:`applehelp_kb_product`, + the text entered by the user in the search box and the user's system + language respectively. + + Defaults to ``None`` for no remote search. + +.. confval:: applehelp_remote_url + + The URL for remote content. You can place a copy of your Help Book's + ``Resources`` folder at this location and Help Viewer will attempt to use + it to fetch updated content. + + e.g. if you set it to ``https://example.com/help/Foo/`` and Help Viewer + wants a copy of ``index.html`` for an English speaking customer, it will + look at ``https://example.com/help/Foo/en.lproj/index.html``. + + Defaults to ``None`` for no remote content. + +.. confval:: applehelp_index_anchors + + If ``True``, tell the help indexer to index anchors in the generated HTML. + This can be useful for jumping to a particular topic using the + ``AHLookupAnchor`` function or the ``openHelpAnchor:inBook:`` method in + your code. It also allows you to use ``help:anchor`` URLs; see the Apple + documentation for more information on this topic. + +.. confval:: applehelp_min_term_length + + Controls the minimum term length for the help indexer. Defaults to + ``None``, which means the default will be used. + +.. confval:: applehelp_stopwords + + Either a language specification (to use the built-in stopwords), or the + path to a stopwords plist, or ``None`` if you do not want to use stopwords. + The default stopwords plist can be found at + ``/usr/share/hiutil/Stopwords.plist`` and contains, at time of writing, + stopwords for the following languages: + + ========= ==== + Language Code + ========= ==== + English en + German de + Spanish es + French fr + Swedish sv + Hungarian hu + Italian it + ========= ==== + + Defaults to :confval:`language`, or if that is not set, to ``'en'``. + +.. confval:: applehelp_locale + + Specifies the locale to generate help for. This is used to determine + the name of the ``.lproj`` folder inside the Help Book’s ``Resources``, and + is passed to the help indexer. + + Defaults to :confval:`language`, or if that is not set, to ``'en'``. + +.. confval:: applehelp_title + + Specifies the help book title. Defaults to :samp:`'{<project>} Help'`. + +.. confval:: applehelp_codesign_identity + + Specifies the identity to use for code signing, or ``None`` if code signing + is not to be performed. + + Defaults to the value of the environment variable ``CODE_SIGN_IDENTITY``, + which is set by Xcode for script build phases, or ``None`` if that variable + is not set. + +.. confval:: applehelp_codesign_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, + or the empty list if that variable is not set. + +.. confval:: applehelp_indexer_path + + The path to the :program:`hiutil` program. Defaults to + ``'/usr/bin/hiutil'``. + +.. confval:: applehelp_codesign_path + + The path to the :program:`codesign` program. Defaults to + ``'/usr/bin/codesign'``. + +.. confval:: applehelp_disable_external_tools + + If ``True``, the builder will not run the indexer or the code signing tool, + no matter what other settings are specified. + + This is mainly useful for testing, or where you want to run the Sphinx + build on a non-Mac OS X platform and then complete the final steps on OS X + for some reason. + + Defaults to ``False``. + + +.. _epub-options: + +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/>`_. + +.. confval:: epub_basename + + The basename for the epub file. It defaults to the :confval:`project` name. + +.. confval:: epub_theme + + The HTML theme for the epub output. Since the default themes are not + optimized for small screen space, using the same theme for HTML and epub + output is usually not wise. This defaults to ``'epub'``, a theme designed + to save visual space. + +.. confval:: epub_theme_options + + A dictionary of options that influence the look and feel of the selected + theme. These are theme-specific. For the options understood by the builtin + themes, see :ref:`this section <builtin-themes>`. + + .. versionadded:: 1.2 + +.. confval:: epub_title + + 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. + + .. versionchanged:: 2.0 + It defaults to the ``project`` option. + +.. confval:: epub_description + + The description of the document. The default value is ``'unknown'``. + + .. versionadded:: 1.4 + + .. versionchanged:: 1.5 + Renamed from ``epub3_description`` + +.. confval:: epub_author + + The author of the document. This is put in the Dublin Core metadata. It + defaults to the :confval:`author` option. + +.. confval:: epub_contributor + + The name of a person, organization, etc. that played a secondary role in + the creation of the content of an EPUB Publication. The default value is + ``'unknown'``. + + .. versionadded:: 1.4 + + .. versionchanged:: 1.5 + Renamed from ``epub3_contributor`` + +.. confval:: epub_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. + +.. confval:: epub_publisher + + The publisher of the document. This is put in the Dublin Core metadata. + You may use any sensible string, e.g. the project homepage. The defaults to + the :confval:`author` option. + +.. confval:: epub_copyright + + The copyright of the document. It defaults to the :confval:`copyright` + option but can be set independently for epub creation. + +.. confval:: epub_identifier + + An identifier for the document. This is put in the Dublin Core metadata. + For published documents this is the ISBN number, but you can also use an + alternative scheme, e.g. the project homepage. The default value is + ``'unknown'``. + +.. confval:: epub_scheme + + 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'``. + +.. confval:: epub_uid + + 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'``. + +.. confval:: epub_cover + + The cover page information. This is a tuple containing the filenames of + the cover image and the html template. The rendered html cover page is + inserted as the first item in the spine in :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:: + + 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 + + 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`. + + .. versionadded:: 1.8 + +.. confval:: epub_guide + + 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 `<http://idpf.org/epub>`_ for details. If possible, default entries + for the *cover* and *toc* types are automatically inserted. However, + the types can be explicitly overwritten if the default entries are not + appropriate. Example:: + + epub_guide = (('cover', 'cover.html', 'Cover Page'),) + + The default value is ``()``. + +.. confval:: epub_pre_files + + Additional files that should be inserted before the text generated by + Sphinx. It is a list of tuples containing the file name and the title. + If the title is empty, no entry is added to :file:`toc.ncx`. Example:: + + epub_pre_files = [ + ('index.html', 'Welcome'), + ] + + The default value is ``[]``. + +.. confval:: epub_post_files + + Additional files that should be inserted after the text generated by Sphinx. + It is a list of tuples containing the file name and the title. This option + can be used to add an appendix. If the title is empty, no entry is added + to :file:`toc.ncx`. The default value is ``[]``. + +.. confval:: epub_exclude_files + + A list of files that are generated/copied in the build directory but should + not be included in the epub file. The default value is ``[]``. + +.. confval:: epub_tocdepth + + 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. + +.. confval:: epub_tocdup + + This flag determines if a toc entry is inserted again at the beginning of + its nested toc listing. This allows easier navigation to the top of + a chapter, but can be confusing because it mixes entries of different + depth in one list. The default value is ``True``. + +.. confval:: epub_tocscope + + This setting control the scope of the epub table of contents. The setting + can have the following values: + + * ``'default'`` -- include all toc entries that are not hidden (default) + * ``'includehidden'`` -- include all toc entries + + .. versionadded:: 1.2 + +.. confval:: epub_fix_images + + This flag determines if sphinx should try to fix image formats that are not + supported by some epub readers. At the moment palette images with a small + color table are upgraded. You need Pillow, the Python Image Library, + installed to use this option. The default value is ``False`` because the + automatic conversion may lose information. + + .. versionadded:: 1.2 + +.. confval:: epub_max_image_width + + This option specifies the maximum width of images. If it is set to a value + greater than zero, images with a width larger than the given value are + scaled accordingly. If it is zero, no scaling is performed. The default + value is ``0``. You need the Python Image Library (Pillow) installed to use + this option. + + .. versionadded:: 1.2 + +.. confval:: epub_show_urls + + Control whether to display URL addresses. This is very useful for + readers that have no other means to display the linked URL. The + settings can have the following values: + + * ``'inline'`` -- display URLs inline in parentheses (default) + * ``'footnote'`` -- display URLs in footnotes + * ``'no'`` -- do not display URLs + + The display of inline URLs can be customized by adding CSS rules for the + class ``link-target``. + + .. versionadded:: 1.2 + +.. confval:: epub_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. + + .. versionadded:: 1.2 + +.. confval:: epub_writing_mode + + It specifies writing direction. It can accept ``'horizontal'`` (default) and + ``'vertical'`` + + .. list-table:: + :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. + + .. [#] https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode + + +.. _latex-options: + +Options for LaTeX output +------------------------ + +These options influence LaTeX output. + +.. confval:: latex_engine + + The LaTeX engine to build the docs. The setting can have the following + values: + + * ``'pdflatex'`` -- PDFLaTeX (default) + * ``'xelatex'`` -- XeLaTeX + * ``'lualatex'`` -- LuaLaTeX + * ``'platex'`` -- pLaTeX + * ``'uplatex'`` -- upLaTeX (default if :confval:`language` is ``'ja'``) + + ``'pdflatex'``\ 's support for Unicode characters is limited. + + .. note:: + + 2.0 adds to ``'pdflatex'`` support in Latin language document of + occasional Cyrillic or Greek letters or words. This is not automatic, + see the discussion of the :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. + + .. versionchanged:: 2.1.0 + + 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`. + +.. confval:: latex_documents + + This value determines how to group the document tree into LaTeX source files. + It must be a list of tuples ``(startdocname, targetname, title, author, + theme, toctree_only)``, where the items are: + + *startdocname* + String that specifies the :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.) + + *targetname* + File name of the LaTeX file in the output directory. + + *title* + LaTeX document title. Can be empty to use the title of the *startdoc* + document. This is inserted as LaTeX markup, so special characters like a + backslash or ampersand must be represented by the proper LaTeX commands if + they are to be inserted literally. + + *author* + Author for the LaTeX document. The same LaTeX markup caveat as for *title* + applies. Use ``\\and`` to separate multiple authors, as in: + ``'John \\and Sarah'`` (backslashes must be Python-escaped to reach LaTeX). + + *theme* + LaTeX theme. See :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. + + .. 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. + +.. confval:: latex_logo + + If given, this must be the name of an image file (relative to the + configuration directory) that is the logo of the docs. It is placed at the + top of the title page. Default: ``None``. + +.. confval:: latex_toplevel_sectioning + + This value determines the topmost sectioning unit. It should be chosen from + ``'part'``, ``'chapter'`` or ``'section'``. The default is ``None``; + the topmost + sectioning unit is switched by documentclass: ``section`` is used if + documentclass will be ``howto``, otherwise ``chapter`` will be used. + + Note that if LaTeX uses ``\part`` command, then the numbering of sectioning + units one level deep gets off-sync with HTML numbering, because LaTeX + numbers continuously ``\chapter`` (or ``\section`` for ``howto``.) + + .. versionadded:: 1.4 + +.. confval:: latex_appendices + + A list of document names to append as an appendix to all manuals. + +.. confval:: latex_domain_indices + + If true, generate domain-specific indices in addition to the general index. + For e.g. the Python domain, this is the global module index. Default is + ``True``. + + This value can be a bool or a list of index names that should be generated, + like for :confval:`html_domain_indices`. + + .. versionadded:: 1.0 + +.. confval:: latex_show_pagerefs + + If true, add page references after internal references. This is very useful + for printed copies of the manual. Default is ``False``. + + .. versionadded:: 1.0 + +.. confval:: latex_show_urls + + Control whether to display URL addresses. This is very useful for printed + copies of the manual. The setting can have the following values: + + * ``'no'`` -- do not display URLs (default) + * ``'footnote'`` -- display URLs in footnotes + * ``'inline'`` -- display URLs inline in parentheses + + .. 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. + +.. 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``. + + .. 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. + + .. 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: + + .. 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: + + .. 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. + + .. hint:: + + If you want to use a special colour for the *contents* of the + cells of a given column use ``>{\noindent\color{<color>}}``, + possibly in addition to the above. + + - Multi-row merged cells, whether single column or multi-column + currently ignore any set column, row, or cell colour. + + - It is possible for a simple cell to set a custom colour via the + :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. + + .. hint:: + + In a document not using ``'booktabs'`` globally, it is possible to style + an individual table via the ``booktabs`` class, but it will be necessary + to add ``r'\usepackage{booktabs}'`` to the LaTeX preamble. + + On the other hand one can use ``colorrows`` class for individual tables + with no extra package (as Sphinx since 5.3.0 always loads colortbl_). + + .. _booktabs: https://ctan.org/pkg/booktabs + .. _colortbl: https://ctan.org/pkg/colortbl + .. _xcolor: https://ctan.org/pkg/xcolor + +.. confval:: latex_use_xindy + + 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 + ordered correctly for the :confval:`language`. + + __ http://xindy.sourceforge.net/ + + - This option is ignored if :confval:`latex_engine` is ``'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 ``False`` for ``'pdflatex'`` but ``True`` is + recommended for non-English documents as soon as some indexed + terms use non-ascii characters from the language script. + + Sphinx adds to :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. + + .. versionadded:: 1.8 + +.. confval:: latex_elements + + .. versionadded:: 0.5 + + Its :ref:`documentation <latex_elements_confval>` has moved to :doc:`/latex`. + +.. confval:: latex_docclass + + A dictionary mapping ``'howto'`` and ``'manual'`` to names of real document + classes that will be used as the base for the two Sphinx classes. Default + is to use ``'article'`` for ``'howto'`` and ``'report'`` for ``'manual'``. + + .. versionadded:: 1.0 + + .. versionchanged:: 1.5 + + In Japanese docs (:confval:`language` is ``'ja'``), by default + ``'jreport'`` is used for ``'howto'`` and ``'jsbook'`` for ``'manual'``. + +.. confval:: latex_additional_files + + A list of file names, relative to the configuration directory, to copy to + the build directory when building LaTeX output. This is useful to copy + files that Sphinx doesn't copy automatically, e.g. if they are referenced in + custom LaTeX added in ``latex_elements``. Image files that are referenced + in source files (e.g. via ``.. image::``) are copied automatically. + + You have to make sure yourself that the filenames don't collide with those + of any automatically copied files. + + .. attention:: + + Filenames with extension ``.tex`` will automatically be handed over to + the PDF build process triggered by :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. + + .. versionadded:: 0.6 + + .. versionchanged:: 1.2 + This overrides the files which is provided from Sphinx such as + ``sphinx.sty``. + +.. confval:: latex_theme + + The "theme" that the LaTeX output should use. It is a collection of settings + for LaTeX output (ex. document class, top level sectioning unit and so on). + + As a built-in LaTeX themes, ``manual`` and ``howto`` are bundled. + + ``manual`` + A LaTeX theme for writing a manual. It imports the ``report`` document + class (Japanese documents use ``jsbook``). + + ``howto`` + A LaTeX theme for writing an article. It imports the ``article`` document + class (Japanese documents use ``jreport`` rather). :confval:`latex_appendices` + is available only for this theme. + + It defaults to ``'manual'``. + + .. versionadded:: 3.0 + +.. confval:: latex_theme_options + + A dictionary of options that influence the look and feel of the selected + theme. + + .. versionadded:: 3.1 + +.. confval:: latex_theme_path + + A list of paths that contain custom LaTeX themes as subdirectories. Relative + paths are taken as relative to the configuration directory. + + .. versionadded:: 3.0 + + +.. _text-options: + +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 + + Default: ``'unix'``. + + .. versionadded:: 1.1 + +.. confval:: text_sectionchars + + A string of 7 characters that should be used for underlining sections. + The first character is used for first-level headings, the second for + second-level headings and so on. + + The default is ``'*=-~"+`'``. + + .. versionadded:: 1.1 + +.. confval:: text_add_secnumbers + + A boolean that decides whether section numbers are included in text output. + Default is ``True``. + + .. versionadded:: 1.7 + +.. confval:: text_secnumber_suffix + + Suffix for section numbers in text output. Default: ``". "``. Set to + ``" "`` to suppress the final dot on section numbers. + + .. versionadded:: 1.7 + + +.. _man-options: + +Options for manual page output +------------------------------ + +These options influence manual page output. + +.. confval:: man_pages + + This value determines how to group the document tree into manual pages. It + must be a list of tuples ``(startdocname, name, description, authors, + section)``, where the items are: + + *startdocname* + String that specifies the :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.) + + *name* + Name of the manual page. This should be a short string without spaces or + special characters. It is used to determine the file name as well as the + name of the manual page (in the NAME section). + + *description* + Description of the manual page. This is used in the NAME section. + Can be an empty string if you do not want to automatically generate + the NAME section. + + *authors* + A list of strings with authors, or a single string. Can be an empty + string or list if you do not want to automatically generate an AUTHORS + section in the manual page. + + *section* + The manual page section. Used for the output file name as well as in the + manual page header. + + .. versionadded:: 1.0 + +.. confval:: man_show_urls + + If true, add URL addresses after links. Default is ``False``. + + .. versionadded:: 1.1 + +.. confval:: man_make_section_directory + + If true, make a section directory on build man page. Default is True. + + .. versionadded:: 3.3 + .. versionchanged:: 4.0 + + The default is changed to ``False`` from ``True``. + + .. versionchanged:: 4.0.2 + + The default is changed to ``True`` from ``False`` again. + +.. _texinfo-options: + +Options for Texinfo output +-------------------------- + +These options influence Texinfo output. + +.. confval:: texinfo_documents + + This value determines how to group the document tree into Texinfo source + files. It must be a list of tuples ``(startdocname, targetname, title, + author, dir_entry, description, category, toctree_only)``, where the items + are: + + *startdocname* + String that specifies the :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.) + + *targetname* + File name (no extension) of the Texinfo file in the output directory. + + *title* + Texinfo document title. Can be empty to use the title of the *startdoc* + document. Inserted as Texinfo markup, so special characters like ``@`` and + ``{}`` will need to be escaped to be inserted literally. + + *author* + Author for the Texinfo document. Inserted as Texinfo markup. Use ``@*`` + to separate multiple authors, as in: ``'John@*Sarah'``. + + *dir_entry* + The name that will appear in the top-level ``DIR`` menu file. + + *description* + Descriptive text to appear in the top-level ``DIR`` menu file. + + *category* + Specifies the section which this entry will appear in the top-level + ``DIR`` menu file. + + *toctree_only* + Must be ``True`` or ``False``. If true, the *startdoc* document itself is + not included in the output, only the documents referenced by it via TOC + trees. With this option, you can put extra stuff in the master document + that shows up in the HTML, but not the Texinfo output. + + .. versionadded:: 1.1 + +.. confval:: texinfo_appendices + + 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``. + + This value can be a bool or a list of index names that should be generated, + like for :confval:`html_domain_indices`. + + .. versionadded:: 1.1 + +.. confval:: texinfo_show_urls + + Control how to display URL addresses. + + * ``'footnote'`` -- display URLs in footnotes (default) + * ``'no'`` -- do not display URLs + * ``'inline'`` -- display URLs inline in parentheses + + .. versionadded:: 1.1 + +.. confval:: texinfo_no_detailmenu + + If true, do not generate a ``@detailmenu`` in the "Top" node's menu + containing entries for each sub-node in the document. Default is ``False``. + + .. versionadded:: 1.2 + +.. confval:: texinfo_elements + + A dictionary that contains Texinfo snippets that override those Sphinx + usually puts into the generated ``.texi`` files. + + * Keys that you may want to override include: + + ``'paragraphindent'`` + Number of spaces to indent the first line of each paragraph, default + ``2``. Specify ``0`` for no indentation. + + ``'exampleindent'`` + Number of spaces to indent the lines for examples or literal blocks, + default ``4``. Specify ``0`` for no indentation. + + ``'preamble'`` + Texinfo markup inserted near the beginning of the file. + + ``'copying'`` + Texinfo markup inserted within the ``@copying`` block and displayed + after the title. The default value consists of a simple title page + identifying the project. + + * Keys that are set by other options and therefore should not be overridden + are: + + ``'author'`` + ``'body'`` + ``'date'`` + ``'direntry'`` + ``'filename'`` + ``'project'`` + ``'release'`` + ``'title'`` + + .. versionadded:: 1.1 + +.. confval:: texinfo_cross_references + + If false, do not generate inline references in a document. That makes + an info file more readable with stand-alone reader (``info``). + Default is ``True``. + + .. 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. + +.. confval:: qthelp_basename + + The basename for the qthelp file. It defaults to the :confval:`project` + name. + +.. confval:: qthelp_namespace + + The namespace for the qthelp file. It defaults to + ``org.sphinx.<project_name>.<project_version>``. + +.. confval:: qthelp_theme + + The HTML theme for the qthelp output. + This defaults to ``'nonav'``. + +.. confval:: qthelp_theme_options + + A dictionary of options that influence the look and feel of the selected + theme. These are theme-specific. For the options understood by the builtin + themes, see :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'http://localhost:\d+/'] + + .. versionadded:: 1.1 + +.. confval:: linkcheck_allowed_redirects + + A dictionary that maps a pattern of the source URI to a pattern of the canonical + URI. The linkcheck builder treats the redirected link as "working" when: + + - the link in the document matches the source URI pattern, and + - the redirect location matches the canonical URI pattern. + + Example: + + .. 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/.*' + } + + 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>`. + + .. versionadded:: 4.1 + +.. confval:: linkcheck_request_headers + + A dictionary that maps baseurls to HTTP request headers. + + The key is a URL base string like ``"https://www.sphinx-doc.org/"``. To specify + headers for other hosts, ``"*"`` can be used. It matches all hosts only when + the URL does not match other settings. + + The value is a dictionary that maps header name to its value. + + Example: + + .. code-block:: python + + linkcheck_request_headers = { + "https://www.sphinx-doc.org/": { + "Accept": "text/html", + "Accept-Encoding": "utf-8", + }, + "*": { + "Accept": "text/html,application/xhtml+xml", + } + } + + .. 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 + + A timeout value, in seconds, for the linkcheck builder. The default is to + use Python's global socket timeout. + + .. versionadded:: 1.1 + +.. confval:: linkcheck_workers + + The number of worker threads to use when checking links. Default is 5 + threads. + + .. versionadded:: 1.1 + +.. confval:: linkcheck_anchors + + If true, check the validity of ``#anchor``\ s in links. Since this requires + downloading the whole document, it's considerably slower when enabled. + Default is ``True``. + + .. versionadded:: 1.2 + +.. confval:: linkcheck_anchors_ignore + + A list of regular expressions that match anchors Sphinx should skip when + checking the validity of anchors in links. This allows skipping anchors that + a website's JavaScript adds to control dynamic pages or when triggering an + internal REST request. Default is ``["^!"]``. + + .. tip:: + + Use :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:: + + linkcheck_ignore = [ + 'https://www.sphinx-doc.org/en/1.7/intro.html#', + ] + + .. versionadded:: 1.5 + +.. confval:: linkcheck_anchors_ignore_for_url + + A list or tuple of regular expressions matching URLs + for which Sphinx should not check the validity of anchors. + This allows skipping anchor checks on a per-page basis + while still checking the validity of the page itself. + Default is an empty tuple ``()``. + + .. versionadded:: 7.1 + +.. confval:: linkcheck_auth + + Pass authentication information when doing a ``linkcheck`` build. + + A list of ``(regex_pattern, auth_info)`` tuples where the items are: + + *regex_pattern* + A regular expression that matches a URI. + *auth_info* + Authentication information to use for that URI. The value can be anything + that is understood by the ``requests`` library (see :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. + + Example:: + + linkcheck_auth = [ + ('https://foo\.yourcompany\.com/.+', ('johndoe', 'secret')), + ('https://.+\.yourcompany\.com/.+', HTTPDigestAuth(...)), + ] + + .. versionadded:: 2.3 + +.. confval:: linkcheck_rate_limit_timeout + + The ``linkcheck`` builder may issue a large number of requests to the same + site over a short period of time. This setting controls the builder behavior + when servers indicate that requests are rate-limited. + + If a server indicates when to retry (using the `Retry-After`_ header), + ``linkcheck`` always follows the server indication. + + Otherwise, ``linkcheck`` waits for a minute before to retry and keeps + doubling the wait time between attempts until it succeeds or exceeds the + ``linkcheck_rate_limit_timeout``. By default, the timeout is 5 minutes. + + .. _Retry-After: https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.3 + + .. versionadded:: 3.4 + +.. confval:: linkcheck_exclude_documents + + A list of regular expressions that match documents in which Sphinx should + not check the validity of links. This can be used for permitting link decay + in legacy or historical sections of the documentation. + + Example:: + + # ignore all links in documents located in a subfolder named 'legacy' + linkcheck_exclude_documents = [r'.*/legacy/.*'] + + .. versionadded:: 4.4 + + +Options for the XML builder +--------------------------- + +.. confval:: xml_pretty + + If true, pretty-print the XML. Default is ``True``. + + .. versionadded:: 1.2 + + +.. 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. + + +.. _c-config: + +Options for the C domain +------------------------ + +.. confval:: c_id_attributes + + A list of strings that the parser additionally should accept as attributes. + This can for example be used when attributes have been ``#define`` d for + portability. + + .. versionadded:: 3.0 + +.. confval:: c_paren_attributes + + A list of strings that the parser additionally should accept as attributes + with one argument. That is, if ``my_align_as`` is in the list, then + ``my_align_as(X)`` is parsed as an attribute for all strings ``X`` that have + balanced braces (``()``, ``[]``, and ``{}``). This can for example be used + when attributes have been ``#define`` d for portability. + + .. versionadded:: 3.0 + +.. confval:: c_extra_keywords + + A list of identifiers to be recognized as keywords by the C parser. + It defaults to ``['alignas', 'alignof', 'bool', 'complex', 'imaginary', + 'noreturn', 'static_assert', 'thread_local']``. + + .. versionadded:: 4.0.3 + +.. confval:: c_maximum_signature_line_length + + If a signature's length in characters exceeds the number set, each + parameter will be displayed on an individual logical line. This is a + domain-specific setting, overriding :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + +.. _cpp-config: + +Options for the C++ domain +-------------------------- + +.. confval:: cpp_index_common_prefix + + A list of prefixes that will be ignored when sorting C++ objects in the + global index. For example ``['awesome_lib::']``. + + .. versionadded:: 1.5 + +.. confval:: cpp_id_attributes + + A list of strings that the parser additionally should accept as attributes. + This can for example be used when attributes have been ``#define`` d for + portability. + + .. versionadded:: 1.5 + +.. confval:: cpp_paren_attributes + + A list of strings that the parser additionally should accept as attributes + with one argument. That is, if ``my_align_as`` is in the list, then + ``my_align_as(X)`` is parsed as an attribute for all strings ``X`` that have + balanced braces (``()``, ``[]``, and ``{}``). This can for example be used + when attributes have been ``#define`` d for portability. + + .. versionadded:: 1.5 + +.. 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`. + + .. versionadded:: 7.1 + +Options for the Python domain +----------------------------- + +.. confval:: python_display_short_literal_types + + 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 + + .. py:function:: serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None + + When ``False``, :py:data:`~typing.Literal` types display as per standard + Python syntax, i.e.: + + .. code:: python + + serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None + + When ``True``, :py:data:`~typing.Literal` types display with a short, + :PEP:`604`-inspired syntax, i.e.: + + .. code:: python + + 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 + + If a signature's length in characters exceeds the number set, + each argument or type parameter will be displayed on an individual logical line. + This is a domain-specific setting, + overriding :confval:`maximum_signature_line_length`. + + For the Python domain, the signature length depends on whether + the type parameters or the list of arguments are being formatted. + For the former, the signature length ignores the length of the arguments list; + for the latter, the signature length ignores the length of + the type parameters list. + + For instance, with `python_maximum_signature_line_length = 20`, + only the list of type parameters will be wrapped + while the arguments list will be rendered on a single line + + .. code:: 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:: javascript_maximum_signature_line_length + + If a signature's length in characters exceeds the number set, each + parameter will be displayed on an individual logical line. This is a + domain-specific setting, overriding :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + +Example of configuration file +----------------------------- + +.. literalinclude:: /_static/conf.py.txt + :language: python diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst new file mode 100644 index 0000000..1498ae9 --- /dev/null +++ b/doc/usage/extensions/autodoc.rst @@ -0,0 +1,853 @@ +.. highlight:: rest + +:mod:`sphinx.ext.autodoc` -- Include documentation from docstrings +================================================================== + +.. module:: sphinx.ext.autodoc + :synopsis: Include documentation from docstrings. + +.. index:: pair: automatic; documentation + single: docstring + +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 + 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. + +For this to work, the docstrings must of course be written in correct +reStructuredText. You can then use all of the usual Sphinx markup in the +docstrings, and it will end up correctly in the documentation. Together with +hand-written documentation, this technique eases the pain of having to maintain +two locations for documentation, while at the same time avoiding +auto-generated-looking pure API documentation. + +If you prefer `NumPy`_ or `Google`_ style docstrings over reStructuredText, +you can also enable the :mod:`napoleon <sphinx.ext.napoleon>` extension. +:mod:`napoleon <sphinx.ext.napoleon>` is a preprocessor that converts your +docstrings to correct reStructuredText before :mod:`autodoc` processes them. + +.. _Google: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings +.. _NumPy: https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard + + +Directives +---------- + +:mod:`autodoc` provides several directives that are versions of the usual +:rst:dir:`py:module`, :rst:dir:`py:class` and so forth. On parsing time, they +import the corresponding module and extract the docstring of the given objects, +inserting them into the page source under a suitable :rst:dir:`py:module`, +:rst:dir:`py:class` etc. directive. + +.. note:: + + Just as :rst:dir:`py:class` respects the current :rst:dir:`py:module`, + :rst:dir:`autoclass` will also do so. Likewise, :rst:dir:`automethod` will + respect the current :rst:dir:`py:class`. + + +.. rst:directive:: automodule + autoclass + autoexception + + Document a module, class or exception. All three directives will by default + only insert the docstring of the object itself:: + + .. autoclass:: Noodle + + will produce source like this:: + + .. class:: Noodle + + Noodle's docstring. + + The "auto" directives can also contain content of their own, it will be + inserted into the resulting non-auto directive source after the docstring + (but before any automatic member documentation). + + Therefore, you can also mix automatic and non-automatic member documentation, + like so:: + + .. autoclass:: Noodle + :members: eat, slurp + + .. method:: boil(time=10) + + Boil the noodle *time* minutes. + + .. rubric:: Options + + .. rst:directive:option:: members + :type: no value or comma separated list + + If set, autodoc will generate document for the members of the target + module, class or exception. + + For example:: + + .. automodule:: noodle + :members: + + will document all module members (recursively), and :: + + .. autoclass:: Noodle + :members: + + will document all class member methods and properties. + + By default, autodoc will not generate document for the members that are + private, not having docstrings, inherited from super class, or special + members. + + For modules, ``__all__`` will be respected when looking for members unless + you give the ``ignore-module-all`` flag option. Without + ``ignore-module-all``, the order of the members will also be the order in + ``__all__``. + + You can also give an explicit list of members; only these will then be + documented:: + + .. autoclass:: Noodle + :members: eat, slurp + + .. rst:directive:option:: undoc-members + :type: no value + + If set, autodoc will also generate document for the members not having + docstrings:: + + .. automodule:: noodle + :members: + :undoc-members: + + .. rst:directive:option:: private-members + :type: no value or comma separated list + + If set, autodoc will also generate document for the private members + (that is, those named like ``_private`` or ``__private``):: + + .. automodule:: noodle + :members: + :private-members: + + It can also take an explicit list of member names to be documented as + arguments:: + + .. automodule:: noodle + :members: + :private-members: _spicy, _garlickly + + .. versionadded:: 1.1 + .. versionchanged:: 3.2 + The option can now take arguments. + + .. rst:directive:option:: special-members + :type: no value or comma separated list + + If set, autodoc will also generate document for the special members + (that is, those named like ``__special__``):: + + .. autoclass:: my.Class + :members: + :special-members: + + It can also take an explicit list of member names to be documented as + arguments:: + + .. autoclass:: my.Class + :members: + :special-members: __init__, __name__ + + .. versionadded:: 1.1 + + .. versionchanged:: 1.2 + The option can now take arguments + + **Options and advanced usage** + + * If you want to make the ``members`` option (or other options described + below) the default, see :confval:`autodoc_default_options`. + + .. tip:: + + You can use a negated form, :samp:`'no-{flag}'`, as an option of + autodoc directive, to disable it temporarily. For example:: + + .. automodule:: foo + :no-undoc-members: + + .. tip:: + + You can use autodoc directive options to temporarily override or + extend default options which takes list as an input. For example:: + + .. autoclass:: Noodle + :members: eat + :private-members: +_spicy, _garlickly + + .. versionchanged:: 3.5 + The default options can be overridden or extended temporarily. + + * autodoc considers a member private if its docstring contains + ``:meta private:`` in its :ref:`info-field-lists`. + For example: + + .. code-block:: python + + def my_function(my_arg, my_other_arg): + """blah blah blah + + :meta private: + """ + + .. versionadded:: 3.0 + + * autodoc considers a member public if its docstring contains + ``:meta public:`` in its :ref:`info-field-lists`, even if it starts with + an underscore. + For example: + + .. code-block:: python + + def _my_function(my_arg, my_other_arg): + """blah blah blah + + :meta public: + """ + + .. versionadded:: 3.1 + + * autodoc considers a variable member does not have any default value if its + docstring contains ``:meta hide-value:`` in its :ref:`info-field-lists`. + Example: + + .. code-block:: python + + var1 = None #: :meta hide-value: + + .. versionadded:: 3.5 + + * For classes and exceptions, members inherited from base classes will be + left out when documenting all members, unless you give the + ``inherited-members`` option, in addition to ``members``:: + + .. autoclass:: Noodle + :members: + :inherited-members: + + This can be combined with ``undoc-members`` to document *all* available + members of the class or module. + + It can take an ancestor class not to document inherited members from it. + By default, members of ``object`` class are not documented. To show them + all, give ``None`` to the option. + + For example; If your class ``Foo`` is derived from ``list`` class and + you don't want to document ``list.__len__()``, you should specify a + option ``:inherited-members: list`` to avoid special members of list + class. + + Another example; If your class Foo has ``__str__`` special method and + autodoc directive has both ``inherited-members`` and ``special-members``, + ``__str__`` will be documented as in the past, but other special method + that are not implemented in your class ``Foo``. + + Since v5.0, it can take a comma separated list of ancestor classes. It + allows to suppress inherited members of several classes on the module at + 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. + + .. versionadded:: 0.3 + + .. versionchanged:: 3.0 + + It takes an ancestor class name as an argument. + + .. versionchanged:: 5.0 + + It takes a comma separated list of ancestor class names. + + * It's possible to override the signature for explicitly documented callable + objects (functions, methods, classes) with the regular syntax that will + override the signature gained from introspection:: + + .. autoclass:: Noodle(type) + + .. automethod:: eat(persona) + + This is useful if the signature from the method is hidden by a decorator. + + .. versionadded:: 0.4 + + * The :rst:dir:`automodule`, :rst:dir:`autoclass` and + :rst:dir:`autoexception` directives also support a flag option called + ``show-inheritance``. When given, a list of base classes will be inserted + just below the class signature (when used with :rst:dir:`automodule`, this + will be inserted for every class that is documented in the module). + + .. versionadded:: 0.4 + + * All autodoc directives support the ``no-index`` flag option that has the + same effect as for standard :rst:dir:`py:function` etc. directives: no + index entries are generated for the documented object (and all + autodocumented members). + + .. versionadded:: 0.4 + + * :rst:dir:`automodule` also recognizes the ``synopsis``, ``platform`` and + ``deprecated`` options that the standard :rst:dir:`py:module` directive + supports. + + .. versionadded:: 0.5 + + * :rst:dir:`automodule` and :rst:dir:`autoclass` also has an ``member-order`` + option that can be used to override the global value of + :confval:`autodoc_member_order` for one directive. + + .. versionadded:: 0.6 + + * The directives supporting member documentation also have a + ``exclude-members`` option that can be used to exclude single member names + from documentation, if all members are to be documented. + + .. versionadded:: 0.6 + + * In an :rst:dir:`automodule` directive with the ``members`` option set, only + module members whose ``__module__`` attribute is equal to the module name + as given to ``automodule`` will be documented. This is to prevent + documentation of imported classes or functions. Set the + ``imported-members`` option if you want to prevent this behavior and + document all available members. Note that attributes from imported modules + will not be documented, because attribute documentation is discovered by + parsing the source file of the current module. + + .. versionadded:: 1.2 + + * Add a list of modules in the :confval:`autodoc_mock_imports` to prevent + import errors to halt the building process when some external dependencies + are not importable at build time. + + .. versionadded:: 1.3 + + * As a hint to autodoc extension, you can put a ``::`` separator in between + module name and object name to let autodoc know the correct module name if + it is ambiguous. :: + + .. autoclass:: module.name::Noodle + + * :rst:dir:`autoclass` also recognizes the ``class-doc-from`` option that + can be used to override the global value of :confval:`autoclass_content`. + + .. versionadded:: 4.1 + +.. rst:directive:: autofunction + autodecorator + autodata + automethod + autoattribute + autoproperty + + These work exactly like :rst:dir:`autoclass` etc., + but do not offer the options used for automatic member documentation. + + :rst:dir:`autodata` and :rst:dir:`autoattribute` support the ``annotation`` + option. The option controls how the value of variable is shown. If specified + without arguments, only the name of the variable will be printed, and its value + is not shown:: + + .. autodata:: CD_DRIVE + :annotation: + + If the option specified with arguments, it is printed after the name as a value + of the variable:: + + .. autodata:: CD_DRIVE + :annotation: = your CD device name + + By default, without ``annotation`` option, Sphinx tries to obtain the value of + the variable and print it after the name. + + The ``no-value`` option can be used instead of a blank ``annotation`` to show the + type hint but not the value:: + + .. autodata:: CD_DRIVE + :no-value: + + If both the ``annotation`` and ``no-value`` options are used, ``no-value`` has no + effect. + + For module data members and class attributes, documentation can either be put + into a comment with special formatting (using a ``#:`` to start the comment + instead of just ``#``), or in a docstring *after* the definition. Comments + need to be either on a line of their own *before* the definition, or + immediately after the assignment *on the same line*. The latter form is + restricted to one line only. + + This means that in the following class definition, all attributes can be + autodocumented:: + + class Foo: + """Docstring for class Foo.""" + + #: Doc comment for class attribute Foo.bar. + #: It can have multiple lines. + bar = 1 + + flox = 1.5 #: Doc comment for Foo.flox. One line only. + + baz = 2 + """Docstring for class attribute Foo.baz.""" + + def __init__(self): + #: Doc comment for instance attribute qux. + self.qux = 3 + + self.spam = 4 + """Docstring for instance attribute spam.""" + + .. versionchanged:: 0.6 + :rst:dir:`autodata` and :rst:dir:`autoattribute` can now extract + docstrings. + .. versionchanged:: 1.1 + Comment docs are now allowed on the same line after an assignment. + .. versionchanged:: 1.2 + :rst:dir:`autodata` and :rst:dir:`autoattribute` have an ``annotation`` + option. + .. versionchanged:: 2.0 + :rst:dir:`autodecorator` added. + .. versionchanged:: 2.1 + :rst:dir:`autoproperty` added. + .. versionchanged:: 3.4 + :rst:dir:`autodata` and :rst:dir:`autoattribute` now have a ``no-value`` + option. + + .. note:: + + If you document decorated functions or methods, keep in mind that autodoc + retrieves its docstrings by importing the module and inspecting the + ``__doc__`` attribute of the given function or method. That means that if + a decorator replaces the decorated function with another, it must copy the + original ``__doc__`` to the new function. + + +Configuration +------------- + +There are also config values that you can set: + +.. confval:: autoclass_content + + This value selects what content will be inserted into the main body of an + :rst:dir:`autoclass` directive. The possible values are: + + ``"class"`` + Only the class' docstring is inserted. This is the default. You can + still document ``__init__`` as a separate method using + :rst:dir:`automethod` or the ``members`` option to :rst:dir:`autoclass`. + ``"both"`` + Both the class' and the ``__init__`` method's docstring are concatenated + and inserted. + ``"init"`` + Only the ``__init__`` method's docstring is inserted. + + .. versionadded:: 0.3 + + If the class has no ``__init__`` method or if the ``__init__`` method's + docstring is empty, but the class has a ``__new__`` method's docstring, + it is used instead. + + .. versionadded:: 1.4 + +.. confval:: autodoc_class_signature + + This value selects how the signature will be displayed for the class defined + by :rst:dir:`autoclass` directive. The possible values are: + + ``"mixed"`` + Display the signature with the class name. + ``"separated"`` + Display the signature as a method. + + The default is ``"mixed"``. + + .. versionadded:: 4.1 + +.. confval:: autodoc_member_order + + This value selects if automatically documented members are sorted + alphabetical (value ``'alphabetical'``), by member type (value + ``'groupwise'``) or by source order (value ``'bysource'``). The default is + alphabetical. + + Note that for source order, the module must be a Python module with the + source code available. + + .. versionadded:: 0.6 + .. versionchanged:: 1.0 + Support for ``'bysource'``. + +.. confval:: autodoc_default_flags + + This value is a list of autodoc directive flags that should be automatically + applied to all autodoc directives. The supported flags are ``'members'``, + ``'undoc-members'``, ``'private-members'``, ``'special-members'``, + ``'inherited-members'``, ``'show-inheritance'``, ``'ignore-module-all'`` + and ``'exclude-members'``. + + .. versionadded:: 1.0 + + .. deprecated:: 1.8 + + Integrated into :confval:`autodoc_default_options`. + +.. confval:: autodoc_default_options + + The default options for autodoc directives. They are applied to all autodoc + directives automatically. It must be a dictionary which maps option names + to the values. For example:: + + autodoc_default_options = { + 'members': 'var1, var2', + 'member-order': 'bysource', + 'special-members': '__init__', + 'undoc-members': True, + 'exclude-members': '__weakref__' + } + + Setting ``None`` or ``True`` to the value is equivalent to giving only the + option name to the directives. + + The supported options are ``'members'``, ``'member-order'``, + ``'undoc-members'``, ``'private-members'``, ``'special-members'``, + ``'inherited-members'``, ``'show-inheritance'``, ``'ignore-module-all'``, + ``'imported-members'``, ``'exclude-members'``, ``'class-doc-from'`` and + ``'no-value'``. + + .. versionadded:: 1.8 + + .. versionchanged:: 2.0 + Accepts ``True`` as a value. + + .. versionchanged:: 2.1 + Added ``'imported-members'``. + + .. versionchanged:: 4.1 + Added ``'class-doc-from'``. + + .. versionchanged:: 4.5 + Added ``'no-value'``. + +.. confval:: autodoc_docstring_signature + + Functions imported from C modules cannot be introspected, and therefore the + signature for such functions cannot be automatically determined. However, it + is an often-used convention to put the signature into the first line of the + function's docstring. + + If this boolean value is set to ``True`` (which is the default), autodoc will + look at the first line of the docstring for functions and methods, and if it + looks like a signature, use the line as the signature and remove it from the + docstring content. + + autodoc will continue to look for multiple signature lines, + stopping at the first line that does not look like a signature. + This is useful for declaring overloaded function signatures. + + .. versionadded:: 1.1 + .. versionchanged:: 3.1 + + Support overloaded signatures + + .. versionchanged:: 4.0 + + Overloaded signatures do not need to be separated by a backslash + +.. confval:: autodoc_mock_imports + + This value contains a list of modules to be mocked up. This is useful when + some external dependencies are not met at build time and break the building + process. You may only specify the root package of the dependencies + themselves and omit the sub-modules: + + .. code-block:: python + + autodoc_mock_imports = ["django"] + + Will mock all imports under the ``django`` package. + + .. versionadded:: 1.3 + + .. versionchanged:: 1.6 + This config value only requires to declare the top-level modules that + should be mocked. + +.. confval:: autodoc_typehints + + This value controls how to represent typehints. The setting takes the + following values: + + * ``'signature'`` -- Show typehints in the signature (default) + * ``'description'`` -- Show typehints as content of the function or method + The typehints of overloaded functions or methods will still be represented + in the signature. + * ``'none'`` -- Do not show typehints + * ``'both'`` -- Show typehints in the signature and as content of + the function or method + + Overloaded functions or methods will not have typehints included in the + description because it is impossible to accurately represent all possible + overloads as a list of parameters. + + .. versionadded:: 2.1 + .. versionadded:: 3.0 + + New option ``'description'`` is added. + + .. versionadded:: 4.1 + + New option ``'both'`` is added. + +.. confval:: autodoc_typehints_description_target + + This value controls whether the types of undocumented parameters and return + values are documented when ``autodoc_typehints`` is set to ``description``. + + The default value is ``"all"``, meaning that types are documented for all + parameters and return values, whether they are documented or not. + + When set to ``"documented"``, types will only be documented for a parameter + or a return value that is already documented by the docstring. + + With ``"documented_params"``, parameter types will only be annotated if the + parameter is documented in the docstring. The return type is always + annotated (except if it is ``None``). + + .. versionadded:: 4.0 + + .. versionadded:: 5.0 + + New option ``'documented_params'`` is added. + +.. confval:: autodoc_type_aliases + + A dictionary for users defined `type aliases`__ that maps a type name to the + full-qualified object name. It is used to keep type aliases not evaluated in + the document. Defaults to empty (``{}``). + + The type aliases are only available if your program enables :pep:`Postponed + Evaluation of Annotations (PEP 563) <563>` feature via ``from __future__ import + annotations``. + + For example, there is code using a type alias:: + + from __future__ import annotations + + AliasType = Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]] + + def f() -> AliasType: + ... + + If ``autodoc_type_aliases`` is not set, autodoc will generate internal mark-up + from this code as following:: + + .. py:function:: f() -> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]] + + ... + + If you set ``autodoc_type_aliases`` as + ``{'AliasType': 'your.module.AliasType'}``, it generates the following document + internally:: + + .. py:function:: f() -> your.module.AliasType: + + ... + + .. __: https://mypy.readthedocs.io/en/latest/kinds_of_types.html#type-aliases + .. versionadded:: 3.3 + +.. confval:: autodoc_typehints_format + + This value controls the format of typehints. The setting takes the + following values: + + * ``'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) + + .. versionadded:: 4.4 + + .. versionchanged:: 5.0 + + The default setting was changed to ``'short'`` + +.. confval:: autodoc_preserve_defaults + + If True, the default argument values of functions will be not evaluated on + generating document. It preserves them as is in the source code. + + .. versionadded:: 4.0 + + Added as an experimental feature. This will be integrated into autodoc core + in the future. + +.. confval:: autodoc_warningiserror + + This value controls the behavior of :option:`sphinx-build -W` during + importing modules. + If ``False`` is given, autodoc forcedly suppresses the error if the imported + module emits warnings. By default, ``True``. + +.. confval:: autodoc_inherit_docstrings + + This value controls the docstrings inheritance. + If set to True the docstring for classes or methods, if not explicitly set, + is inherited from parents. + + The default is ``True``. + + .. versionadded:: 1.7 + +.. confval:: suppress_warnings + :no-index: + + :mod:`autodoc` supports to suppress warning messages via + :confval:`suppress_warnings`. It allows following warnings types in + addition: + + * autodoc + * autodoc.import_object + + +Docstring preprocessing +----------------------- + +autodoc provides the following additional events: + +.. event:: autodoc-process-docstring (app, what, name, obj, options, lines) + + .. versionadded:: 0.4 + + Emitted when autodoc has read and processed a docstring. *lines* is a list + of strings -- the lines of the processed docstring -- that the event handler + can modify **in place** to change what Sphinx puts into the output. + + :param app: the Sphinx application object + :param what: the type of the object which the docstring belongs to (one of + ``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``, + ``"attribute"``) + :param name: the fully qualified name of the object + :param obj: the object itself + :param options: the options given to the directive: an object with attributes + ``inherited_members``, ``undoc_members``, ``show_inheritance`` and + ``no-index`` that are true if the flag option of same name was given to the + auto directive + :param lines: the lines of the docstring, see above + +.. event:: autodoc-before-process-signature (app, obj, bound_method) + + .. versionadded:: 2.4 + + Emitted before autodoc formats a signature for an object. The event handler + can modify an object to change its signature. + + :param app: the Sphinx application object + :param obj: the object itself + :param bound_method: a boolean indicates an object is bound method or not + +.. event:: autodoc-process-signature (app, what, name, obj, options, signature, return_annotation) + + .. versionadded:: 0.5 + + Emitted when autodoc has formatted a signature for an object. The event + handler can return a new tuple ``(signature, return_annotation)`` to change + what Sphinx puts into the output. + + :param app: the Sphinx application object + :param what: the type of the object which the docstring belongs to (one of + ``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``, + ``"attribute"``) + :param name: the fully qualified name of the object + :param obj: the object itself + :param options: the options given to the directive: an object with attributes + ``inherited_members``, ``undoc_members``, ``show_inheritance`` and + ``no-index`` that are true if the flag option of same name was given to the + auto directive + :param signature: function signature, as a string of the form + ``"(parameter_1, parameter_2)"``, or ``None`` if introspection didn't + succeed and signature wasn't specified in the directive. + :param return_annotation: function return annotation as a string of the form + ``" -> annotation"``, or ``None`` if there is no return annotation + +The :mod:`sphinx.ext.autodoc` module provides factory functions for commonly +needed docstring processing in event :event:`autodoc-process-docstring`: + +.. autofunction:: cut_lines +.. autofunction:: between + +.. event:: autodoc-process-bases (app, name, obj, options, bases) + + Emitted when autodoc has read and processed a class to determine the + base-classes. *bases* is a list of classes that the event handler can + modify **in place** to change what Sphinx puts into the output. It's + emitted only if ``show-inheritance`` option given. + + :param app: the Sphinx application object + :param name: the fully qualified name of the object + :param obj: the object itself + :param options: the options given to the class directive + :param bases: the list of base classes signature. see above. + + .. 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. + + +Skipping members +---------------- + +autodoc allows the user to define a custom method for determining whether a +member should be included in the documentation by using the following event: + +.. event:: autodoc-skip-member (app, what, name, obj, skip, options) + + .. versionadded:: 0.5 + + Emitted when autodoc has to decide whether a member should be included in the + documentation. The member is excluded if a handler returns ``True``. It is + included if the handler returns ``False``. + + If more than one enabled extension handles the ``autodoc-skip-member`` + event, autodoc will use the first non-``None`` value returned by a handler. + Handlers should return ``None`` to fall back to the skipping behavior of + autodoc and other enabled extensions. + + :param app: the Sphinx application object + :param what: the type of the object which the docstring belongs to (one of + ``"module"``, ``"class"``, ``"exception"``, ``"function"``, ``"method"``, + ``"attribute"``) + :param name: the fully qualified name of the object + :param obj: the object itself + :param skip: a boolean indicating if autodoc will skip this member if the + user handler does not override the decision + :param options: the options given to the directive: an object with attributes + ``inherited_members``, ``undoc_members``, ``show_inheritance`` and + ``no-index`` that are true if the flag option of same name was given to the + auto directive diff --git a/doc/usage/extensions/autosectionlabel.rst b/doc/usage/extensions/autosectionlabel.rst new file mode 100644 index 0000000..b5b9b51 --- /dev/null +++ b/doc/usage/extensions/autosectionlabel.rst @@ -0,0 +1,56 @@ +.. highlight:: rest + +:mod:`sphinx.ext.autosectionlabel` -- Allow reference sections using its title +============================================================================== + +.. module:: sphinx.ext.autosectionlabel + :synopsis: Allow reference section its title. + +.. versionadded:: 1.4 + +This extension allows you to refer sections its title. This affects to the +reference role (:rst:role:`ref`). + +For example:: + + A Plain Title + ------------- + + This is the text of the section. + + It refers to the section title, see :ref:`A Plain Title`. + + +Internally, this extension generates the labels for each section. If same +section names are used in whole of document, any one is used for a target by +default. The ``autosectionlabel_prefix_document`` configuration variable can be +used to make headings which appear multiple times but in different documents +unique. + + +Configuration +------------- + +.. confval:: autosectionlabel_prefix_document + + True to prefix each section label with the name of the document it is in, + followed by a colon. For example, ``index:Introduction`` for a section + called ``Introduction`` that appears in document ``index.rst``. Useful for + avoiding ambiguity when the same section heading appears in different + documents. + +.. confval:: autosectionlabel_maxdepth + + If set, autosectionlabel chooses the sections for labeling by its depth. For + example, when set 1 to ``autosectionlabel_maxdepth``, labels are generated + only for top level sections, and deeper sections are not labeled. It + defaults to ``None`` (disabled). + + +Debugging +--------- + +The ``WARNING: undefined label`` indicates that your reference in +:rst:role:`ref` is mis-spelled. Invoking :program:`sphinx-build` with ``-vv`` +(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 new file mode 100644 index 0000000..a18460b --- /dev/null +++ b/doc/usage/extensions/autosummary.rst @@ -0,0 +1,364 @@ +.. highlight:: rest + +:mod:`sphinx.ext.autosummary` -- Generate autodoc summaries +=========================================================== + +.. module:: sphinx.ext.autosummary + :synopsis: Generate autodoc summaries + +.. versionadded:: 0.6 + +This extension generates function/method/attribute summary lists, similar to +those output e.g. by Epydoc and other API doc generation tools. This is +especially useful when your docstrings are long and detailed, and putting each +one of them on a separate page makes them easier to read. + +The :mod:`sphinx.ext.autosummary` extension does this in two parts: + +1. There is an :rst:dir:`autosummary` directive for generating summary listings + that contain links to the documented items, and short summary blurbs + extracted from their docstrings. + +2. A :rst:dir:`autosummary` directive also generates short "stub" files for the + entries listed in its content. These files by default contain only the + corresponding :mod:`sphinx.ext.autodoc` directive, but can be customized with + templates. + + The :program:`sphinx-autogen` script is also able to generate "stub" files + from command line. + +.. rst:directive:: autosummary + + Insert a table that contains links to documented items, and a short summary + blurb (the first sentence of the docstring) for each of them. + + The :rst:dir:`autosummary` directive can also optionally serve as a + :rst:dir:`toctree` entry for the included items. Optionally, stub + ``.rst`` files for these items can also be automatically generated + when :confval:`autosummary_generate` is `True`. + + For example, :: + + .. currentmodule:: sphinx + + .. autosummary:: + + environment.BuildEnvironment + util.relative_uri + + produces a table like this: + + .. currentmodule:: sphinx + + .. autosummary:: + + environment.BuildEnvironment + util.relative_uri + + .. currentmodule:: sphinx.ext.autosummary + + Autosummary preprocesses the docstrings and signatures with the same + :event:`autodoc-process-docstring` and :event:`autodoc-process-signature` + hooks as :mod:`~sphinx.ext.autodoc`. + + **Options** + + * If you want the :rst:dir:`autosummary` table to also serve as a + :rst:dir:`toctree` entry, use the ``toctree`` option, for example:: + + .. autosummary:: + :toctree: DIRNAME + + sphinx.environment.BuildEnvironment + sphinx.util.relative_uri + + The ``toctree`` option also signals to the :program:`sphinx-autogen` script + that stub pages should be generated for the entries listed in this + directive. The option accepts a directory name as an argument; + :program:`sphinx-autogen` will by default place its output in this + directory. If no argument is given, output is placed in the same directory + as the file that contains the directive. + + You can also use ``caption`` option to give a caption to the toctree. + + .. versionadded:: 3.1 + + caption option added. + + * If you don't want the :rst:dir:`autosummary` to show function signatures in + the listing, include the ``nosignatures`` option:: + + .. autosummary:: + :nosignatures: + + sphinx.environment.BuildEnvironment + sphinx.util.relative_uri + + * You can specify a custom template with the ``template`` option. + For example, :: + + .. autosummary:: + :template: mytemplate.rst + + sphinx.environment.BuildEnvironment + + would use the template :file:`mytemplate.rst` in your + :confval:`templates_path` to generate the pages for all entries + listed. See `Customizing templates`_ below. + + .. versionadded:: 1.0 + + * You can specify the ``recursive`` option to generate documents for + modules and sub-packages recursively. It defaults to disabled. + For example, :: + + .. autosummary:: + :recursive: + + sphinx.environment.BuildEnvironment + + .. versionadded:: 3.1 + + +:program:`sphinx-autogen` -- generate autodoc stub pages +-------------------------------------------------------- + +The :program:`sphinx-autogen` script can be used to conveniently generate stub +documentation pages for items included in :rst:dir:`autosummary` listings. + +For example, the command :: + + $ sphinx-autogen -o generated *.rst + +will read all :rst:dir:`autosummary` tables in the :file:`*.rst` files that have +the ``:toctree:`` option set, and output corresponding stub pages in directory +``generated`` for all documented items. The generated pages by default contain +text of the form:: + + sphinx.util.relative_uri + ======================== + + .. autofunction:: sphinx.util.relative_uri + +If the ``-o`` option is not given, the script will place the output files in the +directories specified in the ``:toctree:`` options. + +For more information, refer to the :doc:`sphinx-autogen documentation +</man/sphinx-autogen>` + + +Generating stub pages automatically +----------------------------------- + +If you do not want to create stub pages with :program:`sphinx-autogen`, you can +also use these config values: + +.. confval:: autosummary_context + + A dictionary of values to pass into the template engine's context for + autosummary stubs files. + + .. versionadded:: 3.1 + +.. confval:: autosummary_generate + + Boolean indicating whether to scan all found documents for autosummary + directives, and to generate stub pages for each. It is enabled by default. + + Can also be a list of documents for which stub pages should be generated. + + The new files will be placed in the directories specified in the + ``:toctree:`` options of the directives. + + .. versionchanged:: 2.3 + + Emits :event:`autodoc-skip-member` event as :mod:`~sphinx.ext.autodoc` + does. + + .. versionchanged:: 4.0 + + Enabled by default. + +.. confval:: autosummary_generate_overwrite + + If true, autosummary overwrites existing files by generated stub pages. + Defaults to true (enabled). + + .. versionadded:: 3.0 + +.. confval:: autosummary_mock_imports + + This value contains a list of modules to be mocked up. See + :confval:`autodoc_mock_imports` for more details. It defaults to + :confval:`autodoc_mock_imports`. + + .. versionadded:: 2.0 + +.. confval:: autosummary_imported_members + + A boolean flag indicating whether to document classes and functions imported + in modules. Default is ``False`` + + .. versionadded:: 2.1 + + .. versionchanged:: 4.4 + + If ``autosummary_ignore_module_all`` is ``False``, this configuration + value is ignored for members listed in ``__all__``. + +.. confval:: autosummary_ignore_module_all + + If ``False`` and a module has the ``__all__`` attribute set, autosummary + documents every member listed in ``__all__`` and no others. Default is + ``True`` + + Note that if an imported member is listed in ``__all__``, it will be + documented regardless of the value of ``autosummary_imported_members``. To + match the behaviour of ``from module import *``, set + ``autosummary_ignore_module_all`` to False and + ``autosummary_imported_members`` to True. + + .. versionadded:: 4.4 + +.. confval:: autosummary_filename_map + + A dict mapping object names to filenames. This is necessary to avoid + filename conflicts where multiple objects have names that are + indistinguishable when case is ignored, on file systems where filenames + are case-insensitive. + + .. versionadded:: 3.2 + +.. _autosummary-customizing-templates: + +Customizing templates +--------------------- + +.. versionadded:: 1.0 + +You can customize the stub page templates, in a similar way as the HTML Jinja +templates, see :ref:`templating`. (:class:`~sphinx.application.TemplateBridge` +is not supported.) + +.. note:: + + If you find yourself spending much time tailoring the stub templates, this + may indicate that it's a better idea to write custom narrative documentation + instead. + +Autosummary uses the following Jinja template files: + +- :file:`autosummary/base.rst` -- fallback template +- :file:`autosummary/module.rst` -- template for modules +- :file:`autosummary/class.rst` -- template for classes +- :file:`autosummary/function.rst` -- template for functions +- :file:`autosummary/attribute.rst` -- template for class attributes +- :file:`autosummary/method.rst` -- template for class methods + +The following variables are available in the templates: + +.. currentmodule:: None + +.. data:: name + + Name of the documented object, excluding the module and class parts. + +.. data:: objname + + Name of the documented object, excluding the module parts. + +.. data:: fullname + + Full name of the documented object, including module and class parts. + +.. data:: objtype + + Type of the documented object, one of ``"module"``, ``"function"``, + ``"class"``, ``"method"``, ``"attribute"``, ``"data"``, ``"object"``, + ``"exception"``, ``"newvarattribute"``, ``"newtypedata"``, ``"property"``. + +.. data:: module + + Name of the module the documented object belongs to. + +.. data:: class + + Name of the class the documented object belongs to. Only available for + methods and attributes. + +.. data:: underline + + A string containing ``len(full_name) * '='``. Use the ``underline`` filter + instead. + +.. data:: members + + List containing names of all members of the module or class. Only available + for modules and classes. + +.. data:: inherited_members + + List containing names of all inherited members of class. Only available for + classes. + + .. versionadded:: 1.8.0 + +.. data:: functions + + List containing names of "public" functions in the module. Here, "public" + means that the name does not start with an underscore. Only available + for modules. + +.. data:: classes + + List containing names of "public" classes in the module. Only available for + modules. + +.. data:: exceptions + + List containing names of "public" exceptions in the module. Only available + for modules. + +.. data:: methods + + List containing names of "public" methods in the class. Only available for + classes. + +.. data:: attributes + + List containing names of "public" attributes in the class/module. Only + available for classes and modules. + + .. versionchanged:: 3.1 + + Attributes of modules are supported. + +.. data:: modules + + List containing names of "public" modules in the package. Only available for + modules that are packages and the ``recursive`` option is on. + + .. versionadded:: 3.1 + +Additionally, the following filters are available + +.. function:: escape(s) + + Escape any special characters in the text to be used in formatting RST + contexts. For instance, this prevents asterisks making things bold. This + replaces the builtin Jinja `escape filter`_ that does html-escaping. + +.. function:: underline(s, line='=') + :no-index: + + Add a title underline to a piece of text. + +For instance, ``{{ fullname | escape | underline }}`` should be used to produce +the title of a page. + +.. note:: + + You can use the :rst:dir:`autosummary` directive in the stub pages. + Stub pages are generated also based on these directives. + +.. _`escape filter`: https://jinja.palletsprojects.com/en/3.0.x/templates/#jinja-filters.escape diff --git a/doc/usage/extensions/coverage.rst b/doc/usage/extensions/coverage.rst new file mode 100644 index 0000000..1390ebf --- /dev/null +++ b/doc/usage/extensions/coverage.rst @@ -0,0 +1,99 @@ +:mod:`sphinx.ext.coverage` -- Collect doc coverage stats +======================================================== + +.. module:: sphinx.ext.coverage + :synopsis: Check Python modules and C API for coverage in the documentation. + +This extension features one additional builder, the :class:`CoverageBuilder`. + +.. class:: CoverageBuilder + + To use this builder, activate the coverage extension in your configuration + file and give ``-b coverage`` on the command line. + +.. todo:: Write this section. + +Several configuration values can be used to specify what the builder +should check: + +.. confval:: coverage_ignore_modules + +.. confval:: coverage_ignore_functions + +.. confval:: coverage_ignore_classes + +.. confval:: coverage_ignore_pyobjects + + List of `Python regular expressions`_. + + If any of these regular expressions matches any part of the full import path + of a Python object, that Python object is excluded from the documentation + coverage report. + + .. _Python regular expressions: https://docs.python.org/library/re + + .. versionadded:: 2.1 + +.. confval:: coverage_c_path + +.. confval:: coverage_c_regexes + +.. confval:: coverage_ignore_c_items + +.. confval:: coverage_write_headline + + Set to ``False`` to not write headlines. + + .. versionadded:: 1.1 + +.. confval:: coverage_skip_undoc_in_source + + Skip objects that are not documented in the source with a docstring. + ``False`` by default. + + .. versionadded:: 1.1 + +.. confval:: coverage_show_missing_items + + Print objects that are missing to standard output also. + ``False`` by default. + + .. versionadded:: 3.1 + +.. confval:: coverage_statistics_to_report + + Print a tabluar report of the coverage statistics to the coverage report. + ``True`` by default. + + Example output: + + .. code-block:: text + + +-----------------------+----------+--------------+ + | Module | Coverage | Undocumented | + +=======================+==========+==============+ + | package.foo_module | 100.00% | 0 | + +-----------------------+----------+--------------+ + | package.bar_module | 83.33% | 1 | + +-----------------------+----------+--------------+ + + .. versionadded:: 7.2 + +.. confval:: coverage_statistics_to_stdout + + Print a tabluar report of the coverage statistics to standard output. + ``False`` by default. + + Example output: + + .. code-block:: text + + +-----------------------+----------+--------------+ + | Module | Coverage | Undocumented | + +=======================+==========+==============+ + | package.foo_module | 100.00% | 0 | + +-----------------------+----------+--------------+ + | package.bar_module | 83.33% | 1 | + +-----------------------+----------+--------------+ + + .. versionadded:: 7.2 diff --git a/doc/usage/extensions/doctest.rst b/doc/usage/extensions/doctest.rst new file mode 100644 index 0000000..1848e1f --- /dev/null +++ b/doc/usage/extensions/doctest.rst @@ -0,0 +1,385 @@ +.. highlight:: rest + +:mod:`sphinx.ext.doctest` -- Test snippets in the documentation +=============================================================== + +.. module:: sphinx.ext.doctest + :synopsis: Test snippets in the documentation. + +.. index:: pair: automatic; testing + single: doctest + pair: testing; snippets + + +It is often helpful to include snippets of code in your documentation and +demonstrate the results of executing them. But it is important to ensure that +the documentation stays up-to-date with the code. + +This extension allows you to test such code snippets in the documentation in +a natural way. If you mark the code blocks as shown here, the ``doctest`` +builder will collect them and run them as doctest tests. + +Within each document, you can assign each snippet to a *group*. Each group +consists of: + +* zero or more *setup code* blocks (e.g. importing the module to test) +* one or more *test* blocks + +When building the docs with the ``doctest`` builder, groups are collected for +each document and run one after the other, first executing setup code blocks, +then the test blocks in the order they appear in the file. + +There are two kinds of test blocks: + +* *doctest-style* blocks mimic interactive sessions by interleaving Python code + (including the interpreter prompt) and output. + +* *code-output-style* blocks consist of an ordinary piece of Python code, and + optionally, a piece of output for that code. + + +Directives +---------- + +The *group* argument below is interpreted as follows: if it is empty, the block +is assigned to the group named ``default``. If it is ``*``, the block is +assigned to all groups (including the ``default`` group). Otherwise, it must be +a comma-separated list of group names. + +.. rst:directive:: .. testsetup:: [group] + + A setup code block. This code is not shown in the output for other builders, + but executed before the doctests of the group(s) it belongs to. + + +.. rst:directive:: .. testcleanup:: [group] + + A cleanup code block. This code is not shown in the output for other + builders, but executed after the doctests of the group(s) it belongs to. + + .. versionadded:: 1.1 + + +.. rst:directive:: .. doctest:: [group] + + A doctest-style code block. You can use standard :mod:`doctest` flags for + controlling how actual output is compared with what you give as output. The + default set of flags is specified by the :confval:`doctest_default_flags` + configuration variable. + + This directive supports five options: + + * ``hide``, a flag option, hides the doctest block in other builders. By + default it is shown as a highlighted doctest block. + + * ``options``, a string option, can be used to give a comma-separated list of + doctest flags that apply to each example in the tests. (You still can give + explicit flags per example, with doctest comments, but they will show up in + other builders too.) + + * ``pyversion``, a string option, can be used to specify the required Python + version for the example to be tested. For instance, in the following case + the example will be tested only for Python versions greater than 3.10:: + + .. doctest:: + :pyversion: > 3.10 + + The following operands are supported: + + * ``~=``: Compatible release clause + * ``==``: Version matching clause + * ``!=``: Version exclusion clause + * ``<=``, ``>=``: Inclusive ordered comparison clause + * ``<``, ``>``: Exclusive ordered comparison clause + * ``===``: Arbitrary equality clause. + + ``pyversion`` option is followed :pep:`PEP-440: Version Specifiers + <440#version-specifiers>`. + + .. versionadded:: 1.6 + + .. versionchanged:: 1.7 + + Supported PEP-440 operands and notations + + * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option, + doctest flags (comments looking like ``# doctest: FLAG, ...``) at the + ends of lines and ``<BLANKLINE>`` markers are removed (or not removed) + individually. Default is ``trim-doctest-flags``. + + Note that like with standard doctests, you have to use ``<BLANKLINE>`` to + signal a blank line in the expected output. The ``<BLANKLINE>`` is removed + when building presentation output (HTML, LaTeX etc.). + + Also, you can give inline doctest options, like in doctest:: + + >>> datetime.date.now() # doctest: +SKIP + datetime.date(2008, 1, 1) + + They will be respected when the test is run, but stripped from presentation + output. + + +.. rst:directive:: .. testcode:: [group] + + A code block for a code-output-style test. + + This directive supports three options: + + * ``hide``, a flag option, hides the code block in other builders. By + default it is shown as a highlighted code block. + + * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option, + doctest flags (comments looking like ``# doctest: FLAG, ...``) at the + ends of lines and ``<BLANKLINE>`` markers are removed (or not removed) + individually. Default is ``trim-doctest-flags``. + + .. note:: + + Code in a ``testcode`` block is always executed all at once, no matter how + many statements it contains. Therefore, output will *not* be generated + for bare expressions -- use ``print``. Example:: + + .. testcode:: + + 1+1 # this will give no output! + print(2+2) # this will give output + + .. testoutput:: + + 4 + + Also, please be aware that since the doctest module does not support + mixing regular output and an exception message in the same snippet, this + applies to testcode/testoutput as well. + + +.. rst:directive:: .. testoutput:: [group] + + The corresponding output, or the exception message, for the last + :rst:dir:`testcode` block. + + This directive supports four options: + + * ``hide``, a flag option, hides the output block in other builders. By + default it is shown as a literal block without highlighting. + + * ``options``, a string option, can be used to give doctest flags + (comma-separated) just like in normal doctest blocks. + + * ``trim-doctest-flags`` and ``no-trim-doctest-flags``, a flag option, + doctest flags (comments looking like ``# doctest: FLAG, ...``) at the + ends of lines and ``<BLANKLINE>`` markers are removed (or not removed) + individually. Default is ``trim-doctest-flags``. + + Example:: + + .. testcode:: + + print('Output text.') + + .. testoutput:: + :hide: + :options: -ELLIPSIS, +NORMALIZE_WHITESPACE + + Output text. + +The following is an example for the usage of the directives. The test via +:rst:dir:`doctest` and the test via :rst:dir:`testcode` and +:rst:dir:`testoutput` are equivalent. :: + + The parrot module + ================= + + .. testsetup:: * + + import parrot + + The parrot module is a module about parrots. + + Doctest example: + + .. doctest:: + + >>> parrot.voom(3000) + This parrot wouldn't voom if you put 3000 volts through it! + + Test-Output example: + + .. testcode:: + + parrot.voom(3000) + + This would output: + + .. testoutput:: + + This parrot wouldn't voom if you put 3000 volts through it! + + +Skipping tests conditionally +---------------------------- + +``skipif``, a string option, can be used to skip directives conditionally. This +may be useful e.g. when a different set of tests should be run depending on the +environment (hardware, network/VPN, optional dependencies or different versions +of dependencies). The ``skipif`` option is supported by all of the doctest +directives. Below are typical use cases for ``skipif`` when used for different +directives: + +- :rst:dir:`testsetup` and :rst:dir:`testcleanup` + + - conditionally skip test setup and/or cleanup + - customize setup/cleanup code per environment + +- :rst:dir:`doctest` + + - conditionally skip both a test and its output verification + +- :rst:dir:`testcode` + + - conditionally skip a test + - customize test code per environment + +- :rst:dir:`testoutput` + + - conditionally skip output assertion for a skipped test + - expect different output depending on the environment + +The value of the ``skipif`` option is evaluated as a Python expression. If the +result is a true value, the directive is omitted from the test run just as if +it wasn't present in the file at all. + +Instead of repeating an expression, the :confval:`doctest_global_setup` +configuration option can be used to assign it to a variable which can then be +used instead. + +Here's an example which skips some tests if Pandas is not installed: + +.. code-block:: py + :caption: conf.py + + extensions = ['sphinx.ext.doctest'] + doctest_global_setup = ''' + try: + import pandas as pd + except ImportError: + pd = None + ''' + +.. code-block:: rst + :caption: contents.rst + + .. testsetup:: + :skipif: pd is None + + data = pd.Series([42]) + + .. doctest:: + :skipif: pd is None + + >>> data.iloc[0] + 42 + + .. testcode:: + :skipif: pd is None + + print(data.iloc[-1]) + + .. testoutput:: + :skipif: pd is None + + 42 + + +Configuration +------------- + +The doctest extension uses the following configuration values: + +.. confval:: doctest_default_flags + + By default, these options are enabled: + + - ``ELLIPSIS``, allowing you to put ellipses in the expected output that + match anything in the actual output; + - ``IGNORE_EXCEPTION_DETAIL``, causing everything following the leftmost + colon and any module information in the exception name to be ignored; + - ``DONT_ACCEPT_TRUE_FOR_1``, rejecting "True" in the output where "1" is + given -- the default behavior of accepting this substitution is a relic of + pre-Python 2.2 times. + + .. versionadded:: 1.5 + +.. confval:: doctest_show_successes + + Defaults to ``True``. + Controls whether successes are reported. + + For a project with many doctests, + it may be useful to set this to ``False`` to only highlight failures. + + .. versionadded:: 7.2 + +.. confval:: doctest_path + + A list of directories that will be added to :data:`sys.path` when the doctest + builder is used. (Make sure it contains absolute paths.) + +.. confval:: doctest_global_setup + + Python code that is treated like it were put in a ``testsetup`` directive for + *every* file that is tested, and for every group. You can use this to + e.g. import modules you will always need in your doctests. + + .. versionadded:: 0.6 + +.. confval:: doctest_global_cleanup + + Python code that is treated like it were put in a ``testcleanup`` directive + for *every* file that is tested, and for every group. You can use this to + e.g. remove any temporary files that the tests leave behind. + + .. versionadded:: 1.1 + +.. 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. + + reST doctest blocks are simply doctests put into a paragraph of their own, + like so:: + + Some documentation text. + + >>> print(1) + 1 + + Some more documentation text. + + (Note that no special ``::`` is used to introduce a doctest block; docutils + recognizes them from the leading ``>>>``. Also, no additional indentation is + used, though it doesn't hurt.) + + If this value is left at its default value, the above snippet is interpreted + by the doctest builder exactly like the following:: + + Some documentation text. + + .. doctest:: + + >>> print(1) + 1 + + Some more documentation text. + + This feature makes it easy for you to test doctests in docstrings included + 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 + :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/duration.rst b/doc/usage/extensions/duration.rst new file mode 100644 index 0000000..1213811 --- /dev/null +++ b/doc/usage/extensions/duration.rst @@ -0,0 +1,11 @@ +:mod:`sphinx.ext.duration` -- Measure durations of Sphinx processing +==================================================================== + +.. module:: sphinx.ext.duration + :synopsis: Measure durations of Sphinx processing + +.. versionadded:: 2.4 + +This extension measures durations of Sphinx processing and show its +result at end of the build. It is useful for inspecting what document +is slowly built. diff --git a/doc/usage/extensions/example_google.py b/doc/usage/extensions/example_google.py new file mode 100644 index 0000000..434fa3b --- /dev/null +++ b/doc/usage/extensions/example_google.py @@ -0,0 +1,309 @@ +"""Example Google style docstrings. + +This module demonstrates documentation as specified by the `Google Python +Style Guide`_. Docstrings may extend over multiple lines. Sections are created +with a section header and a colon followed by a block of indented text. + +Example: + Examples can be given using either the ``Example`` or ``Examples`` + sections. Sections support any reStructuredText formatting, including + literal blocks:: + + $ python example_google.py + +Section breaks are created by resuming unindented text. Section breaks +are also implicitly created anytime a new section starts. + +Attributes: + module_level_variable1 (int): Module level variables may be documented in + either the ``Attributes`` section of the module docstring, or in an + inline docstring immediately following the variable. + + Either form is acceptable, but the two should not be mixed. Choose + one convention to document module level variables and be consistent + with it. + +Todo: + * For module TODOs + * You have to also use ``sphinx.ext.todo`` extension + +.. _Google Python Style Guide: + https://google.github.io/styleguide/pyguide.html + +""" + +module_level_variable1 = 12345 + +module_level_variable2 = 98765 +"""int: Module level variable documented inline. + +The docstring may span multiple lines. The type may optionally be specified +on the first line, separated by a colon. +""" + + +def function_with_types_in_docstring(param1, param2): + """Example function with types documented in the docstring. + + :pep:`484` type annotations are supported. If attribute, parameter, and + return types are annotated according to `PEP 484`_, they do not need to be + included in the docstring: + + Args: + param1 (int): The first parameter. + param2 (str): The second parameter. + + Returns: + bool: The return value. True for success, False otherwise. + """ + + +def function_with_pep484_type_annotations(param1: int, param2: str) -> bool: + """Example function with PEP 484 type annotations. + + Args: + param1: The first parameter. + param2: The second parameter. + + Returns: + The return value. True for success, False otherwise. + + """ + + +def module_level_function(param1, param2=None, *args, **kwargs): + """This is an example of a module level function. + + Function parameters should be documented in the ``Args`` section. The name + of each parameter is required. The type and description of each parameter + is optional, but should be included if not obvious. + + If ``*args`` or ``**kwargs`` are accepted, + they should be listed as ``*args`` and ``**kwargs``. + + The format for a parameter is:: + + name (type): description + The description may span multiple lines. Following + lines should be indented. The "(type)" is optional. + + Multiple paragraphs are supported in parameter + descriptions. + + Args: + param1 (int): The first parameter. + param2 (:obj:`str`, optional): The second parameter. Defaults to None. + Second line of description should be indented. + *args: Variable length argument list. + **kwargs: Arbitrary keyword arguments. + + Returns: + bool: True if successful, False otherwise. + + The return type is optional and may be specified at the beginning of + the ``Returns`` section followed by a colon. + + The ``Returns`` section may span multiple lines and paragraphs. + Following lines should be indented to match the first line. + + The ``Returns`` section supports any reStructuredText formatting, + including literal blocks:: + + { + 'param1': param1, + 'param2': param2 + } + + Raises: + AttributeError: The ``Raises`` section is a list of all exceptions + that are relevant to the interface. + ValueError: If `param2` is equal to `param1`. + + """ + if param1 == param2: + raise ValueError('param1 may not be equal to param2') + return True + + +def example_generator(n): + """Generators have a ``Yields`` section instead of a ``Returns`` section. + + Args: + n (int): The upper limit of the range to generate, from 0 to `n` - 1. + + Yields: + int: The next number in the range of 0 to `n` - 1. + + Examples: + Examples should be written in doctest format, and should illustrate how + to use the function. + + >>> print([i for i in example_generator(4)]) + [0, 1, 2, 3] + + """ + yield from range(n) + + +class ExampleError(Exception): + """Exceptions are documented in the same way as classes. + + The __init__ method may be documented in either the class level + docstring, or as a docstring on the __init__ method itself. + + Either form is acceptable, but the two should not be mixed. Choose one + convention to document the __init__ method and be consistent with it. + + Note: + Do not include the `self` parameter in the ``Args`` section. + + Args: + msg (str): Human readable string describing the exception. + code (:obj:`int`, optional): Error code. + + Attributes: + msg (str): Human readable string describing the exception. + code (int): Exception error code. + + """ + + def __init__(self, msg, code): + self.msg = msg + self.code = code + + +class ExampleClass: + """The summary line for a class docstring should fit on one line. + + If the class has public attributes, they may be documented here + in an ``Attributes`` section and follow the same formatting as a + function's ``Args`` section. Alternatively, attributes may be documented + inline with the attribute's declaration (see __init__ method below). + + Properties created with the ``@property`` decorator should be documented + in the property's getter method. + + Attributes: + attr1 (str): Description of `attr1`. + attr2 (:obj:`int`, optional): Description of `attr2`. + + """ + + def __init__(self, param1, param2, param3): + """Example of docstring on the __init__ method. + + The __init__ method may be documented in either the class level + docstring, or as a docstring on the __init__ method itself. + + Either form is acceptable, but the two should not be mixed. Choose one + convention to document the __init__ method and be consistent with it. + + Note: + Do not include the `self` parameter in the ``Args`` section. + + Args: + param1 (str): Description of `param1`. + param2 (:obj:`int`, optional): Description of `param2`. Multiple + lines are supported. + param3 (list(str)): Description of `param3`. + + """ + self.attr1 = param1 + self.attr2 = param2 + self.attr3 = param3 #: Doc comment *inline* with attribute + + #: list(str): Doc comment *before* attribute, with type specified + self.attr4 = ['attr4'] + + self.attr5 = None + """str: Docstring *after* attribute, with type specified.""" + + @property + def readonly_property(self): + """str: Properties should be documented in their getter method.""" + return 'readonly_property' + + @property + def readwrite_property(self): + """list(str): Properties with both a getter and setter + should only be documented in their getter method. + + If the setter method contains notable behavior, it should be + mentioned here. + """ + return ['readwrite_property'] + + @readwrite_property.setter + def readwrite_property(self, value): + value + + def example_method(self, param1, param2): + """Class methods are similar to regular functions. + + Note: + Do not include the `self` parameter in the ``Args`` section. + + Args: + param1: The first parameter. + param2: The second parameter. + + Returns: + True if successful, False otherwise. + + """ + return True + + def __special__(self): + """By default special members with docstrings are not included. + + Special members are any methods or attributes that start with and + end with a double underscore. Any special member with a docstring + will be included in the output, if + ``napoleon_include_special_with_doc`` is set to True. + + This behavior can be enabled by changing the following setting in + Sphinx's conf.py:: + + napoleon_include_special_with_doc = True + + """ + pass + + def __special_without_docstring__(self): + pass + + def _private(self): + """By default private members are not included. + + Private members are any methods or attributes that start with an + underscore and are *not* special. By default they are not included + in the output. + + This behavior can be changed such that private members *are* included + by changing the following setting in Sphinx's conf.py:: + + napoleon_include_private_with_doc = True + + """ + pass + + def _private_without_docstring(self): + pass + +class ExamplePEP526Class: + """The summary line for a class docstring should fit on one line. + + If the class has public attributes, they may be documented here + in an ``Attributes`` section and follow the same formatting as a + function's ``Args`` section. If ``napoleon_attr_annotations`` + is True, types can be specified in the class body using ``PEP 526`` + annotations. + + Attributes: + attr1: Description of `attr1`. + attr2: Description of `attr2`. + + """ + + attr1: str + attr2: int diff --git a/doc/usage/extensions/example_google.rst b/doc/usage/extensions/example_google.rst new file mode 100644 index 0000000..a06f161 --- /dev/null +++ b/doc/usage/extensions/example_google.rst @@ -0,0 +1,17 @@ +:orphan: + +.. _example_google: + +Example Google Style Python Docstrings +====================================== + +.. seealso:: + + :ref:`example_numpy` + +.. only:: builder_html + + Download: :download:`example_google.py <example_google.py>` + +.. literalinclude:: example_google.py + :language: python diff --git a/doc/usage/extensions/example_numpy.py b/doc/usage/extensions/example_numpy.py new file mode 100644 index 0000000..2346b1e --- /dev/null +++ b/doc/usage/extensions/example_numpy.py @@ -0,0 +1,350 @@ +"""Example NumPy style docstrings. + +This module demonstrates documentation as specified by the `NumPy +Documentation HOWTO`_. Docstrings may extend over multiple lines. Sections +are created with a section header followed by an underline of equal length. + +Example +------- +Examples can be given using either the ``Example`` or ``Examples`` +sections. Sections support any reStructuredText formatting, including +literal blocks:: + + $ python example_numpy.py + + +Section breaks are created with two blank lines. Section breaks are also +implicitly created anytime a new section starts. Section bodies *may* be +indented: + +Notes +----- + This is an example of an indented section. It's like any other section, + but the body is indented to help it stand out from surrounding text. + +If a section is indented, then a section break is created by +resuming unindented text. + +Attributes +---------- +module_level_variable1 : int + Module level variables may be documented in either the ``Attributes`` + section of the module docstring, or in an inline docstring immediately + following the variable. + + Either form is acceptable, but the two should not be mixed. Choose + one convention to document module level variables and be consistent + with it. + + +.. _NumPy docstring standard: + https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard + +""" + +module_level_variable1 = 12345 + +module_level_variable2 = 98765 +"""int: Module level variable documented inline. + +The docstring may span multiple lines. The type may optionally be specified +on the first line, separated by a colon. +""" + + +def function_with_types_in_docstring(param1, param2): + """Example function with types documented in the docstring. + + :pep:`484` type annotations are supported. If attribute, parameter, and + return types are annotated according to `PEP 484`_, they do not need to be + included in the docstring: + + Parameters + ---------- + param1 : int + The first parameter. + param2 : str + The second parameter. + + Returns + ------- + bool + True if successful, False otherwise. + """ + + +def function_with_pep484_type_annotations(param1: int, param2: str) -> bool: + """Example function with PEP 484 type annotations. + + The return type must be duplicated in the docstring to comply + with the NumPy docstring style. + + Parameters + ---------- + param1 + The first parameter. + param2 + The second parameter. + + Returns + ------- + bool + True if successful, False otherwise. + + """ + + +def module_level_function(param1, param2=None, *args, **kwargs): + """This is an example of a module level function. + + Function parameters should be documented in the ``Parameters`` section. + The name of each parameter is required. The type and description of each + parameter is optional, but should be included if not obvious. + + If ``*args`` or ``**kwargs`` are accepted, + they should be listed as ``*args`` and ``**kwargs``. + + The format for a parameter is:: + + name : type + description + + The description may span multiple lines. Following lines + should be indented to match the first line of the description. + The ": type" is optional. + + Multiple paragraphs are supported in parameter + descriptions. + + Parameters + ---------- + param1 : int + The first parameter. + param2 : :obj:`str`, optional + The second parameter. + *args + Variable length argument list. + **kwargs + Arbitrary keyword arguments. + + Returns + ------- + bool + True if successful, False otherwise. + + The return type is not optional. The ``Returns`` section may span + multiple lines and paragraphs. Following lines should be indented to + match the first line of the description. + + The ``Returns`` section supports any reStructuredText formatting, + including literal blocks:: + + { + 'param1': param1, + 'param2': param2 + } + + Raises + ------ + AttributeError + The ``Raises`` section is a list of all exceptions + that are relevant to the interface. + ValueError + If `param2` is equal to `param1`. + + """ + if param1 == param2: + raise ValueError('param1 may not be equal to param2') + return True + + +def example_generator(n): + """Generators have a ``Yields`` section instead of a ``Returns`` section. + + Parameters + ---------- + n : int + The upper limit of the range to generate, from 0 to `n` - 1. + + Yields + ------ + int + The next number in the range of 0 to `n` - 1. + + Examples + -------- + Examples should be written in doctest format, and should illustrate how + to use the function. + + >>> print([i for i in example_generator(4)]) + [0, 1, 2, 3] + + """ + yield from range(n) + + +class ExampleError(Exception): + """Exceptions are documented in the same way as classes. + + The __init__ method may be documented in either the class level + docstring, or as a docstring on the __init__ method itself. + + Either form is acceptable, but the two should not be mixed. Choose one + convention to document the __init__ method and be consistent with it. + + Note + ---- + Do not include the `self` parameter in the ``Parameters`` section. + + Parameters + ---------- + msg : str + Human readable string describing the exception. + code : :obj:`int`, optional + Numeric error code. + + Attributes + ---------- + msg : str + Human readable string describing the exception. + code : int + Numeric error code. + + """ + + def __init__(self, msg, code): + self.msg = msg + self.code = code + + +class ExampleClass: + """The summary line for a class docstring should fit on one line. + + If the class has public attributes, they may be documented here + in an ``Attributes`` section and follow the same formatting as a + function's ``Args`` section. Alternatively, attributes may be documented + inline with the attribute's declaration (see __init__ method below). + + Properties created with the ``@property`` decorator should be documented + in the property's getter method. + + Attributes + ---------- + attr1 : str + Description of `attr1`. + attr2 : :obj:`int`, optional + Description of `attr2`. + + """ + + def __init__(self, param1, param2, param3): + """Example of docstring on the __init__ method. + + The __init__ method may be documented in either the class level + docstring, or as a docstring on the __init__ method itself. + + Either form is acceptable, but the two should not be mixed. Choose one + convention to document the __init__ method and be consistent with it. + + Note + ---- + Do not include the `self` parameter in the ``Parameters`` section. + + Parameters + ---------- + param1 : str + Description of `param1`. + param2 : list(str) + Description of `param2`. Multiple + lines are supported. + param3 : :obj:`int`, optional + Description of `param3`. + + """ + self.attr1 = param1 + self.attr2 = param2 + self.attr3 = param3 #: Doc comment *inline* with attribute + + #: list(str): Doc comment *before* attribute, with type specified + self.attr4 = ["attr4"] + + self.attr5 = None + """str: Docstring *after* attribute, with type specified.""" + + @property + def readonly_property(self): + """str: Properties should be documented in their getter method.""" + return "readonly_property" + + @property + def readwrite_property(self): + """list(str): Properties with both a getter and setter + should only be documented in their getter method. + + If the setter method contains notable behavior, it should be + mentioned here. + """ + return ["readwrite_property"] + + @readwrite_property.setter + def readwrite_property(self, value): + value + + def example_method(self, param1, param2): + """Class methods are similar to regular functions. + + Note + ---- + Do not include the `self` parameter in the ``Parameters`` section. + + Parameters + ---------- + param1 + The first parameter. + param2 + The second parameter. + + Returns + ------- + bool + True if successful, False otherwise. + + """ + return True + + def __special__(self): + """By default special members with docstrings are not included. + + Special members are any methods or attributes that start with and + end with a double underscore. Any special member with a docstring + will be included in the output, if + ``napoleon_include_special_with_doc`` is set to True. + + This behavior can be enabled by changing the following setting in + Sphinx's conf.py:: + + napoleon_include_special_with_doc = True + + """ + pass + + def __special_without_docstring__(self): + pass + + def _private(self): + """By default private members are not included. + + Private members are any methods or attributes that start with an + underscore and are *not* special. By default they are not included + in the output. + + This behavior can be changed such that private members *are* included + by changing the following setting in Sphinx's conf.py:: + + napoleon_include_private_with_doc = True + + """ + pass + + def _private_without_docstring(self): + pass diff --git a/doc/usage/extensions/example_numpy.rst b/doc/usage/extensions/example_numpy.rst new file mode 100644 index 0000000..38d3439 --- /dev/null +++ b/doc/usage/extensions/example_numpy.rst @@ -0,0 +1,17 @@ +:orphan: + +.. _example_numpy: + +Example NumPy Style Python Docstrings +====================================== + +.. seealso:: + + :ref:`example_google` + +.. only:: builder_html + + Download: :download:`example_numpy.py <example_numpy.py>` + +.. literalinclude:: example_numpy.py + :language: python diff --git a/doc/usage/extensions/extlinks.rst b/doc/usage/extensions/extlinks.rst new file mode 100644 index 0000000..97359ab --- /dev/null +++ b/doc/usage/extensions/extlinks.rst @@ -0,0 +1,69 @@ +:mod:`sphinx.ext.extlinks` -- Markup to shorten external links +============================================================== + +.. module:: sphinx.ext.extlinks + :synopsis: Allow inserting external links with common base URLs easily. +.. moduleauthor:: Georg Brandl + +.. versionadded:: 1.0 + +This extension is meant to help with the common pattern of having many external +links that point to URLs on one and the same site, e.g. links to bug trackers, +version control web interfaces, or simply subpages in other websites. It does +so by providing aliases to base URLs, so that you only need to give the subpage +name when creating a link. + +Let's assume that you want to include many links to issues at the Sphinx +tracker, at :samp:`https://github.com/sphinx-doc/sphinx/issues/{num}`. Typing +this URL again and again is tedious, so you can use :mod:`~sphinx.ext.extlinks` +to avoid repeating yourself. + +The extension adds a config value: + +.. confval:: extlinks + + This config value must be a dictionary of external sites, mapping unique + short alias names to a *base URL* and a *caption*. For example, to create an + alias for the above mentioned issues, you would add :: + + extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s', + 'issue %s')} + + Now, you can use the alias name as a new role, e.g. ``:issue:`123```. This + then inserts a link to https://github.com/sphinx-doc/sphinx/issues/123. + As you can see, the target given in the role is substituted in the *base URL* + in the place of ``%s``. + + The link caption depends on the second item in the tuple, the *caption*: + + - If *caption* is ``None``, the link caption is the full URL. + - If *caption* is a string, then it must contain ``%s`` exactly once. In + this case the link caption is *caption* with the partial URL substituted + for ``%s`` -- in the above example, the link caption would be + ``issue 123``. + + To produce a literal ``%`` in either *base URL* or *caption*, use ``%%``:: + + extlinks = {'KnR': ('https://example.org/K%%26R/page/%s', + '[K&R; page %s]')} + + You can also use the usual "explicit title" syntax supported by other roles + that generate links, i.e. ``:issue:`this issue <123>```. In this case, the + *caption* is not relevant. + + .. versionchanged:: 4.0 + + Support to substitute by '%s' in the caption. + +.. note:: + + Since links are generated from the role in the reading stage, they appear as + ordinary links to e.g. the ``linkcheck`` builder. + +.. confval:: extlinks_detect_hardcoded_links + + If enabled, extlinks emits a warning if a hardcoded link is replaceable + by an extlink, and suggests a replacement via warning. It defaults to + ``False``. + + .. versionadded:: 4.5 diff --git a/doc/usage/extensions/githubpages.rst b/doc/usage/extensions/githubpages.rst new file mode 100644 index 0000000..6d56a30 --- /dev/null +++ b/doc/usage/extensions/githubpages.rst @@ -0,0 +1,16 @@ +:mod:`sphinx.ext.githubpages` -- Publish HTML docs in GitHub Pages +================================================================== + +.. module:: sphinx.ext.githubpages + :synopsis: Publish HTML docs in GitHub Pages + +.. versionadded:: 1.4 + +.. versionchanged:: 2.0 + Support ``CNAME`` file + +This extension creates ``.nojekyll`` file on generated HTML directory to publish +the document on GitHub Pages. + +It also creates a ``CNAME`` file for custom domains when :confval:`html_baseurl` +set. diff --git a/doc/usage/extensions/graphviz.rst b/doc/usage/extensions/graphviz.rst new file mode 100644 index 0000000..c134f6d --- /dev/null +++ b/doc/usage/extensions/graphviz.rst @@ -0,0 +1,239 @@ +.. highlight:: rest + +:mod:`sphinx.ext.graphviz` -- Add Graphviz graphs +================================================= + +.. module:: sphinx.ext.graphviz + :synopsis: Support for Graphviz graphs. + +.. versionadded:: 0.6 + +This extension allows you to embed `Graphviz <https://graphviz.org/>`_ graphs in +your documents. + +It adds these directives: + +.. rst:directive:: graphviz + + Directive to embed graphviz code. The input code for ``dot`` is given as the + content. For example:: + + .. graphviz:: + + digraph foo { + "bar" -> "baz"; + } + + In HTML output, the code will be rendered to a PNG or SVG image (see + :confval:`graphviz_output_format`). In LaTeX output, the code will be + rendered to an embeddable PDF file. + + You can also embed external dot files, by giving the file name as an + argument to :rst:dir:`graphviz` and no additional content:: + + .. graphviz:: external.dot + + As for all file references in Sphinx, if the filename is absolute, it is + taken as relative to the source directory. + + .. versionchanged:: 1.1 + Added support for external files. + + .. rubric:: options + + .. rst:directive:option:: alt: alternate text + :type: text + + The alternate text of the graph. By default, the graph code is used to + the alternate text. + + .. versionadded:: 1.0 + + .. rst:directive:option:: align: alignment of the graph + :type: left, center or right + + The horizontal alignment of the graph. + + .. versionadded:: 1.5 + + .. rst:directive:option:: caption: caption of the graph + :type: text + + The caption of the graph. + + .. versionadded:: 1.1 + + .. 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 + graphviz commands are also allowed. By default, :confval:`graphviz_dot` + is used. + + .. versionadded:: 1.4 + .. versionchanged:: 2.2 + + Renamed from ``graphviz_dot`` + + .. rst:directive:option:: name: label + :type: text + + The label of the graph. + + .. versionadded:: 1.6 + + .. rst:directive:option:: class: class names + :type: a list of class names separated by spaces + + The class name of the graph. + + .. versionadded:: 2.4 + + +.. rst:directive:: graph + + Directive for embedding a single undirected graph. The name is given as a + directive argument, the contents of the graph are the directive content. + This is a convenience directive to generate ``graph <name> { <content> }``. + + For example:: + + .. graph:: foo + + "bar" -- "baz"; + + .. note:: The graph name is passed unchanged to Graphviz. If it contains + non-alphanumeric characters (e.g. a dash), you will have to double-quote + it. + + .. rubric:: options + + Same as :rst:dir:`graphviz`. + + .. rst:directive:option:: alt: alternate text + :type: text + + .. versionadded:: 1.0 + + .. rst:directive:option:: align: alignment of the graph + :type: left, center or right + + .. versionadded:: 1.5 + + .. rst:directive:option:: caption: caption of the graph + :type: text + + .. versionadded:: 1.1 + + .. rst:directive:option:: layout: layout type of the graph + :type: text + + .. versionadded:: 1.4 + .. versionchanged:: 2.2 + + Renamed from ``graphviz_dot`` + + .. rst:directive:option:: name: label + :type: text + + .. versionadded:: 1.6 + + .. rst:directive:option:: class: class names + :type: a list of class names separated by spaces + + The class name of the graph. + + .. versionadded:: 2.4 + + +.. rst:directive:: digraph + + Directive for embedding a single directed graph. The name is given as a + directive argument, the contents of the graph are the directive content. + This is a convenience directive to generate ``digraph <name> { <content> }``. + + For example:: + + .. digraph:: foo + + "bar" -> "baz" -> "quux"; + + .. rubric:: options + + Same as :rst:dir:`graphviz`. + + .. rst:directive:option:: alt: alternate text + :type: text + + .. versionadded:: 1.0 + + .. rst:directive:option:: align: alignment of the graph + :type: left, center or right + + .. versionadded:: 1.5 + + .. rst:directive:option:: caption: caption of the graph + :type: text + + .. versionadded:: 1.1 + + .. rst:directive:option:: layout: layout type of the graph + :type: text + + .. versionadded:: 1.4 + .. versionchanged:: 2.2 + + Renamed from ``graphviz_dot`` + + .. rst:directive:option:: name: label + :type: text + + .. versionadded:: 1.6 + + .. rst:directive:option:: class: class names + :type: a list of class names separated by spaces + + The class name of the graph. + + .. versionadded:: 2.4 + + +There are also these config values: + +.. confval:: graphviz_dot + + The command name with which to invoke ``dot``. The default is ``'dot'``; you + may need to set this to a full path if ``dot`` is not in the executable + search path. + + Since this setting is not portable from system to system, it is normally not + useful to set it in ``conf.py``; rather, giving it on the + :program:`sphinx-build` command line via the :option:`-D <sphinx-build -D>` + option should be preferable, like this:: + + sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html + +.. confval:: graphviz_dot_args + + Additional command-line arguments to give to dot, as a list. The default is + an empty list. This is the right place to set global graph, node or edge + attributes via dot's ``-G``, ``-N`` and ``-E`` options. + +.. confval:: graphviz_output_format + + The output format for Graphviz when building HTML files. This must be either + ``'png'`` or ``'svg'``; the default is ``'png'``. If ``'svg'`` is used, in + order to make the URL links work properly, an appropriate ``target`` + attribute must be set, such as ``"_top"`` and ``"_blank"``. For example, the + link in the following graph should work in the svg output: :: + + .. graphviz:: + + digraph example { + a [label="sphinx", href="https://www.sphinx-doc.org/", target="_top"]; + b [label="other"]; + a -> b; + } + + .. versionadded:: 1.0 + Previously, output always was PNG. diff --git a/doc/usage/extensions/ifconfig.rst b/doc/usage/extensions/ifconfig.rst new file mode 100644 index 0000000..837c0b3 --- /dev/null +++ b/doc/usage/extensions/ifconfig.rst @@ -0,0 +1,38 @@ +.. highlight:: rest + +:mod:`sphinx.ext.ifconfig` -- Include content based on configuration +==================================================================== + +.. module:: sphinx.ext.ifconfig + :synopsis: Include documentation content based on configuration values. + +This extension is quite simple, and features only one directive: + +.. warning:: + + This directive is designed to control only content of document. It could + not control sections, labels and so on. + +.. rst:directive:: ifconfig + + Include content of the directive only if the Python expression given as an + argument is ``True``, evaluated in the namespace of the project's + configuration (that is, all registered variables from :file:`conf.py` are + available). + + For example, one could write :: + + .. ifconfig:: releaselevel in ('alpha', 'beta', 'rc') + + This stuff is only included in the built docs for unstable versions. + + To make a custom config value known to Sphinx, use + :func:`~sphinx.application.Sphinx.add_config_value` in the setup function in + :file:`conf.py`, e.g.:: + + def setup(app): + app.add_config_value('releaselevel', '', 'env') + + The second argument is the default value, the third should always be + ``'env'`` for such values (it selects if Sphinx re-reads the documents if the + value changes). diff --git a/doc/usage/extensions/imgconverter.rst b/doc/usage/extensions/imgconverter.rst new file mode 100644 index 0000000..b9af22d --- /dev/null +++ b/doc/usage/extensions/imgconverter.rst @@ -0,0 +1,55 @@ +.. _sphinx.ext.imgconverter: + +:mod:`sphinx.ext.imgconverter` -- A reference image converter using Imagemagick +=============================================================================== + +.. module:: sphinx.ext.imgconverter + :synopsis: Convert images to appropriate format for builders + +.. versionadded:: 1.6 + +This extension converts images in your document to appropriate format for +builders. For example, it allows you to use SVG images with LaTeX builder. +As a result, you don't mind what image format the builder supports. + +By default the extension uses ImageMagick_ to perform conversions, +and will not work if ImageMagick is not installed. + +.. _ImageMagick: https://www.imagemagick.org + +.. note:: + + ImageMagick rasterizes a SVG image on conversion. As a result, the image + becomes not scalable. To avoid that, please use other image converters like + `sphinxcontrib-svg2pdfconverter`__ (which uses Inkscape or + ``rsvg-convert``). + +.. __: https://github.com/missinglinkelectronics/sphinxcontrib-svg2pdfconverter + + +Configuration +------------- + +.. confval:: image_converter + + A path to a conversion command. By default, the imgconverter finds + the command from search paths. + + On Unix platforms, the command :command:`convert` is used by default. + + On Windows, the command :command:`magick` is used by default. + + .. versionchanged:: 3.1 + + Use :command:`magick` command by default on windows + +.. confval:: image_converter_args + + Additional command-line arguments to give to :command:`convert`, as a list. + The default is an empty list ``[]``. + + On Windows, it defaults to ``["convert"]``. + + .. versionchanged:: 3.1 + + Use ``["convert"]`` by default on Windows diff --git a/doc/usage/extensions/index.rst b/doc/usage/extensions/index.rst new file mode 100644 index 0000000..929f2b6 --- /dev/null +++ b/doc/usage/extensions/index.rst @@ -0,0 +1,81 @@ +========== +Extensions +========== + +Since many projects will need special features in their documentation, Sphinx +allows adding "extensions" to the build process, each of which can modify +almost any aspect of document processing. + +This chapter describes the extensions bundled with Sphinx. For the API +documentation on writing your own extension, refer to :ref:`dev-extensions`. + + +.. _builtin-extensions: + +Built-in extensions +------------------- + +These extensions are built in and can be activated by respective entries in the +:confval:`extensions` configuration value: + +.. toctree:: + :maxdepth: 1 + + autodoc + autosectionlabel + autosummary + coverage + doctest + duration + extlinks + githubpages + graphviz + ifconfig + imgconverter + inheritance + intersphinx + linkcode + math + napoleon + todo + viewcode + + +.. _third-party-extensions: + +Third-party extensions +---------------------- + +You can find several extensions contributed by users in the `sphinx-contrib`__ +organization. If you wish to include your extension in this organization, +simply follow the instructions provided in the `github-administration`__ +project. This is optional and there are several extensions hosted elsewhere. +The `awesome-sphinxdoc`__ and `sphinx-extensions`__ projects are both curated +lists of Sphinx packages, and many packages use the +`Framework :: Sphinx :: Extension`__ and +`Framework :: Sphinx :: Theme`__ trove classifiers for Sphinx extensions and +themes, respectively. + +.. __: https://github.com/sphinx-contrib/ +.. __: https://github.com/sphinx-contrib/github-administration +.. __: https://github.com/yoloseem/awesome-sphinxdoc +.. __: https://sphinx-extensions.readthedocs.io/en/latest/ +.. __: https://pypi.org/search/?c=Framework+%3A%3A+Sphinx+%3A%3A+Extension +.. __: https://pypi.org/search/?c=Framework+%3A%3A+Sphinx+%3A%3A+Theme + +Where to put your own extensions? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Extensions local to a project should be put within the project's directory +structure. Set Python's module search path, ``sys.path``, accordingly so that +Sphinx can find them. For example, if your extension ``foo.py`` lies in the +``exts`` subdirectory of the project root, put into :file:`conf.py`:: + + import sys, os + + sys.path.append(os.path.abspath('exts')) + + extensions = ['foo'] + +You can also install extensions anywhere else on ``sys.path``, e.g. in the +``site-packages`` directory. diff --git a/doc/usage/extensions/inheritance.rst b/doc/usage/extensions/inheritance.rst new file mode 100644 index 0000000..33284b5 --- /dev/null +++ b/doc/usage/extensions/inheritance.rst @@ -0,0 +1,174 @@ +.. highlight:: rest + +:mod:`sphinx.ext.inheritance_diagram` -- Include inheritance diagrams +===================================================================== + +.. module:: sphinx.ext.inheritance_diagram + :synopsis: Support for displaying inheritance diagrams via graphviz. + +.. versionadded:: 0.6 + +This extension allows you to include inheritance diagrams, rendered via the +:mod:`Graphviz extension <sphinx.ext.graphviz>`. + +It adds this directive: + +.. rst:directive:: inheritance-diagram + + This directive has one or more arguments, each giving a module or class + name. Class names can be unqualified; in that case they are taken to exist + in the currently described module (see :rst:dir:`py:module`). + + For each given class, and each class in each given module, the base classes + are determined. Then, from all classes and their base classes, a graph is + generated which is then rendered via the graphviz extension to a directed + graph. + + This directive supports an option called ``parts`` that, if given, must be an + integer, advising the directive to keep that many dot-separated parts + in the displayed names (from right to left). For example, ``parts=1`` will + only display class names, without the names of the modules that contain + them. + + .. versionchanged:: 2.0 + The value of for ``parts`` can also be negative, indicating how many + parts to drop from the left. For example, if all your class names start + with ``lib.``, you can give ``:parts: -1`` to remove that prefix from the + displayed node names. + + The directive also supports a ``private-bases`` flag option; if given, + private base classes (those whose name starts with ``_``) will be included. + + You can use ``caption`` option to give a caption to the diagram. + + .. versionchanged:: 1.1 + Added ``private-bases`` option; previously, all bases were always + included. + + .. versionchanged:: 1.5 + Added ``caption`` option + + It also supports a ``top-classes`` option which requires one or more class + names separated by comma. If specified inheritance traversal will stop at the + specified class names. Given the following Python module:: + + """ + A + / \ + B C + / \ / \ + E D F + """ + + class A: + pass + + class B(A): + pass + + class C(A): + pass + + class D(B, C): + pass + + class E(B): + pass + + class F(C): + pass + + If you have specified a module in the inheritance diagram like this:: + + .. inheritance-diagram:: dummy.test + :top-classes: dummy.test.B, dummy.test.C + + any base classes which are ancestors to ``top-classes`` and are also defined + in the same module will be rendered as stand alone nodes. In this example + class A will be rendered as stand alone node in the graph. This is a known + issue due to how this extension works internally. + + If you don't want class A (or any other ancestors) to be visible then specify + only the classes you would like to generate the diagram for like this:: + + .. inheritance-diagram:: dummy.test.D dummy.test.E dummy.test.F + :top-classes: dummy.test.B, dummy.test.C + + .. versionchanged:: 1.7 + Added ``top-classes`` option to limit the scope of inheritance graphs. + + +Examples +-------- + +The following are different inheritance diagrams for the internal +``InheritanceDiagram`` class that implements the directive. + +With full names:: + + .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram + +.. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram + + +Showing class names only:: + + .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram + :parts: 1 + +.. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram + :parts: 1 + +Stopping the diagram at :class:`sphinx.util.docutils.SphinxDirective` (the +highest superclass still part of Sphinx), and dropping the common left-most +part (``sphinx``) from all names:: + + .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram + :top-classes: sphinx.util.docutils.SphinxDirective + :parts: -1 + +.. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram + :top-classes: sphinx.util.docutils.SphinxDirective + :parts: -1 + +.. py:class:: sphinx.ext.inheritance_diagram.InheritanceDiagram + :no-contents-entry: + :no-index-entry: + + The internal class that implements the ``inheritance-diagram`` directive. + + +Configuration +------------- + +.. confval:: inheritance_graph_attrs + + A dictionary of graphviz graph attributes for inheritance diagrams. + + For example:: + + inheritance_graph_attrs = dict(rankdir="LR", size='"6.0, 8.0"', + fontsize=14, ratio='compress') + +.. confval:: inheritance_node_attrs + + A dictionary of graphviz node attributes for inheritance diagrams. + + For example:: + + inheritance_node_attrs = dict(shape='ellipse', fontsize=14, height=0.75, + color='dodgerblue1', style='filled') + +.. confval:: inheritance_edge_attrs + + A dictionary of graphviz edge attributes for inheritance diagrams. + +.. confval:: inheritance_alias + + Allows mapping the full qualified name of the class to custom values + (useful when exposing the underlying path of a class is not desirable, + e.g. it's a private class and should not be instantiated by the user). + + For example:: + + inheritance_alias = {'_pytest.Magic': 'pytest.Magic'} diff --git a/doc/usage/extensions/intersphinx.rst b/doc/usage/extensions/intersphinx.rst new file mode 100644 index 0000000..5aaaf9f --- /dev/null +++ b/doc/usage/extensions/intersphinx.rst @@ -0,0 +1,250 @@ +:mod:`sphinx.ext.intersphinx` -- Link to other projects' documentation +====================================================================== + +.. module:: sphinx.ext.intersphinx + :synopsis: Link to other Sphinx documentation. + +.. index:: pair: automatic; linking + +.. versionadded:: 0.5 + +This extension can generate links to the documentation of objects in external +projects, either explicitly through the :rst:role:`external` role, or as a +fallback resolution for any other cross-reference. + +Usage for fallback resolution is simple: whenever Sphinx encounters a +cross-reference that has no matching target in the current documentation set, +it looks for targets in the external documentation sets configured in +:confval:`intersphinx_mapping`. A reference like +``:py:class:`zipfile.ZipFile``` can then link to the Python documentation +for the ZipFile class, without you having to specify where it is located +exactly. + +When using the :rst:role:`external` role, you can force lookup to any external +projects, and optionally to a specific external project. +A link like ``:external:ref:`comparison manual <comparisons>``` will then link +to the label "comparisons" in whichever configured external project, if it +exists, +and a link like ``:external+python:ref:`comparison manual <comparisons>``` will +link to the label "comparisons" only in the doc set "python", if it exists. + +Behind the scenes, this works as follows: + +* Each Sphinx HTML build creates a file named :file:`objects.inv` that contains + a mapping from object names to URIs relative to the HTML set's root. + +* Projects using the Intersphinx extension can specify the location of such + mapping files in the :confval:`intersphinx_mapping` config value. The mapping + will then be used to resolve both :rst:role:`external` references, and also + otherwise missing references to objects into links to the other documentation. + +* By default, the mapping file is assumed to be at the same location as the rest + of the documentation; however, the location of the mapping file can also be + specified individually, e.g. if the docs should be buildable without Internet + access. + + +Configuration +------------- + +To use Intersphinx linking, add ``'sphinx.ext.intersphinx'`` to your +:confval:`extensions` config value, and use these config values to activate +linking: + +.. confval:: intersphinx_mapping + + This config value contains the locations and names of other projects that + should be linked to in this documentation. + + Relative local paths for target locations are taken as relative to the base + of the built documentation, while relative local paths for inventory + locations are taken as relative to the source directory. + + When fetching remote inventory files, proxy settings will be read from + the ``$HTTP_PROXY`` environment variable. + + **Format** + + .. versionadded:: 1.0 + + A dictionary mapping unique identifiers to a tuple ``(target, inventory)``. + Each ``target`` is the base URI of a foreign Sphinx documentation set and can + be a local path or an HTTP URI. The ``inventory`` indicates where the + inventory file can be found: it can be ``None`` (an :file:`objects.inv` file + at the same location as the base URI) or another local file path or a full + HTTP URI to an inventory file. + + The unique identifier can be used in the :rst:role:`external` role, so that + it is clear which intersphinx set the target belongs to. A link like + ``external:python+ref:`comparison manual <comparisons>``` will link to the + label "comparisons" in the doc set "python", if it exists. + + **Example** + + To add links to modules and objects in the Python standard library + documentation, use:: + + intersphinx_mapping = {'python': ('https://docs.python.org/3', None)} + + This will download the corresponding :file:`objects.inv` file from the + Internet and generate links to the pages under the given URI. The downloaded + inventory is cached in the Sphinx environment, so it must be re-downloaded + whenever you do a full rebuild. + + A second example, showing the meaning of a non-``None`` value of the second + tuple item:: + + intersphinx_mapping = {'python': ('https://docs.python.org/3', + 'python-inv.txt')} + + This will read the inventory from :file:`python-inv.txt` in the source + directory, but still generate links to the pages under + ``https://docs.python.org/3``. It is up to you to update the inventory file + as new objects are added to the Python documentation. + + **Multiple targets for the inventory** + + .. versionadded:: 1.3 + + Alternative files can be specified for each inventory. One can give a + tuple for the second inventory tuple item as shown in the following + example. This will read the inventory iterating through the (second) + tuple items until the first successful fetch. The primary use case for + this to specify mirror sites for server downtime of the primary + inventory:: + + intersphinx_mapping = {'python': ('https://docs.python.org/3', + (None, 'python-inv.txt'))} + + For a set of books edited and tested locally and then published + together, it could be helpful to try a local inventory file first, + to check references before publication:: + + intersphinx_mapping = { + 'otherbook': + ('https://myproj.readthedocs.io/projects/otherbook/en/latest', + ('../../otherbook/build/html/objects.inv', None)), + } + + **Old format for this config value** + + .. deprecated:: 6.2 + + .. RemovedInSphinx80Warning + + .. caution:: This is the format used before Sphinx 1.0. + It is deprecated and will be removed in Sphinx 8.0. + + A dictionary mapping URIs to either ``None`` or an URI. The keys are the + base URI of the foreign Sphinx documentation sets and can be local paths or + HTTP URIs. The values indicate where the inventory file can be found: they + can be ``None`` (at the same location as the base URI) or another local or + HTTP URI. + + Example: + + .. code:: python + + intersphinx_mapping = {'https://docs.python.org/': None} + + +.. confval:: intersphinx_cache_limit + + The maximum number of days to cache remote inventories. The default is + ``5``, meaning five days. Set this to a negative value to cache inventories + for unlimited time. + +.. confval:: intersphinx_timeout + + The number of seconds for timeout. The default is ``None``, meaning do not + timeout. + + .. note:: + + timeout is not a time limit on the entire response download; rather, an + exception is raised if the server has not issued a response for timeout + seconds. + +.. confval:: intersphinx_disabled_reftypes + + .. versionadded:: 4.3 + + .. versionchanged:: 5.0 + + Changed default value from an empty list to ``['std:doc']``. + + A list of strings being either: + + - the name of a specific reference type in a domain, + e.g., ``std:doc``, ``py:func``, or ``cpp:class``, + - the name of a domain, and a wildcard, e.g., + ``std:*``, ``py:*``, or ``cpp:*``, or + - simply a wildcard ``*``. + + The default value is ``['std:doc']``. + + When a non-:rst:role:`external` cross-reference is being resolved by + intersphinx, skip resolution if it matches one of the specifications in this + list. + + For example, with ``intersphinx_disabled_reftypes = ['std:doc']`` + a cross-reference ``:doc:`installation``` will not be attempted to be + resolved by intersphinx, but ``:external+otherbook:doc:`installation``` will + be attempted to be resolved in the inventory named ``otherbook`` in + :confval:`intersphinx_mapping`. + At the same time, all cross-references generated in, e.g., Python, + declarations will still be attempted to be resolved by intersphinx. + + If ``*`` is in the list of domains, then no non-:rst:role:`external` + references will be resolved by intersphinx. + +Explicitly Reference External Objects +------------------------------------- + +The Intersphinx extension provides the following role. + +.. rst:role:: external + + .. versionadded:: 4.4 + + Use Intersphinx to perform lookup only in external projects, and not the + current project. Intersphinx still needs to know the type of object you + would like to find, so the general form of this role is to write the + cross-refererence as if the object is in the current project, but then prefix + it with ``:external``. + The two forms are then + + - ``:external:domain:reftype:`target```, + e.g., ``:external:py:class:`zipfile.ZipFile```, or + - ``:external:reftype:`target```, + e.g., ``:external:doc:`installation```. + + If you would like to constrain the lookup to a specific external project, + then the key of the project, as specified in :confval:`intersphinx_mapping`, + is added as well to get the two forms + + - ``:external+invname:domain:reftype:`target```, + e.g., ``:external+python:py:class:`zipfile.ZipFile```, or + - ``:external+invname:reftype:`target```, + e.g., ``:external+python:doc:`installation```. + +Showing all links of an Intersphinx mapping file +------------------------------------------------ + +To show all Intersphinx links and their targets of an Intersphinx mapping file, +run ``python -msphinx.ext.intersphinx url-or-path``. This is helpful when +searching for the root cause of a broken Intersphinx link in a documentation +project. The following example prints the Intersphinx mapping of the Python 3 +documentation:: + + $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv + +Using Intersphinx with inventory file under Basic Authorization +--------------------------------------------------------------- + +Intersphinx supports Basic Authorization like this:: + + intersphinx_mapping = {'python': ('https://user:password@docs.python.org/3', + None)} + +The user and password will be stripped from the URL when generating the links. diff --git a/doc/usage/extensions/linkcode.rst b/doc/usage/extensions/linkcode.rst new file mode 100644 index 0000000..e65a0b7 --- /dev/null +++ b/doc/usage/extensions/linkcode.rst @@ -0,0 +1,51 @@ +:mod:`sphinx.ext.linkcode` -- Add external links to source code +=============================================================== + +.. module:: sphinx.ext.linkcode + :synopsis: Add external links to source code. +.. moduleauthor:: Pauli Virtanen + +.. versionadded:: 1.2 + +This extension looks at your object descriptions (``.. class::``, +``.. function::`` etc.) and adds external links to code hosted +somewhere on the web. The intent is similar to the +``sphinx.ext.viewcode`` extension, but assumes the source code can be +found somewhere on the Internet. + +In your configuration, you need to specify a :confval:`linkcode_resolve` +function that returns an URL based on the object. + + +Configuration +------------- + +.. confval:: linkcode_resolve + + This is a function ``linkcode_resolve(domain, info)``, + which should return the URL to source code corresponding to + the object in given domain with given information. + + The function should return ``None`` if no link is to be added. + + The argument ``domain`` specifies the language domain the object is + in. ``info`` is a dictionary with the following keys guaranteed to + be present (dependent on the domain): + + - ``py``: ``module`` (name of the module), ``fullname`` (name of the object) + - ``c``: ``names`` (list of names for the object) + - ``cpp``: ``names`` (list of names for the object) + - ``javascript``: ``object`` (name of the object), ``fullname`` + (name of the item) + + Example: + + .. code-block:: python + + def linkcode_resolve(domain, info): + if domain != 'py': + return None + if not info['module']: + return None + filename = info['module'].replace('.', '/') + return "https://somesite/sourcerepo/%s.py" % filename diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst new file mode 100644 index 0000000..df4fc6b --- /dev/null +++ b/doc/usage/extensions/math.rst @@ -0,0 +1,320 @@ +.. highlight:: rest + +.. _math-support: + +Math support for HTML outputs in Sphinx +======================================= + +.. module:: sphinx.ext.mathbase + :synopsis: Common math support for imgmath and mathjax / jsmath. + +.. versionadded:: 0.5 +.. versionchanged:: 1.8 + + Math support for non-HTML builders is integrated to sphinx-core. + So mathbase extension is no longer needed. + +Since mathematical notation isn't natively supported by HTML in any way, Sphinx +gives a math support to HTML document with several extensions. These use the +reStructuredText math :rst:dir:`directive <math>` and :rst:role:`role <math>`. + +:mod:`sphinx.ext.imgmath` -- Render math as images +-------------------------------------------------- + +.. module:: sphinx.ext.imgmath + :synopsis: Render math as PNG or SVG images. + +.. versionadded:: 1.4 + +This extension renders math via LaTeX and dvipng_ or dvisvgm_ into PNG or SVG +images. This of course means that the computer where the docs are built must +have both programs available. + +There are various configuration values you can set to influence how the images +are built: + +.. confval:: imgmath_image_format + + The output image format. The default is ``'png'``. It should be either + ``'png'`` or ``'svg'``. The image is produced by first executing ``latex`` + on the TeX mathematical mark-up then (depending on the requested format) + either `dvipng`_ or `dvisvgm`_. + +.. confval:: imgmath_use_preview + + ``dvipng`` and ``dvisvgm`` both have the ability to collect from LaTeX the + "depth" of the rendered math: an inline image should use this "depth" in a + ``vertical-align`` style to get correctly aligned with surrounding text. + + This mechanism requires the `LaTeX preview package`_ (available as + ``preview-latex-style`` on Ubuntu xenial). Therefore, the default for this + option is ``False`` but it is strongly recommended to set it to ``True``. + + .. versionchanged:: 2.2 + + This option can be used with the ``'svg'`` :confval:`imgmath_image_format`. + +.. confval:: imgmath_add_tooltips + + Default: ``True``. If false, do not add the LaTeX code as an "alt" attribute + for math images. + +.. confval:: imgmath_font_size + + The font size (in ``pt``) of the displayed math. The default value is + ``12``. It must be a positive integer. + +.. confval:: imgmath_latex + + The command name with which to invoke LaTeX. The default is ``'latex'``; you + may need to set this to a full path if ``latex`` is not in the executable + search path. + + Since this setting is not portable from system to system, it is normally not + useful to set it in ``conf.py``; rather, giving it on the + :program:`sphinx-build` command line via the :option:`-D <sphinx-build -D>` + option should be preferable, like this:: + + sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html + + This value should only contain the path to the latex executable, not further + arguments; use :confval:`imgmath_latex_args` for that purpose. + + .. hint:: + + To use `OpenType Math fonts`__ with ``unicode-math``, via a custom + :confval:`imgmath_latex_preamble`, you can set :confval:`imgmath_latex` + to ``'dvilualatex'``, but must then set :confval:`imgmath_image_format` + to ``'svg'``. Note: this has only been tested with ``dvisvgm 3.0.3``. + It significantly increases image production duration compared to using + standard ``'latex'`` with traditional TeX math fonts. + + __ https://tex.stackexchange.com/questions/425098/which-opentype-math-fonts-are-available + + + .. hint:: + + Some fancy LaTeX mark-up (an example was reported which used TikZ to add + various decorations to the equation) require multiple runs of the LaTeX + executable. To handle this, set this configuration setting to + ``'latexmk'`` (or a full path to it) as this Perl script reliably + chooses dynamically how many latex runs are needed. + + .. versionchanged:: 6.2.0 + + Using ``'xelatex'`` (or a full path to it) is now supported. But you + must then add ``'-no-pdf'`` to the :confval:`imgmath_latex_args` list of + the command options. The ``'svg'`` :confval:`imgmath_image_format` is + required. Also, you may need the ``dvisvgm`` binary to be relatively + recent (testing was done only with its ``3.0.3`` release). + + .. note:: + + Regarding the previous note, it is currently not supported to use + ``latexmk`` with option ``-xelatex``. + +.. confval:: imgmath_latex_args + + Additional arguments to give to latex, as a list. The default is an empty + list. + +.. confval:: imgmath_latex_preamble + + Additional LaTeX code to put into the preamble of the LaTeX files used to + translate the math snippets. This is left empty by default. Use it + e.g. to add packages which modify the fonts used for math, such as + ``'\\usepackage{newtxsf}'`` for sans-serif fonts, or + ``'\\usepackage{fouriernc}'`` for serif fonts. Indeed, the default LaTeX + math fonts have rather thin glyphs which (in HTML output) often do not + match well with the font for text. + +.. confval:: imgmath_dvipng + + The command name to invoke ``dvipng``. The default is + ``'dvipng'``; you may need to set this to a full path if ``dvipng`` is not in + the executable search path. This option is only used when + ``imgmath_image_format`` is set to ``'png'``. + +.. confval:: imgmath_dvipng_args + + Additional arguments to give to dvipng, as a list. The default value is + ``['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']`` which makes the + image a bit darker and larger then it is by default (this compensates + somewhat for the thinness of default LaTeX math fonts), and produces PNGs with a + transparent background. This option is used only when + ``imgmath_image_format`` is ``'png'``. + +.. confval:: imgmath_dvisvgm + + The command name to invoke ``dvisvgm``. The default is + ``'dvisvgm'``; you may need to set this to a full path if ``dvisvgm`` is not + in the executable search path. This option is only used when + ``imgmath_image_format`` is ``'svg'``. + +.. confval:: imgmath_dvisvgm_args + + Additional arguments to give to dvisvgm, as a list. The default value is + ``['--no-fonts']``, which means that ``dvisvgm`` will render glyphs as path + elements (cf the `dvisvgm FAQ`_). This option is used only when + ``imgmath_image_format`` is ``'svg'``. + +.. confval:: imgmath_embed + + Default: ``False``. If true, encode LaTeX output images within HTML files + (base64 encoded) and do not save separate png/svg files to disk. + + .. versionadded:: 5.2 + +:mod:`sphinx.ext.mathjax` -- Render math via JavaScript +------------------------------------------------------- + +.. module:: sphinx.ext.mathjax + :synopsis: Render math using JavaScript via MathJax. + +.. warning:: + Version 4.0 changes the version of MathJax used to version 3. You may need to + override ``mathjax_path`` to + ``https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML`` + or update your configuration options for version 3 + (see :confval:`mathjax3_config`). + +.. versionadded:: 1.1 + +This extension puts math as-is into the HTML files. The JavaScript package +MathJax_ is then loaded and transforms the LaTeX markup to readable math live in +the browser. + +Because MathJax (and the necessary fonts) is very large, it is not included in +Sphinx but is set to automatically include it from a third-party site. + +.. attention:: + + You should use the math :rst:dir:`directive <math>` and + :rst:role:`role <math>`, not the native MathJax ``$$``, ``\(``, etc. + + +.. confval:: mathjax_path + + The path to the JavaScript file to include in the HTML files in order to load + MathJax. + + The default is the ``https://`` URL that loads the JS files from the + `jsdelivr`__ Content Delivery Network. See the `MathJax Getting Started + page`__ for details. If you want MathJax to be available offline or + without including resources from a third-party site, you have to + download it and set this value to a different path. + + __ https://www.jsdelivr.com/ + + __ https://www.mathjax.org/#gettingstarted + + The path can be absolute or relative; if it is relative, it is relative to + the ``_static`` directory of the built docs. + + For example, if you put MathJax into the static path of the Sphinx docs, this + value would be ``MathJax/MathJax.js``. If you host more than one Sphinx + documentation set on one server, it is advisable to install MathJax in a + shared location. + + You can also give a full ``https://`` URL different from the CDN URL. + +.. confval:: mathjax_options + + The options to script tag for mathjax. For example, you can set integrity + option with following setting:: + + mathjax_options = { + 'integrity': 'sha384-......', + } + + The default is empty (``{}``). + + .. versionadded:: 1.8 + + .. versionchanged:: 4.4.1 + + Allow to change the loading method (async or defer) of MathJax if "async" + or "defer" key is set. + +.. confval:: mathjax3_config + + The configuration options for MathJax v3 (which is used by default). + The given dictionary is assigned to the JavaScript variable + ``window.MathJax``. + For more information, please read `Configuring MathJax`__. + + __ https://docs.mathjax.org/en/latest/web/configuration.html#configuration + + The default is empty (not configured). + + .. versionadded:: 4.0 + +.. confval:: mathjax2_config + + The configuration options for MathJax v2 (which can be loaded via + :confval:`mathjax_path`). + The value is used as a parameter of ``MathJax.Hub.Config()``. + For more information, please read `Using in-line configuration options`__. + + __ https://docs.mathjax.org/en/v2.7-latest/ + configuration.html#using-in-line-configuration-options + + For example:: + + mathjax2_config = { + 'extensions': ['tex2jax.js'], + 'jax': ['input/TeX', 'output/HTML-CSS'], + } + + The default is empty (not configured). + + .. versionadded:: 4.0 + + :confval:`mathjax_config` has been renamed to :confval:`mathjax2_config`. + +.. confval:: mathjax_config + + Former name of :confval:`mathjax2_config`. + + For help converting your old MathJax configuration to to the new + :confval:`mathjax3_config`, see `Converting Your v2 Configuration to v3`__. + + __ https://docs.mathjax.org/en/latest/web/ + configuration.html#converting-your-v2-configuration-to-v3 + + .. versionadded:: 1.8 + + .. versionchanged:: 4.0 + + This has been renamed to :confval:`mathjax2_config`. + :confval:`mathjax_config` is still supported for backwards compatibility. + +:mod:`sphinx.ext.jsmath` -- Render math via JavaScript +------------------------------------------------------ + +.. module:: sphinx.ext.jsmath + :synopsis: Render math using JavaScript via JSMath. + +This extension works just as the MathJax extension does, but uses the older +package jsMath_. It provides this config value: + +.. confval:: jsmath_path + + The path to the JavaScript file to include in the HTML files in order to load + JSMath. There is no default. + + The path can be absolute or relative; if it is relative, it is relative to + the ``_static`` directory of the built docs. + + For example, if you put JSMath into the static path of the Sphinx docs, this + value would be ``jsMath/easy/load.js``. If you host more than one + Sphinx documentation set on one server, it is advisable to install jsMath in + a shared location. + + +.. _dvipng: https://savannah.nongnu.org/projects/dvipng/ +.. _dvisvgm: https://dvisvgm.de/ +.. _dvisvgm FAQ: https://dvisvgm.de/FAQ +.. _MathJax: https://www.mathjax.org/ +.. _jsMath: http://www.math.union.edu/~dpvc/jsmath/ +.. _LaTeX preview package: https://www.gnu.org/software/auctex/preview-latex.html diff --git a/doc/usage/extensions/napoleon.rst b/doc/usage/extensions/napoleon.rst new file mode 100644 index 0000000..d2391da --- /dev/null +++ b/doc/usage/extensions/napoleon.rst @@ -0,0 +1,574 @@ +:mod:`sphinx.ext.napoleon` -- Support for NumPy and Google style docstrings +=========================================================================== + +.. module:: sphinx.ext.napoleon + :synopsis: Support for NumPy and Google style docstrings + +.. moduleauthor:: Rob Ruana + +.. versionadded:: 1.3 + +Overview +-------- + +.. highlight:: text + +Are you tired of writing docstrings that look like this:: + + :param path: The path of the file to wrap + :type path: str + :param field_storage: The :class:`FileStorage` instance to wrap + :type field_storage: FileStorage + :param temporary: Whether or not to delete the file when the File + instance is destructed + :type temporary: bool + :returns: A buffered writable file descriptor + :rtype: BufferedFileStorage + +`reStructuredText`_ is great, but it creates visually dense, hard to read +:pep:`docstrings <287>`. Compare the jumble above to the same thing rewritten +according to the `Google Python Style Guide`_:: + + Args: + path (str): The path of the file to wrap + field_storage (FileStorage): The :class:`FileStorage` instance to wrap + temporary (bool): Whether or not to delete the file when the File + instance is destructed + + Returns: + BufferedFileStorage: A buffered writable file descriptor + +Much more legible, no? + +Napoleon is a :term:`extension` that enables Sphinx to parse both `NumPy`_ and +`Google`_ style docstrings - the style recommended by `Khan Academy`_. + +Napoleon is a pre-processor that parses `NumPy`_ and `Google`_ style +docstrings and converts them to reStructuredText before Sphinx attempts to +parse them. This happens in an intermediate step while Sphinx is processing +the documentation, so it doesn't modify any of the docstrings in your actual +source code files. + +.. _ReStructuredText: https://docutils.sourceforge.io/rst.html +.. _Google Python Style Guide: + https://google.github.io/styleguide/pyguide.html +.. _Google: + https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings +.. _NumPy: + https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard +.. _Khan Academy: + https://github.com/Khan/style-guides/blob/master/style/python.md#docstrings + +Getting Started +~~~~~~~~~~~~~~~ + +1. After :doc:`setting up Sphinx </usage/quickstart>` to build your docs, + enable napoleon in the Sphinx `conf.py` file:: + + # conf.py + + # Add napoleon to the extensions list + extensions = ['sphinx.ext.napoleon'] + +2. Use `sphinx-apidoc` to build your API documentation:: + + $ sphinx-apidoc -f -o docs/source projectdir + + +Docstrings +~~~~~~~~~~ + +Napoleon interprets every docstring that :mod:`autodoc <sphinx.ext.autodoc>` +can find, including docstrings on: ``modules``, ``classes``, ``attributes``, +``methods``, ``functions``, and ``variables``. Inside each docstring, +specially formatted `Sections`_ are parsed and converted to +reStructuredText. + +All standard reStructuredText formatting still works as expected. + + +.. _Sections: + +Docstring Sections +~~~~~~~~~~~~~~~~~~ + +All of the following section headers are supported: + +* ``Args`` *(alias of Parameters)* +* ``Arguments`` *(alias of Parameters)* +* ``Attention`` +* ``Attributes`` +* ``Caution`` +* ``Danger`` +* ``Error`` +* ``Example`` +* ``Examples`` +* ``Hint`` +* ``Important`` +* ``Keyword Args`` *(alias of Keyword Arguments)* +* ``Keyword Arguments`` +* ``Methods`` +* ``Note`` +* ``Notes`` +* ``Other Parameters`` +* ``Parameters`` +* ``Return`` *(alias of Returns)* +* ``Returns`` +* ``Raise`` *(alias of Raises)* +* ``Raises`` +* ``References`` +* ``See Also`` +* ``Tip`` +* ``Todo`` +* ``Warning`` +* ``Warnings`` *(alias of Warning)* +* ``Warn`` *(alias of Warns)* +* ``Warns`` +* ``Yield`` *(alias of Yields)* +* ``Yields`` + +Google vs NumPy +~~~~~~~~~~~~~~~ + +Napoleon supports two styles of docstrings: `Google`_ and `NumPy`_. The +main difference between the two styles is that Google uses indentation to +separate sections, whereas NumPy uses underlines. + +Google style: + +.. code-block:: python + + def func(arg1, arg2): + """Summary line. + + Extended description of function. + + Args: + arg1 (int): Description of arg1 + arg2 (str): Description of arg2 + + Returns: + bool: Description of return value + + """ + return True + +NumPy style: + +.. code-block:: python + + def func(arg1, arg2): + """Summary line. + + Extended description of function. + + Parameters + ---------- + arg1 : int + Description of arg1 + arg2 : str + Description of arg2 + + Returns + ------- + bool + Description of return value + + """ + return True + +NumPy style tends to require more vertical space, whereas Google style +tends to use more horizontal space. Google style tends to be easier to +read for short and simple docstrings, whereas NumPy style tends be easier +to read for long and in-depth docstrings. + +The choice between styles is largely aesthetic, but the two styles should +not be mixed. Choose one style for your project and be consistent with it. + +.. seealso:: + + For complete examples: + + * :ref:`example_google` + * :ref:`example_numpy` + + +Type Annotations +~~~~~~~~~~~~~~~~ + +:pep:`484` introduced a standard way to express types in Python code. +This is an alternative to expressing types directly in docstrings. +One benefit of expressing types according to :pep:`484` is that +type checkers and IDEs can take advantage of them for static code +analysis. :pep:`484` was then extended by :pep:`526` which introduced +a similar way to annotate variables (and attributes). + +Google style with Python 3 type annotations:: + + def func(arg1: int, arg2: str) -> bool: + """Summary line. + + Extended description of function. + + Args: + arg1: Description of arg1 + arg2: Description of arg2 + + Returns: + Description of return value + + """ + return True + + class Class: + """Summary line. + + Extended description of class + + Attributes: + attr1: Description of attr1 + attr2: Description of attr2 + """ + + attr1: int + attr2: str + +Google style with types in docstrings:: + + def func(arg1, arg2): + """Summary line. + + Extended description of function. + + Args: + arg1 (int): Description of arg1 + arg2 (str): Description of arg2 + + Returns: + bool: Description of return value + + """ + return True + + class Class: + """Summary line. + + Extended description of class + + Attributes: + attr1 (int): Description of attr1 + attr2 (str): Description of attr2 + """ + +.. Note:: + `Python 2/3 compatible annotations`_ aren't currently + supported by Sphinx and won't show up in the docs. + +.. _Python 2/3 compatible annotations: https://peps.python.org/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code + + +Configuration +------------- + +Listed below are all the settings used by napoleon and their default +values. These settings can be changed in the Sphinx `conf.py` file. Make +sure that "sphinx.ext.napoleon" is enabled in `conf.py`:: + + # conf.py + + # Add any Sphinx extension module names here, as strings + extensions = ['sphinx.ext.napoleon'] + + # Napoleon settings + napoleon_google_docstring = True + napoleon_numpy_docstring = True + napoleon_include_init_with_doc = False + napoleon_include_private_with_doc = False + napoleon_include_special_with_doc = True + napoleon_use_admonition_for_examples = False + napoleon_use_admonition_for_notes = False + napoleon_use_admonition_for_references = False + napoleon_use_ivar = False + napoleon_use_param = True + napoleon_use_rtype = True + napoleon_preprocess_types = False + napoleon_type_aliases = None + napoleon_attr_annotations = True + +.. _Google style: + https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings +.. _NumPy style: + https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard + +.. confval:: napoleon_google_docstring + + True to parse `Google style`_ docstrings. False to disable support + for Google style docstrings. *Defaults to True.* + +.. confval:: napoleon_numpy_docstring + + True to parse `NumPy style`_ docstrings. False to disable support + for NumPy style docstrings. *Defaults to True.* + +.. confval:: napoleon_include_init_with_doc + + True to list ``__init___`` docstrings separately from the class + docstring. False to fall back to Sphinx's default behavior, which + considers the ``__init___`` docstring as part of the class + documentation. *Defaults to False.* + + **If True**:: + + def __init__(self): + """ + This will be included in the docs because it has a docstring + """ + + def __init__(self): + # This will NOT be included in the docs + +.. confval:: napoleon_include_private_with_doc + + True to include private members (like ``_membername``) with docstrings + in the documentation. False to fall back to Sphinx's default behavior. + *Defaults to False.* + + **If True**:: + + def _included(self): + """ + This will be included in the docs because it has a docstring + """ + pass + + def _skipped(self): + # This will NOT be included in the docs + pass + +.. confval:: napoleon_include_special_with_doc + + True to include special members (like ``__membername__``) with + docstrings in the documentation. False to fall back to Sphinx's + default behavior. *Defaults to True.* + + **If True**:: + + def __str__(self): + """ + This will be included in the docs because it has a docstring + """ + return unicode(self).encode('utf-8') + + def __unicode__(self): + # This will NOT be included in the docs + return unicode(self.__class__.__name__) + +.. confval:: napoleon_use_admonition_for_examples + + True to use the ``.. admonition::`` directive for the **Example** and + **Examples** sections. False to use the ``.. rubric::`` directive + instead. One may look better than the other depending on what HTML + theme is used. *Defaults to False.* + + This `NumPy style`_ snippet will be converted as follows:: + + Example + ------- + This is just a quick example + + **If True**:: + + .. admonition:: Example + + This is just a quick example + + **If False**:: + + .. rubric:: Example + + This is just a quick example + +.. confval:: napoleon_use_admonition_for_notes + + True to use the ``.. admonition::`` directive for **Notes** sections. + False to use the ``.. rubric::`` directive instead. *Defaults to False.* + + .. note:: The singular **Note** section will always be converted to a + ``.. note::`` directive. + + .. seealso:: + + :confval:`napoleon_use_admonition_for_examples` + +.. confval:: napoleon_use_admonition_for_references + + True to use the ``.. admonition::`` directive for **References** + sections. False to use the ``.. rubric::`` directive instead. + *Defaults to False.* + + .. seealso:: + + :confval:`napoleon_use_admonition_for_examples` + +.. confval:: napoleon_use_ivar + + True to use the ``:ivar:`` role for instance variables. False to use + the ``.. attribute::`` directive instead. *Defaults to False.* + + This `NumPy style`_ snippet will be converted as follows:: + + Attributes + ---------- + attr1 : int + Description of `attr1` + + **If True**:: + + :ivar attr1: Description of `attr1` + :vartype attr1: int + + **If False**:: + + .. attribute:: attr1 + + Description of `attr1` + + :type: int + +.. confval:: napoleon_use_param + + True to use a ``:param:`` role for each function parameter. False to + use a single ``:parameters:`` role for all the parameters. + *Defaults to True.* + + This `NumPy style`_ snippet will be converted as follows:: + + Parameters + ---------- + arg1 : str + Description of `arg1` + arg2 : int, optional + Description of `arg2`, defaults to 0 + + **If True**:: + + :param arg1: Description of `arg1` + :type arg1: str + :param arg2: Description of `arg2`, defaults to 0 + :type arg2: :class:`int`, *optional* + + **If False**:: + + :parameters: * **arg1** (*str*) -- + Description of `arg1` + * **arg2** (*int, optional*) -- + Description of `arg2`, defaults to 0 + +.. confval:: napoleon_use_keyword + + True to use a ``:keyword:`` role for each function keyword argument. + False to use a single ``:keyword arguments:`` role for all the + keywords. + *Defaults to True.* + + This behaves similarly to :confval:`napoleon_use_param`. Note unlike docutils, + ``:keyword:`` and ``:param:`` will not be treated the same way - there will + be a separate "Keyword Arguments" section, rendered in the same fashion as + "Parameters" section (type links created if possible) + + .. seealso:: + + :confval:`napoleon_use_param` + +.. confval:: napoleon_use_rtype + + True to use the ``:rtype:`` role for the return type. False to output + the return type inline with the description. *Defaults to True.* + + This `NumPy style`_ snippet will be converted as follows:: + + Returns + ------- + bool + True if successful, False otherwise + + **If True**:: + + :returns: True if successful, False otherwise + :rtype: bool + + **If False**:: + + :returns: *bool* -- True if successful, False otherwise + +.. confval:: napoleon_preprocess_types + + True to convert the type definitions in the docstrings as references. + Defaults to *False*. + + .. versionadded:: 3.2.1 + .. versionchanged:: 3.5 + + Do preprocess the Google style docstrings also. + +.. confval:: napoleon_type_aliases + + A mapping to translate type names to other names or references. Works + only when ``napoleon_use_param = True``. *Defaults to None.* + + With:: + + napoleon_type_aliases = { + "CustomType": "mypackage.CustomType", + "dict-like": ":term:`dict-like <mapping>`", + } + + This `NumPy style`_ snippet:: + + Parameters + ---------- + arg1 : CustomType + Description of `arg1` + arg2 : dict-like + Description of `arg2` + + becomes:: + + :param arg1: Description of `arg1` + :type arg1: mypackage.CustomType + :param arg2: Description of `arg2` + :type arg2: :term:`dict-like <mapping>` + + .. versionadded:: 3.2 + +.. confval:: napoleon_attr_annotations + + True to allow using :pep:`526` attributes annotations in classes. + If an attribute is documented in the docstring without a type and + has an annotation in the class body, that type is used. + + .. versionadded:: 3.4 + +.. confval:: napoleon_custom_sections + + Add a list of custom sections to include, expanding the list of parsed sections. + *Defaults to None.* + + The entries can either be strings or tuples, depending on the intention: + + * To create a custom "generic" section, just pass a string. + * To create an alias for an existing section, pass a tuple containing the + alias name and the original, in that order. + * To create a custom section that displays like the parameters or returns + section, pass a tuple containing the custom section name and a string + value, "params_style" or "returns_style". + + If an entry is just a string, it is interpreted as a header for a generic + section. If the entry is a tuple/list/indexed container, the first entry + is the name of the section, the second is the section key to emulate. If the + second entry value is "params_style" or "returns_style", the custom section + will be displayed like the parameters section or returns section. + + .. versionadded:: 1.8 + .. versionchanged:: 3.5 + Support ``params_style`` and ``returns_style`` diff --git a/doc/usage/extensions/todo.rst b/doc/usage/extensions/todo.rst new file mode 100644 index 0000000..bf8b922 --- /dev/null +++ b/doc/usage/extensions/todo.rst @@ -0,0 +1,62 @@ +:mod:`sphinx.ext.todo` -- Support for todo items +================================================ + +.. module:: sphinx.ext.todo + :synopsis: Allow inserting todo items into documents. +.. moduleauthor:: Daniel Bültmann + +.. versionadded:: 0.5 + +There are two additional directives when using this extension: + +.. rst:directive:: todo + + Use this directive like, for example, :rst:dir:`note`. + + It will only show up in the output if :confval:`todo_include_todos` is + ``True``. + + .. versionadded:: 1.3.2 + This directive supports an ``class`` option that determines the class + attribute for HTML output. If not given, the class defaults to + ``admonition-todo``. + + +.. rst:directive:: todolist + + This directive is replaced by a list of all todo directives in the whole + documentation, if :confval:`todo_include_todos` is ``True``. + + +These can be configured as seen below. + +Configuration +------------- + +.. confval:: todo_include_todos + + If this is ``True``, :rst:dir:`todo` and :rst:dir:`todolist` produce output, + else they produce nothing. The default is ``False``. + +.. confval:: todo_emit_warnings + + If this is ``True``, :rst:dir:`todo` emits a warning for each TODO entries. + The default is ``False``. + + .. versionadded:: 1.5 + +.. confval:: todo_link_only + + If this is ``True``, :rst:dir:`todolist` produce output without file path and + line, The default is ``False``. + + .. versionadded:: 1.4 + +autodoc provides the following an additional event: + +.. event:: todo-defined (app, node) + + .. versionadded:: 1.5 + + Emitted when a todo is defined. *node* is the defined + ``sphinx.ext.todo.todo_node`` node. diff --git a/doc/usage/extensions/viewcode.rst b/doc/usage/extensions/viewcode.rst new file mode 100644 index 0000000..c90d2ba --- /dev/null +++ b/doc/usage/extensions/viewcode.rst @@ -0,0 +1,106 @@ +:mod:`sphinx.ext.viewcode` -- Add links to highlighted source code +================================================================== + +.. module:: sphinx.ext.viewcode + :synopsis: Add links to a highlighted version of the source code. +.. moduleauthor:: Georg Brandl + +.. versionadded:: 1.0 + +This extension looks at your Python object descriptions (``.. class::``, ``.. +function::`` etc.) and tries to find the source files where the objects are +contained. When found, a separate HTML page will be output for each module with +a highlighted version of the source code, and a link will be added to all object +descriptions that leads to the source code of the described object. A link back +from the source to the description will also be inserted. + +.. warning:: + + Basically, ``viewcode`` extension will import the modules being linked to. + If any modules have side effects on import, these will be executed 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. + + In addition, if you don't want to import the modules by ``viewcode``, + you can tell the location of the location of source code to ``viewcode`` + using the :event:`viewcode-find-source` event. + + If :confval:`viewcode_follow_imported_members` is enabled, + you will also need to resolve imported attributes + using the :event:`viewcode-follow-imported` event. + +This extension works only on HTML related builders like ``html``, +``applehelp``, ``devhelp``, ``htmlhelp``, ``qthelp`` and so on except +``singlehtml``. By default ``epub`` builder doesn't +support this extension (see :confval:`viewcode_enable_epub`). + +Configuration +------------- + +.. confval:: viewcode_follow_imported_members + + If this is ``True``, viewcode extension will emit + :event:`viewcode-follow-imported` event to resolve the name of the module + by other extensions. The default is ``True``. + + .. versionadded:: 1.3 + + .. versionchanged:: 1.8 + Renamed from ``viewcode_import`` to ``viewcode_follow_imported_members``. + +.. confval:: viewcode_enable_epub + + If this is ``True``, viewcode extension is also enabled even if you use + epub builders. This extension generates pages outside toctree, but this + is not preferred as epub format. + + Until 1.4.x, this extension is always enabled. If you want to generate + epub as same as 1.4.x, you should set ``True``, but epub format checker's + score becomes worse. + + The default is ``False``. + + .. versionadded:: 1.5 + + .. warning:: + + Not all epub readers support pages generated by viewcode extension. + These readers ignore links to pages are not under toctree. + + Some reader's rendering result are corrupted and + `epubcheck <https://github.com/IDPF/epubcheck>`_'s score + becomes worse even if the reader supports. + +.. confval:: viewcode_line_numbers + + Default: ``False``. + + If set to ``True``, inline line numbers will be added to the highlighted code. + + .. versionadded:: 7.2 + +.. event:: viewcode-find-source (app, modname) + + .. versionadded:: 1.8 + + Find the source code for a module. + An event handler for this event should return + a tuple of the source code itself and a dictionary of tags. + The dictionary maps the name of a class, function, attribute, etc + to a tuple of its type, the start line number, and the end line number. + The type should be one of "class", "def", or "other". + + :param app: The Sphinx application object. + :param modname: The name of the module to find source code for. + +.. event:: viewcode-follow-imported (app, modname, attribute) + + .. versionadded:: 1.8 + + Find the name of the original module for an attribute. + + :param app: The Sphinx application object. + :param modname: The name of the module that the attribute belongs to. + :param attribute: The name of the member to follow. diff --git a/doc/usage/index.rst b/doc/usage/index.rst new file mode 100644 index 0000000..fd8cdd8 --- /dev/null +++ b/doc/usage/index.rst @@ -0,0 +1,20 @@ +============ +Using Sphinx +============ + +This guide serves to demonstrate how one can get started with Sphinx and covers +everything from installing Sphinx and configuring your first Sphinx project to +using some of the advanced features Sphinx provides out-of-the-box. If you are +looking for guidance on extending Sphinx, refer to :doc:`/development/index`. + +.. toctree:: + :maxdepth: 2 + + restructuredtext/index + markdown + configuration + builders/index + extensions/index + theming + advanced/intl + advanced/websupport/index diff --git a/doc/usage/installation.rst b/doc/usage/installation.rst new file mode 100644 index 0000000..e85603e --- /dev/null +++ b/doc/usage/installation.rst @@ -0,0 +1,282 @@ +================= +Installing Sphinx +================= + +.. contents:: + :depth: 1 + :local: + :backlinks: none + +.. highlight:: console + +Overview +-------- + +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://docs.python-guide.org/ +__ https://docutils.sourceforge.io/ +__ https://jinja.palletsprojects.com/ + + +Linux +----- + +Debian/Ubuntu +~~~~~~~~~~~~~ + +Install either ``python3-sphinx`` using :command:`apt-get`: + +:: + + $ apt-get install python3-sphinx + +If it not already present, this will install Python for you. + +RHEL, CentOS +~~~~~~~~~~~~ + +Install ``python-sphinx`` using :command:`yum`: + +:: + + $ yum install python-sphinx + +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 +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`__. + +__ https://brew.sh/ +__ https://www.macports.org/ +__ https://www.anaconda.com/download/#macos + +Homebrew +~~~~~~~~ + +:: + + $ brew install sphinx-doc + +For more information, refer to the `package overview`__. + +__ https://formulae.brew.sh/formula/sphinx-doc + +MacPorts +~~~~~~~~ + +Install either ``python3x-sphinx`` using :command:`port`: + +:: + + $ sudo port install py39-sphinx + +To set up the executable paths, use the ``port select`` command: + +:: + + $ sudo port select --set python python39 + $ sudo port select --set sphinx py39-sphinx + +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>`. + +__ https://chocolatey.org/ + +Chocolatey +~~~~~~~~~~ + +:: + + $ choco install sphinx + +You would need to `install Chocolatey +<https://chocolatey.org/install>`_ +before running this. + +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 + +You can read more about them in the `Python Packaging User Guide`_. + +.. _Python Packaging User Guide: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment + +.. 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 +------ + +Docker images for Sphinx are published on the `Docker Hub`_. There are two kind +of images: + +- `sphinxdoc/sphinx`_ +- `sphinxdoc/sphinx-latexpdf`_ + +.. _Docker Hub: https://hub.docker.com/ +.. _sphinxdoc/sphinx: https://hub.docker.com/r/sphinxdoc/sphinx +.. _sphinxdoc/sphinx-latexpdf: https://hub.docker.com/r/sphinxdoc/sphinx-latexpdf + +Former one is used for standard usage of Sphinx, and latter one is mainly used for +PDF builds using LaTeX. Please choose one for your purpose. + +.. note:: + + sphinxdoc/sphinx-latexpdf contains TeXLive packages. So the image is very large + (over 2GB!). + +.. hint:: + + When using docker images, please use ``docker run`` command to invoke sphinx + commands. For example, you can use following command to create a Sphinx + project: + + .. code-block:: console + + $ docker run -it --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-quickstart + + And you can use the following command to build HTML document: + + .. code-block:: console + + $ docker run --rm -v /path/to/document:/docs sphinxdoc/sphinx make html + +For more details, please read `README file`__ of docker images. + +.. __: https://hub.docker.com/r/sphinxdoc/sphinx + + +Installation from source +------------------------ + +You can install Sphinx directly from a clone of the `Git repository`__. This +can be done either by cloning the repo and installing from the local clone, on +simply installing directly via :command:`git`. + +:: + + $ git clone https://github.com/sphinx-doc/sphinx + $ cd sphinx + $ pip install . + +:: + + $ pip install git+https://github.com/sphinx-doc/sphinx + +You can also download a snapshot of the Git repo in either `tar.gz`__ or +`zip`__ format. Once downloaded and extracted, these can be installed with +:command:`pip` as above. + +.. highlight:: default + +__ https://github.com/sphinx-doc/sphinx +__ https://github.com/sphinx-doc/sphinx/archive/master.tar.gz +__ https://github.com/sphinx-doc/sphinx/archive/master.zip diff --git a/doc/usage/markdown.rst b/doc/usage/markdown.rst new file mode 100644 index 0000000..ac24f8d --- /dev/null +++ b/doc/usage/markdown.rst @@ -0,0 +1,52 @@ +.. highlight:: python + +.. _markdown: + +======== +Markdown +======== + +`Markdown`__ is a lightweight markup language with a simplistic plain text +formatting syntax. It exists in many syntactically different *flavors*. To +support Markdown-based documentation, Sphinx can use `MyST-Parser`__. +MyST-Parser is a Docutils bridge to `markdown-it-py`__, a Python package for +parsing the `CommonMark`__ Markdown flavor. + +__ https://daringfireball.net/projects/markdown/ +__ https://myst-parser.readthedocs.io/en/latest/ +__ https://github.com/executablebooks/markdown-it-py +__ https://commonmark.org/ + +Configuration +------------- + +To configure your Sphinx project for Markdown support, proceed as follows: + +#. Install the Markdown parser *MyST-Parser*:: + + pip install --upgrade myst-parser + +#. Add *myst_parser* to the + :confval:`list of configured extensions <extensions>`:: + + extensions = ['myst_parser'] + + .. note:: + MyST-Parser requires Sphinx 2.1 or newer. + +#. If you want to use Markdown files with extensions other than ``.md``, adjust + the :confval:`source_suffix` variable. The following example configures + Sphinx to parse all files with the extensions ``.md`` and ``.txt`` as + Markdown:: + + source_suffix = { + '.rst': 'restructuredtext', + '.txt': 'markdown', + '.md': 'markdown', + } + +#. You can further configure *MyST-Parser* to allow custom syntax that + standard *CommonMark* doesn't support. Read more in the `MyST-Parser + documentation`__. + +__ https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst new file mode 100644 index 0000000..0773f60 --- /dev/null +++ b/doc/usage/quickstart.rst @@ -0,0 +1,348 @@ +=============== +Getting Started +=============== + +Sphinx is a *documentation generator* or a tool that translates a set of plain +text source files into various output formats, automatically producing +cross-references, indices, etc. That is, if you have a directory containing a +bunch of :doc:`/usage/restructuredtext/index` or :doc:`/usage/markdown` +documents, Sphinx can generate a series of HTML files, a PDF file (via LaTeX), +man pages and much more. + +Sphinx focuses on documentation, in particular handwritten documentation, +however, Sphinx can also be used to generate blogs, homepages and even books. +Much of Sphinx's power comes from the richness of its default plain-text markup +format, :doc:`reStructuredText </usage/restructuredtext/index>`, along with +its :doc:`significant extensibility capabilities </development/index>`. + +The goal of this document is to give you a quick taste of what Sphinx is and +how you might use it. When you're done here, you can check out the +:doc:`installation guide </usage/installation>` followed by the intro to the +default markup format used by Sphinx, :doc:`reStucturedText +</usage/restructuredtext/index>`. + +For a great "introduction" to writing docs in general -- the whys and hows, see +also `Write the docs`__, written by Eric Holscher. + +.. __: https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/ + + +Setting up the documentation sources +------------------------------------ + +The root directory of a Sphinx collection of plain-text document sources is +called the :term:`source directory`. This directory also contains the Sphinx +configuration file :file:`conf.py`, where you can configure all aspects of how +Sphinx reads your sources and builds your documentation. [#]_ + +Sphinx comes with a script called :program:`sphinx-quickstart` that sets up a +source directory and creates a default :file:`conf.py` with the most useful +configuration values from a few questions it asks you. To use this, run: + +.. code-block:: console + + $ sphinx-quickstart + + +Defining document structure +--------------------------- + +Let's assume you've run :program:`sphinx-quickstart`. It created a source +directory with :file:`conf.py` and a root document, :file:`index.rst`. The +main function of the :term:`root document` is to serve as a welcome page, and +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 + + ``toctree`` is a reStructuredText :dfn:`directive`, a very versatile piece + of markup. Directives can have arguments, options and content. + + *Arguments* are given directly after the double colon following the + directive's name. Each directive decides whether it can have arguments, and + how many. + + *Options* are given after the arguments, in form of a "field list". The + ``maxdepth`` is such an option for the ``toctree`` directive. + + *Content* follows the options or arguments after a blank line. Each + directive decides whether to allow content, and what to do with it. + + A common gotcha with directives is that **the first line of the content must + be indented to the same level as the options are**. + +The ``toctree`` directive initially is empty, and looks like so: + +.. code-block:: rst + + .. toctree:: + :maxdepth: 2 + +You add documents listing them in the *content* of the directive: + +.. code-block:: rst + + .. toctree:: + :maxdepth: 2 + + usage/installation + usage/quickstart + ... + +This is exactly how the ``toctree`` for this documentation looks. The +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>`. + +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 +place where the ``toctree`` directive is placed. Also, Sphinx now knows about +the order and hierarchy of your documents. (They may contain ``toctree`` +directives themselves, which means you can create deeply nested hierarchies if +necessary.) + + +Adding content +-------------- + +In Sphinx source files, you can use most features of standard +:term:`reStructuredText`. There are also several features added by Sphinx. +For example, you can add cross-file references in a portable way (which works +for all output types) using the :rst:role:`ref` role. + +For an example, if you are viewing the HTML version, you can look at the source +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. + + +Running the build +----------------- + +Now that you have added some files and content, let's make a first build of the +docs. A build is started with the :program:`sphinx-build` program: + +.. code-block:: console + + $ sphinx-build -b html sourcedir builddir + +where *sourcedir* is the :term:`source directory`, and *builddir* is the +directory in which you want to place the built documentation. +The :option:`-b <sphinx-build -b>` 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. + +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 +running :command:`make` with the name of the builder. For example. + +.. code-block:: console + + $ make html + +This will build HTML docs in the build directory you chose. Execute +:command:`make` without an argument to see which targets are available. + +.. admonition:: How do I generate PDF documents? + + ``make latexpdf`` runs the :mod:`LaTeX builder + <sphinx.builders.latex.LaTeXBuilder>` and readily invokes the pdfTeX + toolchain for you. + + +.. todo:: Move this whole section into a guide on rST or directives + +Documenting objects +------------------- + +One of Sphinx's main objectives is easy documentation of :dfn:`objects` (in a +very general sense) in any :dfn:`domain`. A domain is a collection of object +types that belong together, complete with markup to create and reference +descriptions of these objects. + +The most prominent domain is the Python domain. For example, to document +Python's built-in function ``enumerate()``, you would add this to one of your +source files. + +.. code-block:: rst + + .. py:function:: enumerate(sequence[, start=0]) + + Return an iterator that yields tuples of an index and an item of the + *sequence*. (And so on.) + +This is rendered like this: + +.. py:function:: enumerate(sequence[, start=0]) + + Return an iterator that yields tuples of an index and an item of the + *sequence*. (And so on.) + +The argument of the directive is the :dfn:`signature` of the object you +describe, the content is the documentation for it. Multiple signatures can be +given, each in its own line. + +The Python domain also happens to be the default domain, so you don't need to +prefix the markup with the domain name. + +.. code-block:: rst + + .. function:: enumerate(sequence[, start=0]) + + ... + +does the same job if you keep the default setting for the default domain. + +There are several more directives for documenting other types of Python +objects, for example :rst:dir:`py:class` or :rst:dir:`py:method`. There is +also a cross-referencing :dfn:`role` for each of these object types. This +markup will create a link to the documentation of ``enumerate()``. + +:: + + The :py:func:`enumerate` function can be used for ... + +And here is the proof: A link to :func:`enumerate`. + +Again, the ``py:`` can be left out if the Python domain is the default one. It +doesn't matter which file contains the actual documentation for +``enumerate()``; Sphinx will find it and create a link to it. + +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/restructuredtext/domains` for all the available domains +and their directives/roles. + + +Basic configuration +------------------- + +Earlier we mentioned that the :file:`conf.py` file controls how Sphinx +processes your documents. In that file, which is executed as a Python source +file, you assign configuration values. For advanced users: since it is +executed by Sphinx, you can do non-trivial tasks in it, like extending +:data:`sys.path` or importing a module to find out the version you are +documenting. + +The config values that you probably want to change are already put into the +:file:`conf.py` by :program:`sphinx-quickstart` and initially commented out +(with standard Python syntax: a ``#`` comments the rest of the line). To +change the default value, remove the hash sign and modify the value. To +customize a config value that is not automatically added by +:program:`sphinx-quickstart`, just add an additional assignment. + +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. + + +.. todo:: Move this entire doc to a different section + +Autodoc +------- + +When documenting Python code, it is common to put a lot of documentation in the +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 :: + + .. 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 + +Intersphinx +----------- + +Many Sphinx documents including the `Python documentation`_ are published on +the Internet. When you want to make links to such documents from your +documentation, you can do it with :mod:`sphinx.ext.intersphinx`. + +.. _Python documentation: https://docs.python.org/3 + +In order to use intersphinx, you need to activate it in :file:`conf.py` by +putting the string ``'sphinx.ext.intersphinx'`` into the :confval:`extensions` +list and set up the :confval:`intersphinx_mapping` config value. + +For example, to link to ``io.open()`` in the Python library manual, you need to +setup your :confval:`intersphinx_mapping` like:: + + intersphinx_mapping = {'python': ('https://docs.python.org/3', None)} + +And now, you can write a cross-reference like ``:py:func:`io.open```. Any +cross-reference that has no matching target in the current documentation set, +will be looked up in the documentation sets configured in +:confval:`intersphinx_mapping` (this needs access to the URL in order to +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. + + +More topics to be covered +------------------------- + +- :doc:`Other extensions </usage/extensions/index>`: +- Static files +- :doc:`Selecting a theme </usage/theming>` +- :ref:`Templating <templating>` +- Using extensions +- :ref:`Writing extensions <dev-extensions>` + + +.. rubric:: Footnotes + +.. [#] 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/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst new file mode 100644 index 0000000..cc3c615 --- /dev/null +++ b/doc/usage/restructuredtext/basics.rst @@ -0,0 +1,631 @@ +.. highlight:: rst + +.. _rst-primer: + +======================= +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 +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. + + +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. + + +.. _rst-inline-markup: + +Inline markup +------------- + +The standard reST inline markup is quite simple: use + +* one asterisk: ``*text*`` for emphasis (italics), +* two asterisks: ``**text**`` for strong emphasis (boldface), and +* backquotes: ````text```` for code samples. + +If asterisks or backquotes appear in running text and could be confused with +inline markup delimiters, they have to be escaped with a backslash. + +Be aware of some restrictions of this markup: + +* it may not be nested, +* content may not start or end with whitespace: ``* text*`` is wrong, +* it must be separated from surrounding text by non-word characters. Use a + backslash escaped space to work around that: ``thisis\ *one*\ word``. + +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. + + +Lists and Quote-like blocks +--------------------------- + +List markup (:duref:`ref <bullet-lists>`) is natural: just place an asterisk at +the start of a paragraph and indent properly. The same goes for numbered +lists; they can also be autonumbered using a ``#`` sign:: + + * This is a bulleted list. + * It has two items, the second + item uses two lines. + + 1. This is a numbered list. + 2. It has two items too. + + #. This is a numbered list. + #. It has two items too. + +Nested lists are possible, but be aware that they must be separated from the +parent list items by blank lines:: + + * this is + * a list + + * with a nested list + * and some subitems + + * and here the parent list continues + +Definition lists (:duref:`ref <definition-lists>`) are created as follows:: + + term (up to a line of text) + Definition of the term, which must be indented + + and can even consist of multiple paragraphs + + next term + Description. + +Note that the term cannot have more than one line of text. + +Quoted paragraphs (:duref:`ref <block-quotes>`) are created by just indenting +them more than the surrounding paragraphs. + +Line blocks (:duref:`ref <line-blocks>`) are a way of preserving line breaks:: + + | These lines are + | broken exactly like in + | the source file. + +There are also several more special blocks available: + +* field lists (:duref:`ref <field-lists>`, with caveats noted in + :ref:`rst-field-lists`) +* option lists (:duref:`ref <option-lists>`) +* quoted literal blocks (:duref:`ref <quoted-literal-blocks>`) +* doctest blocks (:duref:`ref <doctest-blocks>`) + + +.. _rst-literal-blocks: + +Literal blocks +-------------- + +Literal code blocks (:duref:`ref <literal-blocks>`) are introduced by ending a +paragraph with the special marker ``::``. The literal block must be indented +(and, like all paragraphs, separated from the surrounding ones by blank +lines):: + + This is a normal text paragraph. The next paragraph is a code sample:: + + It is not processed in any way, except + that the indentation is removed. + + It can span multiple lines. + + This is a normal text paragraph again. + +The handling of the ``::`` marker is smart: + +* If it occurs as a paragraph of its own, that paragraph is completely left out + of the document. +* If it is preceded by whitespace, the marker is removed. +* If it is preceded by non-whitespace, the marker is replaced by a single + colon. + +That way, the second sentence in the above example's first paragraph would be +rendered as "The next paragraph is a code sample:". + +Code highlighting can be enabled for these literal blocks on a document-wide +basis using the :rst:dir:`highlight` directive and on a project-wide basis +using the :confval:`highlight_language` configuration option. The +:rst:dir:`code-block` directive can be used to set highlighting on a +block-by-block basis. These directives are discussed later. + + +.. _rst-doctest-blocks: + +Doctest blocks +-------------- + +Doctest blocks (:duref:`ref <doctest-blocks>`) are interactive Python sessions +cut-and-pasted into docstrings. They do not require the +:ref:`literal blocks <rst-literal-blocks>` syntax. The doctest block must end +with a blank line and should *not* end with an unused prompt:: + + >>> 1 + 1 + 2 + +.. _rst-tables: + +Tables +------ + +For *grid tables* (:duref:`ref <grid-tables>`), you have to "paint" the cell +grid yourself. They look like this:: + + +------------------------+------------+----------+----------+ + | Header row, column 1 | Header 2 | Header 3 | Header 4 | + | (header rows optional) | | | | + +========================+============+==========+==========+ + | body row 1, column 1 | column 2 | column 3 | column 4 | + +------------------------+------------+----------+----------+ + | body row 2 | ... | ... | | + +------------------------+------------+----------+----------+ + +*Simple tables* (:duref:`ref <simple-tables>`) are easier to write, but +limited: they must contain more than one row, and the first column cells cannot +contain multiple lines. They look like this:: + + ===== ===== ======= + A B A and B + ===== ===== ======= + False False False + True False False + False True False + True True True + ===== ===== ======= + +Two more syntaxes are supported: *CSV tables* and *List tables*. They use an +*explicit markup block*. Refer to :ref:`table-directives` for more information. + + +Hyperlinks +---------- + +External links +~~~~~~~~~~~~~~ + +Use ```Link text <https://domain.invalid/>`_`` for inline web links. If the +link text should be the web address, you don't need special markup at all, the +parser finds links and mail addresses in ordinary text. + +.. important:: There must be a space between the link text and the opening \< for the URL. + +You can also separate the link and the target definition (:duref:`ref +<hyperlink-targets>`), like this:: + + This is a paragraph that contains `a link`_. + + .. _a link: https://domain.invalid/ + +Internal links +~~~~~~~~~~~~~~ + +Internal linking is done via a special reST role provided by Sphinx, see the +section on specific markup, :ref:`ref-role`. + + +.. _rst-sections: + +Sections +-------- + +Section headers (:duref:`ref <sections>`) are created by underlining (and +optionally overlining) the section title with a punctuation character, at least +as long as the text:: + + ================= + This is a heading + ================= + +Normally, there are no heading levels assigned to certain characters as the +structure is determined from the succession of headings. However, this +convention is used in `Python Developer's Guide for documenting +<https://devguide.python.org/documentation/markup/#sections>`_ which you may +follow: + +* ``#`` with overline, for parts +* ``*`` with overline, for chapters +* ``=`` for sections +* ``-`` for subsections +* ``^`` for subsubsections +* ``"`` for paragraphs + +Of course, you are free to use your own marker characters (see the reST +documentation), and use a deeper nesting level, but keep in mind that most +target formats (HTML, LaTeX) have a limited supported nesting depth. + + +.. _rst-field-lists: + +Field Lists +----------- + +Field lists (:duref:`ref <field-lists>`) are sequences of fields marked up like +this:: + + :fieldname: Field content + +They are commonly used in Python documentation:: + + def my_function(my_arg, my_other_arg): + """A function just for me. + + :param my_arg: The first of my arguments. + :param my_other_arg: The second of my arguments. + + :returns: A message (just for me, of course). + """ + +Sphinx extends standard docutils behavior and intercepts field lists specified +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: + +Roles +----- + +A role or "custom interpreted text role" (:duref:`ref <roles>`) is an inline +piece of explicit markup. It signifies that the enclosed text should be +interpreted in a specific way. Sphinx uses this to provide semantic markup and +cross-referencing of identifiers, as described in the appropriate section. The +general syntax is ``:rolename:`content```. + +Docutils supports the following roles: + +* :durole:`emphasis` -- equivalent of ``*emphasis*`` +* :durole:`strong` -- equivalent of ``**strong**`` +* :durole:`literal` -- equivalent of ````literal```` +* :durole:`subscript` -- subscript text +* :durole:`superscript` -- superscript text +* :durole:`title-reference` -- for titles of books, periodicals, and other + materials + +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, +specially-highlighted paragraphs, comments, and generic directives. + +An explicit markup block begins with a line starting with ``..`` followed by +whitespace and is terminated by the next paragraph at the same level of +indentation. (There needs to be a blank line between explicit markup and +normal paragraphs. This may all sound a bit complicated, but it is intuitive +enough when you write it.) + + +.. _rst-directives: + +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. + +Docutils supports the following directives: + +* Admonitions: :dudir:`attention`, :dudir:`caution`, :dudir:`danger`, + :dudir:`error`, :dudir:`hint`, :dudir:`important`, :dudir:`note`, + :dudir:`tip`, :dudir:`warning` and the generic + :dudir:`admonition <admonitions>`. (Most themes style only "note" and + "warning" specially.) + +* Images: + + - :dudir:`image` (see also Images_ below) + - :dudir:`figure` (an image with caption and optional legend) + +* Additional body elements: + + - :dudir:`contents <table-of-contents>` (a local, i.e. for the current file + only, table of contents) + - :dudir:`container` (a container with a custom class, useful to generate an + outer ``<div>`` in HTML) + - :dudir:`rubric` (a heading without relation to the document sectioning) + - :dudir:`topic`, :dudir:`sidebar` (special highlighted body elements) + - :dudir:`parsed-literal` (literal block that supports inline markup) + - :dudir:`epigraph` (a block quote with optional attribution line) + - :dudir:`highlights`, :dudir:`pull-quote` (block quotes with their own + class attribute) + - :dudir:`compound <compound-paragraph>` (a compound paragraph) + +* Special tables: + + - :dudir:`table` (a table with title) + - :dudir:`csv-table` (a table generated from comma-separated values) + - :dudir:`list-table` (a table generated from a list of lists) + +* Special directives: + + - :dudir:`raw <raw-data-pass-through>` (include raw target-format markup) + - :dudir:`include` (include reStructuredText from another file) -- in Sphinx, + when given an absolute include file path, this directive takes it as + relative to the source directory + + .. _rstclass: + + - :dudir:`class` (assign a class attribute to the next element) + + .. note:: + + When the default domain contains a ``class`` directive, this directive + will be shadowed. Therefore, Sphinx re-exports it as ``rst-class``. + +* HTML specifics: + + - :dudir:`meta` + (generation of HTML ``<meta>`` tags, see also :ref:`html-meta` below) + - :dudir:`title <metadata-document-title>` (override document title) + +* Influencing markup: + + - :dudir:`default-role` (set a new default role) + - :dudir:`role` (create a new role) + + Since these are only per-file, better use Sphinx's facilities for setting the + :confval:`default_role`. + +.. warning:: + + Do *not* use the directives :dudir:`sectnum`, :dudir:`header` and + :dudir:`footer`. + +Directives added by Sphinx are described in :doc:`directives`. + +Basically, a directive consists of a name, arguments, options and content. +(Keep this terminology in mind, it is used in the next chapter describing +custom directives.) Looking at this example, :: + + .. function:: foo(x) + foo(y, z) + :module: some.module.name + + Return a line of text input from the user. + +``function`` is the directive name. It is given two arguments here, the +remainder of the first line and the second line, as well as one option +``module`` (as you can see, options are given in the lines immediately +following the arguments and indicated by the colons). Options must be indented +to the same level as the directive content. + +The directive content follows after a blank line and is indented relative to +the directive start or if options are present, by the same amount as the +options. + +Be careful as the indent is not a fixed number of whitespace, e.g. three, but +any number whitespace. This can be surprising when a fixed indent is used +throughout the document and can make a difference for directives which are +sensitive to whitespace. Compare:: + + .. code-block:: + :caption: A cool example + + The output of this line starts with four spaces. + + .. code-block:: + + The output of this line has no spaces at the beginning. + +In the first code block, the indent for the content was fixated by the option +line to three spaces, consequently the content starts with four spaces. +In the latter the indent was fixed by the content itself to seven spaces, thus +it does not start with a space. + + +Images +------ + +reST supports an image directive (:dudir:`ref <image>`), used like so:: + + .. image:: gnu.png + (options) + +When used within Sphinx, the file name given (here ``gnu.png``) must either be +relative to the source file, or absolute which means that they are relative to +the top source directory. For example, the file ``sketch/spam.rst`` could +refer to the image ``images/spam.png`` as ``../images/spam.png`` or +``/images/spam.png``. + +Sphinx will automatically copy image files over to a subdirectory of the output +directory on building (e.g. the ``_static`` directory for HTML output.) + +Interpretation of image size options (``width`` and ``height``) is as follows: +if the size has no unit or the unit is pixels, the given size will only be +respected for output channels that support pixels. Other units (like ``pt`` for +points) will be used for HTML and LaTeX output (the latter replaces ``pt`` by +``bp`` as this is the TeX unit such that ``72bp=1in``). + +Sphinx extends the standard docutils behavior by allowing an asterisk for the +extension:: + + .. image:: gnu.* + +Sphinx then searches for all images matching the provided pattern and +determines their type. Each builder then chooses the best image out of these +candidates. For instance, if the file name ``gnu.*`` was given and two files +:file:`gnu.pdf` and :file:`gnu.png` existed in the source tree, the LaTeX +builder would choose the former, while the HTML builder would prefer the +latter. Supported image types and choosing priority are defined at +:doc:`/usage/builders/index`. + +Note that image file names should not contain spaces. + +.. versionchanged:: 0.4 + Added the support for file names ending in an asterisk. + +.. versionchanged:: 0.6 + Image paths can now be absolute. + +.. versionchanged:: 1.5 + latex target supports pixels (default is ``96px=1in``). + + +Footnotes +--------- + +For footnotes (:duref:`ref <footnotes>`), use ``[#name]_`` to mark the footnote +location, and add the footnote body at the bottom of the document after a +"Footnotes" rubric heading, like so:: + + Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_ + + .. rubric:: Footnotes + + .. [#f1] Text of the first footnote. + .. [#f2] Text of the second footnote. + +You can also explicitly number the footnotes (``[1]_``) or use auto-numbered +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:: + + Lorem ipsum [Ref]_ dolor sit amet. + + .. [Ref] Book or article reference, URL or whatever. + +Citation usage is similar to footnote usage, but with a label that is not +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:: + + .. |name| replace:: replacement *text* + +or this:: + + .. |caution| image:: warning.png + :alt: Warning! + +See the :duref:`reST reference for substitutions <substitution-definitions>` +for details. + +.. index:: ! pair: global; substitutions + +If you want to use some substitutions for all documents, put them into +:confval:`rst_prolog` or :confval:`rst_epilog` or put them into a separate file +and include it into all documents you want to use them in, using the +:dudir:`include` directive. (Be sure to give the include file a file name +extension differing from that of other source files, to avoid Sphinx finding it +as a standalone document.) + +Sphinx defines some default substitutions, see :ref:`default-substitutions`. + + +Comments +-------- + +Every explicit markup block which isn't a valid markup construct (like the +footnotes above) is regarded as a comment (:duref:`ref <comments>`). For +example:: + + .. This is a comment. + +You can indent text after a comment start to form multiline comments:: + + .. + This whole indented block + is a comment. + + Still in the comment. + + +.. _html-meta: + +HTML Metadata +------------- + +The :dudir:`meta` directive allows specifying the HTML +`metadata element`_ of a Sphinx documentation page. For example, the +directive:: + + .. meta:: + :description: The Sphinx documentation builder + :keywords: Sphinx, documentation, builder + +will generate the following HTML output: + +.. code:: html + + <meta name="description" content="The Sphinx documentation builder"> + <meta name="keywords" content="Sphinx, documentation, builder"> + +Also, Sphinx will add the keywords as specified in the meta directive to the +search index. Thereby, the ``lang`` attribute of the meta element is +considered. For example, the directive:: + + .. meta:: + :keywords: backup + :keywords lang=en: pleasefindthiskey pleasefindthiskeytoo + :keywords lang=de: bittediesenkeyfinden + +adds the following words to the search indices of builds with different language +configurations: + +* ``pleasefindthiskey``, ``pleasefindthiskeytoo`` to *English* builds; +* ``bittediesenkeyfinden`` to *German* builds; +* ``backup`` to builds in all languages. + +.. _metadata element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta + + +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 +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. + + +Gotchas +------- + +There are some problems one commonly runs into while authoring reST 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 + backslash-escaped space to get around that. See :duref:`the reference + <substitution-definitions>` for the details. + +* **No nested inline markup:** Something like ``*see :func:`foo`*`` is not + possible. diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst new file mode 100644 index 0000000..1fd5b66 --- /dev/null +++ b/doc/usage/restructuredtext/directives.rst @@ -0,0 +1,1311 @@ +.. highlight:: rst + +========== +Directives +========== + +:ref:`As previously discussed <rst-directives>`, a directive is a generic block +of explicit markup. While Docutils provides a number of directives, Sphinx +provides many more and uses directives as one of the primary extension +mechanisms. + +See :doc:`/usage/restructuredtext/domains` for roles added by domains. + +.. seealso:: + + Refer to the :ref:`reStructuredText Primer <rst-directives>` for an overview + of the directives provided by Docutils. + + +.. _toctree-directive: + +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. + +.. note:: + + Simple "inclusion" of one file in another can be done with the + :dudir:`include` directive. + +.. note:: + + To create table of contents for current document (.rst file), use the + standard reST :dudir:`contents directive <table-of-contents>`. + +.. rst:directive:: toctree + + This directive inserts a "TOC tree" at the current location, using the + individual TOCs (including "sub-TOC trees") of the documents given in the + directive body. Relative document names (not beginning with a slash) are + relative to the document the directive occurs in, absolute names are relative + to the source directory. A numeric ``maxdepth`` option may be given to + indicate the depth of the tree; by default, all levels are included. [#]_ + + The representation of "TOC tree" is changed in each output format. The + builders that output multiple files (ex. HTML) treat it as a collection of + hyperlinks. On the other hand, the builders that output a single file (ex. + LaTeX, man page, etc.) replace it with the content of the documents on the + TOC tree. + + Consider this example (taken from the Python docs' library reference index):: + + .. toctree:: + :maxdepth: 2 + + intro + strings + datatypes + numeric + (many more documents listed here) + + This accomplishes two things: + + * Tables of contents from all those documents are inserted, with a maximum + depth of two, that means one nested heading. ``toctree`` directives in + those documents are also taken into account. + * Sphinx knows the relative order of the documents ``intro``, + ``strings`` and so forth, and it knows that they are children of the shown + document, the library index. From this information it generates "next + chapter", "previous chapter" and "parent chapter" links. + + **Entries** + + 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 + hyperlinks (and Sphinx's :ref:`cross-referencing syntax <xref-syntax>`). This + looks like:: + + .. toctree:: + + intro + All about strings <strings> + datatypes + + The second line above will link to the ``strings`` document, but will use the + title "All about strings" instead of the title of the ``strings`` document. + + You can also add external links, by giving an HTTP URL instead of a document + name. + + **Section numbering** + + If you want to have section numbers even in HTML output, give the + **toplevel** toctree a ``numbered`` option. For example:: + + .. toctree:: + :numbered: + + foo + bar + + Numbering then starts at the heading of ``foo``. Sub-toctrees are + automatically numbered (don't give the ``numbered`` flag to those). + + Numbering up to a specific depth is also possible, by giving the depth as a + numeric argument to ``numbered``. + + **Additional options** + + You can use the ``caption`` option to provide a toctree caption and you can + use the ``name`` option to provide an implicit target name that can be + referenced by using :rst:role:`ref`:: + + .. toctree:: + :caption: Table of Contents + :name: mastertoc + + foo + + If you want only the titles of documents in the tree to show up, not other + headings of the same level, you can use the ``titlesonly`` option:: + + .. toctree:: + :titlesonly: + + foo + bar + + You can use "globbing" in toctree directives, by giving the ``glob`` flag + option. All entries are then matched against the list of available + documents, and matches are inserted into the list alphabetically. Example:: + + .. toctree:: + :glob: + + intro* + recipe/* + * + + This includes first all documents whose names start with ``intro``, then all + documents in the ``recipe`` folder, then all remaining documents (except the + one containing the directive, of course.) [#]_ + + The special entry name ``self`` stands for the document containing the + toctree directive. This is useful if you want to generate a "sitemap" from + the toctree. + + You can use the ``reversed`` flag option to reverse the order of the entries + in the list. This can be useful when using the ``glob`` flag option to + reverse the ordering of the files. Example:: + + .. toctree:: + :glob: + :reversed: + + recipe/* + + You can also give a "hidden" option to the directive, like this:: + + .. toctree:: + :hidden: + + doc_1 + doc_2 + + This will still notify Sphinx of the document hierarchy, but not insert links + into the document at the location of the directive -- this makes sense if you + intend to insert these links yourself, in a different style, or in the HTML + sidebar. + + In cases where you want to have only one top-level toctree and hide all other + lower level toctrees you can add the "includehidden" option to the top-level + toctree entry:: + + .. toctree:: + :includehidden: + + doc_1 + doc_2 + + All other toctree entries can then be eliminated by the "hidden" option. + + In the end, all documents in the :term:`source directory` (or subdirectories) + must occur in some ``toctree`` directive; Sphinx will emit a warning if it + finds a file that is not included, because that means that this file will not + be reachable through standard navigation. + + Use :confval:`exclude_patterns` to explicitly exclude documents or + directories from building completely. Use :ref:`the "orphan" metadata + <metadata>` to let a document be built, but notify Sphinx that it is not + reachable via a toctree. + + The "root document" (selected by :confval:`root_doc`) is the "root" of the TOC + tree hierarchy. It can be used as the documentation's main page, or as a + "full table of contents" if you don't give a ``maxdepth`` option. + + .. versionchanged:: 0.3 + Added "globbing" option. + + .. versionchanged:: 0.6 + Added "numbered" and "hidden" options as well as external links and + support for "self" references. + + .. versionchanged:: 1.0 + Added "titlesonly" option. + + .. versionchanged:: 1.1 + Added numeric argument to "numbered". + + .. versionchanged:: 1.2 + Added "includehidden" option. + + .. versionchanged:: 1.3 + Added "caption" and "name" option. + +Special names +^^^^^^^^^^^^^ + +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`` + + These are used for the general index, the Python module index, and the search + page, respectively. + + The general index is populated with entries from modules, all + index-generating :ref:`object descriptions <basic-domain-markup>`, and from + :rst:dir:`index` directives. + + The Python module index contains one entry per :rst:dir:`py:module` + directive. + + The search page contains a form that uses the generated JSON search index and + JavaScript to full-text search the generated documents for search words; it + should work on every major browser that supports modern JavaScript. + +* every name beginning with ``_`` + + Though few such names are currently used by Sphinx, you should not + create documents or document-containing directories with such names. (Using + ``_`` as a prefix for a custom template directory is fine.) + +.. warning:: + + Be careful with unusual characters in filenames. Some formats may interpret + these characters in unexpected ways: + + * 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. + +.. 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. + + Example:: + + .. note:: + + This function is not suitable for sending spam e-mails. + +.. 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. + +.. rst:directive:: .. versionadded:: version + + This directive documents the version of the project which added the described + feature to the library or C API. When this applies to an entire module, it + should be placed at the top of the module section before any prose. + + The first argument must be given and is the version in question; you can add + a second argument consisting of a *brief* explanation of the change. + + Example:: + + .. versionadded:: 2.5 + The *spam* parameter. + + Note that there must be no blank line between the directive head and the + explanation; this is to make these blocks visually continuous in the markup. + +.. rst:directive:: .. versionchanged:: version + + 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 + + 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:: + + .. deprecated:: 3.1 + Use :func:`spam` instead. + +.. 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. For the HTML output, it is shown boxed off from the main + flow of the text. + + The content of the :rst:dir:`seealso` directive should be a reST definition + list. Example:: + + .. seealso:: + + Module :py:mod:`zipfile` + Documentation of the :py:mod:`zipfile` standard module. + + `GNU tar manual, Basic Tar Format <http://link>`_ + Documentation for tar archive files, including GNU tar extensions. + + There's also a "short form" allowed that looks like this:: + + .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile` + + .. versionadded:: 0.5 + The short form. + +.. rst:directive:: .. rubric:: title + + This directive creates a paragraph heading that is not used to create a + table of contents node. + + .. note:: + + If the *title* of the rubric is "Footnotes" (or the selected language's + equivalent), this rubric is ignored by the LaTeX writer, since it is + assumed to only contain footnote definitions and therefore would create an + empty heading. + +.. rst:directive:: centered + + This directive creates a centered boldfaced line of text. Use it as + follows:: + + .. centered:: LICENSE AGREEMENT + + .. deprecated:: 1.1 + This presentation-only directive is a legacy from older versions. + Use a :ref:`rst-class <rstclass>` directive instead and add an + appropriate style. + +.. rst:directive:: hlist + + This directive must contain a bullet list. It will transform it into a more + compact list by either distributing more than one item horizontally, or + reducing spacing between items, depending on the builder. + + For builders that support the horizontal distribution, there is a ``columns`` + option that specifies the number of columns; it defaults to 2. Example:: + + .. hlist:: + :columns: 3 + + * A list of + * short items + * that should be + * displayed + * horizontally + + .. versionadded:: 0.6 + + +.. _code-examples: + +Showing code examples +--------------------- + +.. index:: pair: code; examples + single: sourcecode + +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 + combination with the :rst:dir:`highlight` directive; +* using the :rst:dir:`code-block` directive; +* and using the :rst:dir:`literalinclude` directive. + +Doctest blocks can only be used +to show interactive Python sessions, while the remaining three can be used for +other languages. Of these three, literal blocks are useful when an entire +document, or at least large sections of it, use code blocks with the same +syntax and which should be styled in the same manner. On the other hand, the +:rst:dir:`code-block` directive makes more sense when you want more fine-tuned +control over the styling of each block or when you have a document containing +code blocks using multiple varied syntaxes. Finally, the +:rst:dir:`literalinclude` directive is useful for including entire code files +in your documentation. + +In all cases, Syntax highlighting is provided by `Pygments +<https://pygments.org>`_. When using literal blocks, this is configured using +any :rst:dir:`highlight` directives in the source file. When a ``highlight`` +directive is encountered, it is used until the next ``highlight`` directive is +encountered. If there is no ``highlight`` directive in the file, the global +highlighting language is used. This defaults to ``python`` but can be +configured using the :confval:`highlight_language` config value. The following +values are supported: + +* ``none`` (no highlighting) +* ``default`` (similar to ``python3`` but with a fallback to ``none`` without + warning highlighting fails; the default when :confval:`highlight_language` + isn't set) +* ``guess`` (let Pygments guess the lexer based on contents, only works with + certain well-recognizable languages) +* ``python`` +* ``rest`` +* ``c`` +* ... and any other `lexer alias that Pygments supports`__ + +If highlighting with the selected language fails (i.e. Pygments emits an +"Error" token), the block is not highlighted in any way. + +.. important:: + + The list of lexer aliases supported is tied to the Pygment version. If you + want to ensure consistent highlighting, you should fix your version of + Pygments. + +__ https://pygments.org/docs/lexers + +.. rst:directive:: .. highlight:: language + + Example:: + + .. highlight:: c + + This language is used until the next ``highlight`` directive is encountered. + As discussed previously, *language* can be any lexer alias supported by + Pygments. + + .. rubric:: options + + .. rst:directive:option:: linenothreshold: threshold + :type: number (optional) + + Enable to generate line numbers for code blocks. + + This option takes an optional number as threshold parameter. If any + threshold given, the directive will produce line numbers only for the code + blocks longer than N lines. If not given, line numbers will be produced + for all of code blocks. + + Example:: + + .. highlight:: python + :linenothreshold: 5 + + .. rst:directive:option:: force + :type: no value + + If given, minor errors on highlighting are ignored. + + .. versionadded:: 2.1 + +.. rst:directive:: .. code-block:: [language] + .. sourcecode:: [language] + + Example:: + + .. code-block:: ruby + + Some Ruby code. + + The directive's alias name :rst:dir:`sourcecode` works as well. This + directive takes a language name as an argument. It can be `any lexer alias + supported by Pygments <https://pygments.org/docs/lexers/>`_. If it is not + given, the setting of :rst:dir:`highlight` directive will be used. If not + set, :confval:`highlight_language` will be used. To display a code example + *inline* within other text, rather than as a separate block, you can use the + :rst:role:`code` role instead. + + .. versionchanged:: 2.0 + The ``language`` argument becomes optional. + + .. rubric:: options + + .. rst:directive:option:: linenos + :type: no value + + Enable to generate line numbers for the code block:: + + .. code-block:: ruby + :linenos: + + Some more Ruby code. + + .. rst:directive:option:: lineno-start: number + :type: number + + Set the first line number of the code block. If present, ``linenos`` + option is also automatically activated:: + + .. code-block:: ruby + :lineno-start: 10 + + Some more Ruby code, with line numbering starting at 10. + + .. versionadded:: 1.3 + + .. rst:directive:option:: emphasize-lines: line numbers + :type: comma separated numbers + + Emphasize particular lines of the code block:: + + .. code-block:: python + :emphasize-lines: 3,5 + + def some_function(): + interesting = False + print 'This line is highlighted.' + print 'This one is not...' + print '...but this one is.' + + .. versionadded:: 1.1 + .. versionchanged:: 1.6.6 + LaTeX supports the ``emphasize-lines`` option. + + .. rst:directive:option: force + :type: no value + + Ignore minor errors on highlighting + + .. versionchanged:: 2.1 + + .. rst:directive:option:: caption: caption of code block + :type: text + + Set a caption to the code block. + + .. versionadded:: 1.3 + + .. rst:directive:option:: name: a label for hyperlink + :type: text + + Define implicit target name that can be referenced by using + :rst:role:`ref`. For example:: + + .. code-block:: python + :caption: this.py + :name: this-py + + print 'Explicit is better than implicit.' + + In order to cross-reference a code-block using either the + :rst:role:`ref` or the :rst:role:`numref` role, it is necessary + that both :strong:`name` and :strong:`caption` be defined. The + argument of :strong:`name` can then be given to :rst:role:`numref` + to generate the cross-reference. Example:: + + See :numref:`this-py` for an example. + + When using :rst:role:`ref`, it is possible to generate a cross-reference + with only :strong:`name` defined, provided an explicit title is + given. Example:: + + See :ref:`this code snippet <this-py>` for an example. + + .. versionadded:: 1.3 + + .. rst:directive:option:: class: class names + :type: a list of class names separated by spaces + + The class name of the graph. + + .. versionadded:: 1.4 + + .. rst:directive:option:: dedent: number + :type: number or no value + + Strip indentation characters from the code block. When number given, + leading N characters are removed. When no argument given, leading spaces + are removed via :func:`textwrap.dedent()`. For example:: + + .. code-block:: ruby + :linenos: + :dedent: 4 + + some ruby code + + .. versionadded:: 1.3 + .. versionchanged:: 3.5 + Support automatic dedent. + + .. rst:directive:option:: force + :type: no value + + If given, minor errors on highlighting are ignored. + + .. versionadded:: 2.1 + +.. rst:directive:: .. literalinclude:: filename + + Longer displays of verbatim text may be included by storing the example text + in an external file containing only plain text. The file may be included + using the ``literalinclude`` directive. [#]_ For example, to include the + Python source file :file:`example.py`, use:: + + .. literalinclude:: example.py + + The file name is usually relative to the current file's path. However, if + it is absolute (starting with ``/``), it is relative to the top source + directory. + + **Additional options** + + Like :rst:dir:`code-block`, the directive supports the ``linenos`` flag + option to switch on line numbers, the ``lineno-start`` option to select the + first line number, the ``emphasize-lines`` option to emphasize particular + lines, the ``name`` option to provide an implicit target name, the + ``dedent`` option to strip indentation characters for the code block, and a + ``language`` option to select a language different from the current file's + standard language. In addition, it supports the ``caption`` option; however, + this can be provided with no argument to use the filename as the caption. + Example with options:: + + .. literalinclude:: example.rb + :language: ruby + :emphasize-lines: 12,15-18 + :linenos: + + Tabs in the input are expanded if you give a ``tab-width`` option with the + desired tab width. + + Include files are assumed to be encoded in the :confval:`source_encoding`. + If the file has a different encoding, you can specify it with the + ``encoding`` option:: + + .. literalinclude:: example.py + :encoding: latin-1 + + The directive also supports including only parts of the file. If it is a + Python module, you can select a class, function or method to include using + the ``pyobject`` option:: + + .. literalinclude:: example.py + :pyobject: Timer.start + + This would only include the code lines belonging to the ``start()`` method + in the ``Timer`` class within the file. + + Alternately, you can specify exactly which lines to include by giving a + ``lines`` option:: + + .. literalinclude:: example.py + :lines: 1,3,5-10,20- + + This includes the lines 1, 3, 5 to 10 and lines 20 to the last line. + + Another way to control which part of the file is included is to use the + ``start-after`` and ``end-before`` options (or only one of them). If + ``start-after`` is given as a string option, only lines that follow the + first line containing that string are included. If ``end-before`` is given + as a string option, only lines that precede the first lines containing that + string are included. The ``start-at`` and ``end-at`` options behave in a + similar way, but the lines containing the matched string are included. + + ``start-after``/``start-at`` and ``end-before``/``end-at`` can have same string. + ``start-after``/``start-at`` filter lines before the line that contains + option string (``start-at`` will keep the line). Then ``end-before``/``end-at`` + filter lines after the line that contains option string (``end-at`` will keep + the line and ``end-before`` skip the first line). + + .. note:: + + If you want to select only ``[second-section]`` of ini file like the + following, you can use ``:start-at: [second-section]`` and + ``:end-before: [third-section]``: + + .. code-block:: ini + + [first-section] + + var_in_first=true + + [second-section] + + var_in_second=true + + [third-section] + + var_in_third=true + + Useful cases of these option is working with tag comments. + ``:start-after: [initialize]`` and ``:end-before: [initialized]`` options + keep lines between comments: + + .. code-block:: py + + if __name__ == "__main__": + # [initialize] + app.start(":8000") + # [initialized] + + + When lines have been selected in any of the ways described above, the line + numbers in ``emphasize-lines`` refer to those selected lines, counted + consecutively starting at ``1``. + + When specifying particular parts of a file to display, it can be useful to + display the original line numbers. This can be done using the + ``lineno-match`` option, which is however allowed only when the selection + consists of contiguous lines. + + You can prepend and/or append a line to the included code, using the + ``prepend`` and ``append`` option, respectively. This is useful e.g. for + highlighting PHP code that doesn't include the ``<?php``/``?>`` markers. + + If you want to show the diff of the code, you can specify the old file by + giving a ``diff`` option:: + + .. literalinclude:: example.py + :diff: example.py.orig + + This shows the diff between ``example.py`` and ``example.py.orig`` with + unified diff format. + + A ``force`` option can ignore minor errors on highlighting. + + .. versionchanged:: 0.4.3 + Added the ``encoding`` option. + + .. versionchanged:: 0.6 + Added the ``pyobject``, ``lines``, ``start-after`` and ``end-before`` + options, as well as support for absolute filenames. + + .. versionchanged:: 1.0 + Added the ``prepend``, ``append``, and ``tab-width`` options. + + .. versionchanged:: 1.3 + Added the ``diff``, ``lineno-match``, ``caption``, ``name``, and + ``dedent`` options. + + .. versionchanged:: 1.4 + Added the ``class`` option. + + .. versionchanged:: 1.5 + Added the ``start-at``, and ``end-at`` options. + + .. versionchanged:: 1.6 + With both ``start-after`` and ``lines`` in use, the first line as per + ``start-after`` is considered to be with line number ``1`` for ``lines``. + + .. versionchanged:: 2.1 + Added the ``force`` option. + + .. versionchanged:: 3.5 + Support automatic dedent. + +.. _glossary-directive: + +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 + :rst:role:`term` role. Example:: + + .. glossary:: + + environment + A structure where information about all documents under the root is + saved, and used for cross-referencing. The environment is pickled + after the parsing stage, so that successive runs only need to read + and parse new and changed documents. + + source directory + The directory which, including its subdirectories, contains all + source files for one Sphinx project. + + In contrast to regular definition lists, *multiple* terms per entry are + allowed, and inline markup is allowed in terms. You can link to all of the + terms. For example:: + + .. glossary:: + + term 1 + term 2 + Definition of both terms. + + (When the glossary is sorted, the first term determines the sort order.) + + If you want to specify "grouping key" for general index entries, you can put + a "key" as "term : key". For example:: + + .. glossary:: + + term 1 : A + term 2 : B + Definition of both terms. + + Note that "key" is used for grouping key as is. + The "key" isn't normalized; key "A" and "a" become different groups. + The whole characters in "key" is used instead of a first character; it is + used for "Combining Character Sequence" and "Surrogate Pairs" grouping key. + + In i18n situation, you can specify "localized term : key" even if original + text only have "term" part. In this case, translated "localized term" will be + categorized in "key" group. + + .. versionadded:: 0.6 + You can now give the glossary directive a ``:sorted:`` flag that will + automatically sort the entries alphabetically. + + .. versionchanged:: 1.1 + Now supports multiple terms and inline markup in terms. + + .. versionchanged:: 1.4 + Index key for glossary term should be considered *experimental*. + + .. versionchanged:: 4.4 + In internationalized documentation, the ``:sorted:`` flag sorts + according to translated terms. + +Meta-information markup +----------------------- + +.. rst:directive:: .. sectionauthor:: name <email> + + Identifies the author of the current section. The argument should include + the author's name such that it can be used for presentation and email + address. The domain name portion of the address should be lower case. + Example:: + + .. sectionauthor:: Guido van Rossum <guido@python.org> + + By default, this markup isn't reflected in the output in any way (it helps + keep track of contributions), but you can set the configuration value + :confval:`show_authors` to ``True`` to make them produce a paragraph in the + output. + + +.. rst:directive:: .. codeauthor:: name <email> + + The :rst:dir:`codeauthor` directive, which can appear multiple times, names + the authors of the described code, just like :rst:dir:`sectionauthor` names + the author(s) of a piece of documentation. It too only produces output if + the :confval:`show_authors` configuration value is ``True``. + + +Index-generating markup +----------------------- + +Sphinx automatically creates index entries from all object descriptions (like +functions, classes or attributes) like discussed in +:doc:`/usage/restructuredtext/domains`. + +However, there is also explicit markup available, to make the index more +comprehensive and enable index entries in documents where information is not +mainly contained in information units, such as the language reference. + +.. rst:directive:: .. index:: <entries> + + This directive contains one or more index entries. Each entry consists of a + type and a value, separated by a colon. + + For example:: + + .. index:: + single: execution; context + pair: module; __main__ + pair: module; sys + triple: module; search; path + seealso: scope + + The execution context + --------------------- + + ... + + This directive contains five entries, which will be converted to entries in + the generated index which link to the exact location of the index statement + (or, in case of offline media, the corresponding page number). + + Since index directives generate cross-reference targets at their location in + the source, it makes sense to put them *before* the thing they refer to -- + e.g. a heading, as in the example above. + + The possible entry types are: + + single + Creates a single index entry. + Can be made a sub-entry by separating the sub-entry text with a semicolon + (this notation is also used below to describe what entries are created). + Examples: + + .. code:: reStructuredText + + .. index:: single: execution + single: execution; context + + - ``single: execution`` creates an index entry labelled ``execution``. + - ``single: execution; context`` creates an sub-entry of ``execution`` + labelled ``context``. + pair + A shortcut to create two index entries. + The pair of values must be separated by a semicolon. + Example: + + .. code:: reStructuredText + + .. index:: pair: loop; statement + + This would create two index entries; ``loop; statement`` and ``statement; loop``. + triple + A shortcut to create three index entries. + All three values must be separated by a semicolon. + Example: + + .. code:: reStructuredText + + .. index:: triple: module; search; path + + This would create three index entries; ``module; search path``, + ``search; path, module``, and ``path; module search``. + see + A shortcut to create an index entry that refers to another entry. + Example: + + .. code:: reStructuredText + + .. index:: see: entry; other + + This would create an index entry referring from ``entry`` to ``other`` + (i.e. 'entry': See 'other'). + seealso + Like ``see``, but inserts 'see also' instead of 'see'. + module, keyword, operator, object, exception, statement, builtin + These **deprecated** shortcuts all create two index entries. + For example, ``module: hashlib`` creates the entries ``module; hashlib`` + and ``hashlib; module``. + + .. deprecated:: 1.0 + These Python-specific entry types are deprecated. + + .. versionchanged:: 7.1 + Removal version set to Sphinx 9.0. + Using these entry types will now emit warnings with the ``index`` category. + + You can mark up "main" index entries by prefixing them with an exclamation + mark. The references to "main" entries are emphasized in the generated + index. For example, if two pages contain :: + + .. index:: Python + + and one page contains :: + + .. index:: ! Python + + then the backlink to the latter page is emphasized among the three backlinks. + + For index directives containing only "single" entries, there is a shorthand + notation:: + + .. index:: BNF, grammar, syntax, notation + + This creates four index entries. + + .. versionchanged:: 1.1 + Added ``see`` and ``seealso`` types, as well as marking main entries. + + .. rubric:: options + + .. rst:directive:option:: name: a label for hyperlink + :type: text + + Define implicit target name that can be referenced by using + :rst:role:`ref`. For example:: + + .. index:: Python + :name: py-index + + .. versionadded:: 3.0 + +.. rst:role:: index + + While the :rst:dir:`index` directive is a block-level markup and links to the + beginning of the next paragraph, there is also a corresponding role that sets + the link target directly where it is used. + + The content of the role can be a simple phrase, which is then kept in the + text and used as an index entry. It can also be a combination of text and + index entry, styled like with explicit targets of cross-references. In that + case, the "target" part can be a full entry as described for the directive + above. For example:: + + This is a normal reST :index:`paragraph` that contains several + :index:`index entries <pair: index; entry>`. + + .. versionadded:: 1.1 + + +.. _tags: + +Including content based on tags +------------------------------- + +.. rst:directive:: .. only:: <expression> + + Include the content of the directive only if the *expression* is true. The + expression should consist of tags, like this:: + + .. only:: html and draft + + Undefined tags are false, defined tags (via the ``-t`` command-line option or + within :file:`conf.py`, see :ref:`here <conf-tags>`) are true. Boolean + expressions, also using parentheses (like ``html and (latex or draft)``) are + supported. + + The *format* and the *name* of the current builder (``html``, ``latex`` or + ``text``) are always set as a tag [#]_. To make the distinction between + format and name explicit, they are also added with the prefix ``format_`` and + ``builder_``, e.g. the epub builder defines the tags ``html``, ``epub``, + ``format_html`` and ``builder_epub``. + + These standard tags are set *after* the configuration file is read, so they + are not available there. + + All tags must follow the standard Python identifier syntax as set out in + the `Identifiers and keywords + <https://docs.python.org/3/reference/lexical_analysis.html#identifiers>`_ + documentation. That is, a tag expression may only consist of tags that + conform to the syntax of Python variables. In ASCII, this consists of the + uppercase and lowercase letters ``A`` through ``Z``, the underscore ``_`` + and, except for the first character, the digits ``0`` through ``9``. + + .. versionadded:: 0.6 + .. versionchanged:: 1.2 + Added the name of the builder and the prefixes. + + .. warning:: + + This directive is designed to control only content of document. It could + not control sections, labels and so on. + +.. _table-directives: + +Tables +------ + +Use :ref:`reStructuredText tables <rst-tables>`, i.e. either + +- grid table syntax (:duref:`ref <grid-tables>`), +- simple table syntax (:duref:`ref <simple-tables>`), +- :dudir:`csv-table` syntax, +- or :dudir:`list-table` syntax. + +The :dudir:`table` directive serves as optional wrapper of the *grid* and +*simple* syntaxes. + +They work fine in HTML output, but rendering tables to LaTeX is complex. +Check the :confval:`latex_table_style`. + +.. versionchanged:: 1.6 + Merged cells (multi-row, multi-column, both) from grid tables containing + complex contents such as multiple paragraphs, blockquotes, lists, literal + blocks, will render correctly to LaTeX output. + +.. rst:directive:: .. tabularcolumns:: column spec + + This directive influences only the LaTeX output for the next table in + source. The mandatory argument is a column specification (known as an + "alignment preamble" in LaTeX idiom). Please refer to a LaTeX + documentation, such as the `wiki page`_, for basics of such a column + specification. + + .. _wiki page: https://en.wikibooks.org/wiki/LaTeX/Tables + + .. versionadded:: 0.3 + + .. note:: + + :rst:dir:`tabularcolumns` conflicts with ``:widths:`` option of table + directives. If both are specified, ``:widths:`` option will be ignored. + + Sphinx will render tables with more than 30 rows with ``longtable``. + Besides the ``l``, ``r``, ``c`` and ``p{width}`` column specifiers, one can + also use ``\X{a}{b}`` (new in version 1.5) which configures the column + width to be a fraction ``a/b`` of the total line width and ``\Y{f}`` (new + in version 1.6) where ``f`` is a decimal: for example ``\Y{0.2}`` means that + the column will occupy ``0.2`` times the line width. + + When this directive is used for a table with at most 30 rows, Sphinx will + render it with ``tabulary``. One can then use specific column types ``L`` + (left), ``R`` (right), ``C`` (centered) and ``J`` (justified). They have + the effect of a ``p{width}`` (i.e. each cell is a LaTeX ``\parbox``) with + the specified internal text alignment and an automatically computed + ``width``. + + .. warning:: + + - Cells that contain list-like elements such as object descriptions, + blockquotes or any kind of lists are not compatible with the ``LRCJ`` + column types. The column type must then be some ``p{width}`` with an + explicit ``width`` (or ``\X{a}{b}`` or ``\Y{f}``). + + - Literal blocks do not work with ``tabulary`` at all. Sphinx will + fall back to ``tabular`` or ``longtable`` environments and generate a + suitable column specification. + +In absence of the :rst:dir:`tabularcolumns` directive, and for a table with at +most 30 rows and no problematic cells as described in the above warning, +Sphinx uses ``tabulary`` and the ``J`` column-type for every column. + +.. versionchanged:: 1.6 + + Formerly, the ``L`` column-type was used (text is flushed-left). To revert + to this, include ``\newcolumntype{T}{L}`` in the LaTeX preamble, as in fact + Sphinx uses ``T`` and sets it by default to be an alias of ``J``. + +.. hint:: + + A frequent issue with ``tabulary`` is that columns with little contents + appear to be "squeezed". One can add to the LaTeX preamble for example + ``\setlength{\tymin}{40pt}`` to ensure a minimal column width of ``40pt``, + the ``tabulary`` default of ``10pt`` being too small. + +.. hint:: + + To force usage of the LaTeX ``longtable`` environment pass ``longtable`` as + a ``:class:`` option to :dudir:`table`, :dudir:`csv-table`, or + :dudir:`list-table`. Use :ref:`rst-class <rstclass>` for other tables. + +Math +---- + +The input language for mathematics is LaTeX markup. This is the de-facto +standard for plain-text math notation and has the added advantage that no +further translation is necessary when building LaTeX output. + +Keep in mind that when you put math markup in **Python docstrings** read by +:mod:`autodoc <sphinx.ext.autodoc>`, you either have to double all backslashes, +or use Python raw strings (``r"raw"``). + +.. rst:directive:: math + + Directive for displayed math (math that takes the whole line for itself). + + The directive supports multiple equations, which should be separated by a + blank line:: + + .. math:: + + (a + b)^2 = a^2 + 2ab + b^2 + + (a - b)^2 = a^2 - 2ab + b^2 + + In addition, each single equation is set within a ``split`` environment, + which means that you can have multiple aligned lines in an equation, + aligned at ``&`` and separated by ``\\``:: + + .. math:: + + (a + b)^2 &= (a + b)(a + b) \\ + &= a^2 + 2ab + b^2 + + For more details, look into the documentation of the `AmSMath LaTeX + package`_. + + When the math is only one line of text, it can also be given as a directive + argument:: + + .. math:: (a + b)^2 = a^2 + 2ab + b^2 + + Normally, equations are not numbered. If you want your equation to get a + number, use the ``label`` option. When given, it selects an internal label + for the equation, by which it can be cross-referenced, and causes an equation + number to be issued. See :rst:role:`eq` for an example. The numbering + style depends on the output format. + + There is also an option ``nowrap`` that prevents any wrapping of the given + math in a math environment. When you give this option, you must make sure + yourself that the math is properly set up. For example:: + + .. math:: + :nowrap: + + \begin{eqnarray} + y & = & ax^2 + bx + c \\ + f(x) & = & x^2 + 2xy + y^2 + \end{eqnarray} + +.. _AmSMath LaTeX package: https://www.ams.org/publications/authors/tex/amslatex + +.. seealso:: + + :ref:`math-support` + Rendering options for math with HTML builders. + + :confval:`latex_engine` + Explains how to configure LaTeX builder to support Unicode literals in + math mark-up. + + +Grammar production displays +--------------------------- + +Special markup is available for displaying the productions of a formal grammar. +The markup is simple and does not attempt to model all aspects of BNF (or any +derived forms), but provides enough to allow context-free grammars to be +displayed in a way that causes uses of a symbol to be rendered as hyperlinks to +the definition of the symbol. There is this directive: + +.. rst:directive:: .. productionlist:: [productionGroup] + + This directive is used to enclose a group of productions. Each production + is given on a single line and consists of a name, separated by a colon from + the following definition. If the definition spans multiple lines, each + continuation line must begin with a colon placed at the same column as in + the first line. + Blank lines are not allowed within ``productionlist`` directive arguments. + + The definition can contain token names which are marked as interpreted text + (e.g., "``sum ::= `integer` "+" `integer```") -- this generates + cross-references to the productions of these tokens. Outside of the + production list, you can reference to token productions using + :rst:role:`token`. + + The *productionGroup* argument to :rst:dir:`productionlist` serves to + distinguish different sets of production lists that belong to different + grammars. Multiple production lists with the same *productionGroup* thus + define rules in the same scope. + + Inside of the production list, tokens implicitly refer to productions + from the current group. You can refer to the production of another + grammar by prefixing the token with its group name and a colon, e.g, + "``otherGroup:sum``". If the group of the token should not be shown in + the production, it can be prefixed by a tilde, e.g., + "``~otherGroup:sum``". To refer to a production from an unnamed + grammar, the token should be prefixed by a colon, e.g., "``:sum``". + + Outside of the production list, + if you have given a *productionGroup* argument you must prefix the + token name in the cross-reference with the group name and a colon, + e.g., "``myGroup:sum``" instead of just "``sum``". + If the group should not be shown in the title of the link either + an explicit title can be given (e.g., "``myTitle <myGroup:sum>``"), + or the target can be prefixed with a tilde (e.g., "``~myGroup:sum``"). + + Note that no further reST parsing is done in the production, so that you + don't have to escape ``*`` or ``|`` characters. + +The following is an example taken from the Python Reference Manual:: + + .. productionlist:: + try_stmt: try1_stmt | try2_stmt + try1_stmt: "try" ":" `suite` + : ("except" [`expression` ["," `target`]] ":" `suite`)+ + : ["else" ":" `suite`] + : ["finally" ":" `suite`] + try2_stmt: "try" ":" `suite` + : "finally" ":" `suite` + + +.. rubric:: Footnotes + +.. [#] The LaTeX writer only refers the ``maxdepth`` option of first toctree + directive in the document. + +.. [#] 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. + +.. [#] There is a standard ``.. include`` directive, but it raises errors if the + file is not found. This one only emits a warning. + +.. [#] For most builders name and format are the same. At the moment only + builders derived from the html builder distinguish between the builder + format and the builder name. + + Note that the current builder tag is not available in ``conf.py``, it is + only available after the builder is initialized. diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst new file mode 100644 index 0000000..729e651 --- /dev/null +++ b/doc/usage/restructuredtext/domains.rst @@ -0,0 +1,2303 @@ +.. highlight:: rst + +======= +Domains +======= + +.. versionadded:: 1.0 + +Originally, Sphinx was conceived for a single project, the documentation of the +Python language. Shortly afterwards, it was made available for everyone as a +documentation tool, but the documentation of Python modules remained deeply +built in -- the most fundamental directives, like ``function``, were designed +for Python objects. Since Sphinx has become somewhat popular, interest +developed in using it for many different purposes: C/C++ projects, JavaScript, +or even reStructuredText markup (like in this documentation). + +While this was always possible, it is now much easier to easily support +documentation of projects using different programming languages or even ones +not supported by the main Sphinx distribution, by providing a **domain** for +every such purpose. + +A domain is a collection of markup (reStructuredText :term:`directive`\ s and +:term:`role`\ s) to describe and link to :term:`object`\ s belonging together, +e.g. elements of a programming language. Directive and role names in a domain +have names like ``domain:name``, e.g. ``py:function``. Domains can also +provide custom indices (like the Python Module Index). + +Having domains means that there are no naming problems when one set of +documentation wants to refer to e.g. C++ and Python classes. It also means +that extensions that support the documentation of whole new languages are much +easier to write. + +This section describes what the domains that are included with Sphinx provide. +The domain API is documented as well, in the section :ref:`domain-api`. + + +.. _basic-domain-markup: + +Basic Markup +------------ + +Most domains provide a number of :dfn:`object description directives`, used to +describe specific objects provided by modules. Each directive requires one or +more signatures to provide basic information about what is being described, and +the content should be the description. + +A domain will typically keep an internal index of all entities to aid +cross-referencing. +Typically it will also add entries in the shown general index. +If you want to suppress the addition of an entry in the shown index, you can +give the directive option flag ``:no-index-entry:``. +If you want to exclude the object description from the table of contents, you +can give the directive option flag ``:no-contents-entry:``. +If you want to typeset an object description, without even making it available +for cross-referencing, you can give the directive option flag ``:no-index:`` +(which implies ``:no-index-entry:``). +If you do not want to typeset anything, you can give the directive option flag +``:no-typesetting:``. This can for example be used to create only a target and +index entry for later reference. +Though, note that not every directive in every domain may support these +options. + +.. versionadded:: 3.2 + The directive option ``noindexentry`` in the Python, C, C++, and Javascript + domains. + +.. versionadded:: 5.2.3 + The directive option ``:nocontentsentry:`` in the Python, C, C++, Javascript, + and reStructuredText domains. + +.. versionadded:: 7.2 + The directive option ``no-typesetting`` in the Python, C, C++, Javascript, + and reStructuredText domains. + +.. versionchanged:: 7.2 + + * The directive option ``:noindex:`` was renamed + to ``:no-index:``. + * The directive option ``:noindexentry:`` was renamed + to ``:no-index-entry:``. + * The directive option ``:nocontentsentry:`` was renamed + to ``:no-contents-entry:``. + + The previous names are retained as aliases, + but will be deprecated and removed + in a future version of Sphinx. + +An example using a Python domain directive:: + + .. py:function:: spam(eggs) + ham(eggs) + + Spam or ham the foo. + +This describes the two Python functions ``spam`` and ``ham``. (Note that when +signatures become too long, you can break them if you add a backslash to lines +that are continued in the next line. Example:: + + .. py:function:: filterwarnings(action, message='', category=Warning, \ + module='', lineno=0, append=False) + :no-index: + +(This example also shows how to use the ``:no-index:`` flag.) + +The domains also provide roles that link back to these object descriptions. +For example, to link to one of the functions described in the example above, +you could say :: + + The function :py:func:`spam` does a similar thing. + +As you can see, both directive and role names contain the domain name and the +directive name. + +The directive option ``:no-typesetting:`` can be used to create a target +(and index entry) which can later be referenced +by the roles provided by the domain. +This is particularly useful for literate programming: + +.. code-block:: rst + + .. py:function:: spam(eggs) + :no-typesetting: + + .. code:: + + def spam(eggs): + pass + + The function :py:func:`spam` does nothing. + +.. rubric:: Default Domain + +For documentation describing objects from solely one domain, authors will not +have to state again its name at each directive, role, etc... after +having specified a default. This can be done either via the config +value :confval:`primary_domain` or via this directive: + +.. rst:directive:: .. default-domain:: name + + Select a new default domain. While the :confval:`primary_domain` selects a + global default, this only has an effect within the same file. + +If no other default is selected, the Python domain (named ``py``) is the +default one, mostly for compatibility with documentation written for older +versions of Sphinx. + +Directives and roles that belong to the default domain can be mentioned without +giving the domain name, i.e. :: + + .. function:: pyfunc() + + Describes a Python function. + + Reference to :func:`pyfunc`. + +Cross-referencing syntax +~~~~~~~~~~~~~~~~~~~~~~~~ + +For cross-reference roles provided by domains, the same facilities exist as for +general cross-references. See :ref:`xref-syntax`. + +In short: + +* You may supply an explicit title and reference target: ``:role:`title + <target>``` will refer to *target*, but the link text will be *title*. + +* If you prefix the content with ``!``, no reference/hyperlink will be created. + +* If you prefix the content with ``~``, the link text will only be the last + component of the target. For example, ``:py:meth:`~Queue.Queue.get``` will + refer to ``Queue.Queue.get`` but only display ``get`` as the link text. + +.. _python-domain: + +The Python Domain +----------------- + +The Python domain (name **py**) provides the following directives for module +declarations: + +.. rst:directive:: .. py:module:: name + + This directive marks the beginning of the description of a module (or package + submodule, in which case the name should be fully qualified, including the + package name). A description of the module such as the docstring can be + placed in the body of the directive. + + This directive will also cause an entry in the global module index. + + .. versionchanged:: 5.2 + + Module directives support body content. + + .. rubric:: options + + .. rst:directive:option:: platform: platforms + :type: comma separated list + + Indicate platforms which the module is available (if it is available on + all platforms, the option should be omitted). The keys are short + identifiers; examples that are in use include "IRIX", "Mac", "Windows" + and "Unix". It is important to use a key which has already been used when + applicable. + + .. rst:directive:option:: synopsis: purpose + :type: text + + Consist of one sentence describing the module's purpose -- it is currently + only used in the Global Module Index. + + .. rst:directive:option:: deprecated + :type: no argument + + Mark a module as deprecated; it will be designated as such in various + locations then. + + + +.. rst:directive:: .. py:currentmodule:: name + + This directive tells Sphinx that the classes, functions etc. documented from + here are in the given module (like :rst:dir:`py:module`), but it will not + create index entries, an entry in the Global Module Index, or a link target + for :rst:role:`py:mod`. This is helpful in situations where documentation + for things in a module is spread over multiple files or sections -- one + location has the :rst:dir:`py:module` directive, the others only + :rst:dir:`py:currentmodule`. + +The following directives are provided for module and class contents: + +.. rst:directive:: .. py:function:: name(parameters) + .. py:function:: name[type parameters](parameters) + + Describes a module-level function. + The signature should include the parameters, + together with optional type parameters, + as given in the Python function definition, see :ref:`signatures`. + For example:: + + .. py:function:: Timer.repeat(repeat=3, number=1_000_000) + .. py:function:: add[T](a: T, b: T) -> T + + For methods you should use :rst:dir:`py:method`. + + The description normally includes information about the parameters required + and how they are used (especially whether mutable objects passed as + parameters are modified), side effects, and possible exceptions. + + This information can (in any ``py`` directive) optionally be given in a + structured form, see :ref:`info-field-lists`. + + .. rubric:: options + + .. rst:directive:option:: async + :type: no value + + Indicate the function is an async function. + + .. versionadded:: 2.1 + + .. rst:directive:option:: canonical + :type: full qualified name including module name + + Describe the location where the object is defined if the object is + imported from other modules + + .. versionadded:: 4.0 + + .. rst::directive:option:: module + :type: text + + Describe the location where the object is defined. The default value is + the module specified by :rst:dir:`py:currentmodule`. + + .. rst:directive:option:: single-line-parameter-list + :type: no value + + Ensures that the function's arguments will be emitted on a single logical + line, overriding :confval:`python_maximum_signature_line_length` and + :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + + .. rst:directive:option:: single-line-type-parameter-list + :type: no value + + Ensure that the function's type parameters are emitted on a single + logical line, overriding :confval:`python_maximum_signature_line_length` + and :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + + +.. 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. + + .. rubric:: options + + .. rst:directive:option:: type: type of the variable + :type: text + + .. versionadded:: 2.4 + + .. rst:directive:option:: value: initial value of the variable + :type: text + + .. versionadded:: 2.4 + + .. rst:directive:option:: canonical + :type: full qualified name including module name + + Describe the location where the object is defined if the object is + imported from other modules + + .. versionadded:: 4.0 + + .. rst::directive:option:: module + :type: text + + Describe the location where the object is defined. The default value is + the module specified by :rst:dir:`py:currentmodule`. + +.. rst:directive:: .. py:exception:: name + .. py:exception:: name(parameters) + .. py:exception:: name[type parmeters](parameters) + + Describes an exception class. + The signature can, but need not include parentheses with constructor arguments, + or may optionally include type parameters (see :pep:`695`). + + .. rubric:: options + + .. rst:directive:option:: final + :type: no value + + Indicate the class is a final class. + + .. versionadded:: 3.1 + + .. rst::directive:option:: module + :type: text + + Describe the location where the object is defined. The default value is + the module specified by :rst:dir:`py:currentmodule`. + + .. rst:directive:option:: single-line-parameter-list + :type: no value + + See :rst:dir:`py:class:single-line-parameter-list`. + + .. versionadded:: 7.1 + + .. rst:directive:option:: single-line-type-parameter-list + :type: no value + + See :rst:dir:`py:class:single-line-type-parameter-list`. + + .. versionadded:: 7.1 + +.. rst:directive:: .. py:class:: name + .. py:class:: name(parameters) + .. py:class:: name[type parmeters](parameters) + + Describes a class. + The signature can optionally include type parameters (see :pep:`695`) + or parentheses with parameters which will be shown as the constructor arguments. + See also :ref:`signatures`. + + Methods and attributes belonging to the class should be placed in this + directive's body. If they are placed outside, the supplied name should + contain the class name so that cross-references still work. Example:: + + .. py:class:: Foo + + .. py:method:: quux() + + -- or -- + + .. py:class:: Bar + + .. py:method:: Bar.quux() + + The first way is the preferred one. + + .. rubric:: options + + .. rst:directive:option:: canonical + :type: full qualified name including module name + + Describe the location where the object is defined if the object is + imported from other modules + + .. versionadded:: 4.0 + + .. rst:directive:option:: final + :type: no value + + Indicate the class is a final class. + + .. versionadded:: 3.1 + + .. rst::directive:option:: module + :type: text + + Describe the location where the object is defined. The default value is + the module specified by :rst:dir:`py:currentmodule`. + + .. rst:directive:option:: single-line-parameter-list + :type: no value + + Ensures that the class constructor's arguments will be emitted on a single + logical line, overriding :confval:`python_maximum_signature_line_length` + and :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + + .. rst:directive:option:: single-line-type-parameter-list + :type: no value + + Ensure that the class type parameters are emitted on a single logical + line, overriding :confval:`python_maximum_signature_line_length` and + :confval:`maximum_signature_line_length`. + +.. rst:directive:: .. py:attribute:: name + + Describes an object data attribute. The description should include + information about the type of the data to be expected and whether it may be + changed directly. + + .. rubric:: options + + .. rst:directive:option:: type: type of the attribute + :type: text + + .. versionadded:: 2.4 + + .. rst:directive:option:: value: initial value of the attribute + :type: text + + .. versionadded:: 2.4 + + .. rst:directive:option:: canonical + :type: full qualified name including module name + + Describe the location where the object is defined if the object is + imported from other modules + + .. versionadded:: 4.0 + + .. rst::directive:option:: module + :type: text + + Describe the location where the object is defined. The default value is + the module specified by :rst:dir:`py:currentmodule`. + +.. rst:directive:: .. py:property:: name + + Describes an object property. + + .. versionadded:: 4.0 + + .. rubric:: options + + .. rst:directive:option:: abstractmethod + :type: no value + + Indicate the property is abstract. + + .. rst:directive:option:: classmethod + :type: no value + + Indicate the property is a classmethod. + + .. versionaddedd: 4.2 + + .. rst:directive:option:: type: type of the property + :type: text + + .. rst::directive:option:: module + :type: text + + Describe the location where the object is defined. The default value is + the module specified by :rst:dir:`py:currentmodule`. + +.. rst:directive:: .. py:method:: name(parameters) + .. py:method:: name[type parameters](parameters) + + Describes an object method. The parameters should not include the ``self`` + parameter. The description should include similar information to that + described for ``function``. See also :ref:`signatures` and + :ref:`info-field-lists`. + + .. rubric:: options + + .. rst:directive:option:: abstractmethod + :type: no value + + Indicate the method is an abstract method. + + .. versionadded:: 2.1 + + .. rst:directive:option:: async + :type: no value + + Indicate the method is an async method. + + .. versionadded:: 2.1 + + .. rst:directive:option:: canonical + :type: full qualified name including module name + + Describe the location where the object is defined if the object is + imported from other modules + + .. versionadded:: 4.0 + + .. rst:directive:option:: classmethod + :type: no value + + Indicate the method is a class method. + + .. versionadded:: 2.1 + + .. rst:directive:option:: final + :type: no value + + Indicate the class is a final method. + + .. versionadded:: 3.1 + + .. rst::directive:option:: module + :type: text + + Describe the location where the object is defined. The default value is + the module specified by :rst:dir:`py:currentmodule`. + + .. rst:directive:option:: single-line-parameter-list + :type: no value + + Ensures that the method's arguments will be emitted on a single logical + line, overriding :confval:`python_maximum_signature_line_length` and + :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + + .. rst:directive:option:: single-line-type-parameter-list + :type: no value + + Ensure that the method's type parameters are emitted on a single logical + line, overriding :confval:`python_maximum_signature_line_length` and + :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.2 + + .. rst:directive:option:: staticmethod + :type: no value + + Indicate the method is a static method. + + .. versionadded:: 2.1 + + +.. rst:directive:: .. py:staticmethod:: name(parameters) + .. py:staticmethod:: name[type parameters](parameters) + + Like :rst:dir:`py:method`, but indicates that the method is a static method. + + .. versionadded:: 0.4 + +.. rst:directive:: .. py:classmethod:: name(parameters) + .. py:classmethod:: name[type parameters](parameters) + + Like :rst:dir:`py:method`, but indicates that the method is a class method. + + .. versionadded:: 0.6 + +.. rst:directive:: .. py:decorator:: name + .. py:decorator:: name(parameters) + .. py:decorator:: name[type parameters](parameters) + + Describes a decorator function. The signature should represent the usage as + a decorator. For example, given the functions + + .. code-block:: python + + def removename(func): + func.__name__ = '' + return func + + def setnewname(name): + def decorator(func): + func.__name__ = name + return func + return decorator + + the descriptions should look like this:: + + .. py:decorator:: removename + + Remove name of the decorated function. + + .. py:decorator:: setnewname(name) + + Set name of the decorated function to *name*. + + (as opposed to ``.. py:decorator:: removename(func)``.) + + There is no ``py:deco`` role to link to a decorator that is marked up with + this directive; rather, use the :rst:role:`py:func` role. + + .. rst:directive:option:: single-line-parameter-list + :type: no value + + Ensures that the decorator's arguments will be emitted on a single logical + line, overriding :confval:`python_maximum_signature_line_length` and + :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + + .. rst:directive:option:: single-line-type-parameter-list + :type: no value + + Ensure that the decorator's type parameters are emitted on a single + logical line, overriding :confval:`python_maximum_signature_line_length` + and :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.2 + +.. rst:directive:: .. py:decoratormethod:: name + .. py:decoratormethod:: name(signature) + .. py:decoratormethod:: name[type parameters](signature) + + Same as :rst:dir:`py:decorator`, but for decorators that are methods. + + Refer to a decorator method using the :rst:role:`py:meth` role. + +.. _signatures: + +Python Signatures +~~~~~~~~~~~~~~~~~ + +Signatures of functions, methods and class constructors can be given like they +would be written in Python. + +Default values for optional arguments can be given (but if they contain commas, +they will confuse the signature parser). Python 3-style argument annotations +can also be given as well as return type annotations:: + + .. py:function:: compile(source : string, filename, symbol='file') -> ast object + +For functions with optional parameters that don't have default values +(typically functions implemented in C extension modules without keyword +argument support), you can use brackets to specify the optional parts: + +.. py:function:: compile(source[, filename[, symbol]]) + :no-index: + +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 + + class AnimalList[AnimalT](list[AnimalT]): + ... + + def add[T](a: T, b: T) -> T: + return a + b + +The corresponding reStructuredText documentation would be: + +.. code:: rst + + .. py:class:: AnimalList[AnimalT] + + .. py:function:: add[T](a: T, b: T) -> T + +See :pep:`695` and :pep:`696` for details and the full specification. + +.. _info-field-lists: + +Info field lists +~~~~~~~~~~~~~~~~ + +.. versionadded:: 0.4 +.. versionchanged:: 3.0 + + meta fields are added. + +Inside Python object description directives, reST field lists with these fields +are recognized and formatted nicely: + +* ``param``, ``parameter``, ``arg``, ``argument``, ``key``, ``keyword``: + Description of a parameter. +* ``type``: Type of a parameter. Creates a link if possible. +* ``raises``, ``raise``, ``except``, ``exception``: That (and when) a specific + exception is raised. +* ``var``, ``ivar``, ``cvar``: Description of a variable. +* ``vartype``: Type of a variable. Creates a link if possible. +* ``returns``, ``return``: Description of the return value. +* ``rtype``: Return type. Creates a link if possible. +* ``meta``: Add metadata to description of the python object. The metadata will + not be shown on output document. For example, ``:meta private:`` indicates + the python object is private member. It is used in + :py:mod:`sphinx.ext.autodoc` for filtering members. + +.. note:: + + In current release, all ``var``, ``ivar`` and ``cvar`` are represented as + "Variable". There is no difference at all. + +The field names must consist of one of these keywords and an argument (except +for ``returns`` and ``rtype``, which do not need an argument). This is best +explained by an example:: + + .. py:function:: send_message(sender, recipient, message_body, [priority=1]) + + Send a message to a recipient + + :param str sender: The person sending the message + :param str recipient: The recipient of the message + :param str message_body: The body of the message + :param priority: The priority of the message, can be a number 1-5 + :type priority: integer or None + :return: the message id + :rtype: int + :raises ValueError: if the message_body exceeds 160 characters + :raises TypeError: if the message_body is not a basestring + +This will render like this: + +.. py:function:: send_message(sender, recipient, message_body, [priority=1]) + :no-index: + + Send a message to a recipient + + :param str sender: The person sending the message + :param str recipient: The recipient of the message + :param str message_body: The body of the message + :param priority: The priority of the message, can be a number 1-5 + :type priority: int or None + :return: the message id + :rtype: int + :raises ValueError: if the message_body exceeds 160 characters + :raises TypeError: if the message_body is not a basestring + +It is also possible to combine parameter type and description, if the type is a +single word, like this:: + + :param int priority: The priority of the message, can be a number 1-5 + +.. versionadded:: 1.5 + +Container types such as lists and dictionaries can be linked automatically +using the following syntax:: + + :type priorities: list(int) + :type priorities: list[int] + :type mapping: dict(str, int) + :type mapping: dict[str, int] + :type point: tuple(float, float) + :type point: tuple[float, float] + +Multiple types in a type field will be linked automatically if separated by the +word "or":: + + :type an_arg: int or None + :vartype a_var: str or int + :rtype: float or str + +.. _python-roles: + +Cross-referencing Python objects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following roles refer to objects in modules and are possibly hyperlinked if +a matching identifier is found: + +.. rst:role:: py:mod + + Reference a module; a dotted name may be used. This should also be used for + package names. + +.. rst:role:: py:func + + Reference a Python function; dotted names may be used. The role text needs + not include trailing parentheses to enhance readability; they will be added + automatically by Sphinx if the :confval:`add_function_parentheses` config + value is ``True`` (the default). + +.. rst:role:: py:data + + Reference a module-level variable. + +.. rst:role:: py:const + + Reference a "defined" constant. This may be a Python variable that is not + intended to be changed. + +.. rst:role:: py:class + + Reference a class; a dotted name may be used. + +.. rst:role:: py:meth + + Reference a method of an object. The role text can include the type name + and the method name; if it occurs within the description of a type, the type + name can be omitted. A dotted name may be used. + +.. rst:role:: py:attr + + Reference a data attribute of an object. + + .. note:: The role is also able to refer to property. + +.. rst:role:: py:exc + + Reference an exception. A dotted name may be used. + +.. rst:role:: py:obj + + Reference an object of unspecified type. Useful e.g. as the + :confval:`default_role`. + + .. versionadded:: 0.4 + +The name enclosed in this markup can include a module name and/or a class name. +For example, ``:py:func:`filter``` could refer to a function named ``filter`` +in the current module, or the built-in function of that name. In contrast, +``:py:func:`foo.filter``` clearly refers to the ``filter`` function in the +``foo`` module. + +Normally, names in these roles are searched first without any further +qualification, then with the current module name prepended, then with the +current module and class name (if any) prepended. If you prefix the name with +a dot, this order is reversed. For example, in the documentation of Python's +:mod:`codecs` module, ``:py:func:`open``` always refers to the built-in +function, while ``:py:func:`.open``` refers to :func:`codecs.open`. + +A similar heuristic is used to determine whether the name is an attribute of +the currently documented class. + +Also, if the name is prefixed with a dot, and no exact match is found, the +target is taken as a suffix and all object names with that suffix are searched. +For example, ``:py:meth:`.TarFile.close``` references the +``tarfile.TarFile.close()`` function, even if the current module is not +``tarfile``. Since this can get ambiguous, if there is more than one possible +match, you will get a warning from Sphinx. + +Note that you can combine the ``~`` and ``.`` prefixes: +``:py:meth:`~.TarFile.close``` will reference the ``tarfile.TarFile.close()`` +method, but the visible link caption will only be ``close()``. + + +.. _c-domain: + +The C Domain +------------ + +The C domain (name **c**) is suited for documentation of C API. + +.. rst:directive:: .. c:member:: declaration + .. c:var:: declaration + + Describes a C struct member or variable. Example signature:: + + .. c:member:: PyObject *PyTypeObject.tp_bases + + The difference between the two directives is only cosmetic. + +.. rst:directive:: .. c:function:: function prototype + + Describes a C function. The signature should be given as in C, e.g.:: + + .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) + + Note that you don't have to backslash-escape asterisks in the signature, as + it is not parsed by the reST inliner. + + In the description of a function you can use the following info fields + (see also :ref:`info-field-lists`). + + * ``param``, ``parameter``, ``arg``, ``argument``, + Description of a parameter. + * ``type``: Type of a parameter, + written as if passed to the :rst:role:`c:expr` role. + * ``returns``, ``return``: Description of the return value. + * ``rtype``: Return type, + written as if passed to the :rst:role:`c:expr` role. + * ``retval``, ``retvals``: An alternative to ``returns`` for describing + the result of the function. + + .. versionadded:: 4.3 + The ``retval`` field type. + + For example:: + + .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) + + :param type: description of the first parameter. + :param nitems: description of the second parameter. + :returns: a result. + :retval NULL: under some conditions. + :retval NULL: under some other conditions as well. + + which renders as + + .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) + + .. + ** for some editors (e.g., vim) to stop bold-highlighting the source + + :param type: description of the first parameter. + :param nitems: description of the second parameter. + :returns: a result. + :retval NULL: under some conditions. + :retval NULL: under some other conditions as well. + + .. rst:directive:option:: single-line-parameter-list + :type: no value + + Ensures that the function's parameters will be emitted on a single logical + line, overriding :confval:`c_maximum_signature_line_length` and + :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + + +.. rst:directive:: .. c:macro:: name + .. c:macro:: name(arg list) + + Describes a C macro, i.e., a C-language ``#define``, without the replacement + text. + + In the description of a macro you can use the same info fields as for the + :rst:dir:`c:function` directive. + + .. versionadded:: 3.0 + The function style variant. + + .. rst:directive:option:: single-line-parameter-list + :type: no value + + Ensures that the macro's parameters will be emitted on a single logical + line, overriding :confval:`c_maximum_signature_line_length` and + :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + +.. rst:directive:: .. c:struct:: name + + Describes a C struct. + + .. versionadded:: 3.0 + +.. rst:directive:: .. c:union:: name + + Describes a C union. + + .. versionadded:: 3.0 + +.. rst:directive:: .. c:enum:: name + + Describes a C enum. + + .. versionadded:: 3.0 + +.. rst:directive:: .. c:enumerator:: name + + Describes a C enumerator. + + .. versionadded:: 3.0 + +.. rst:directive:: .. c:type:: typedef-like declaration + .. c:type:: name + + Describes a C type, either as a typedef, or the alias for an unspecified + type. + +.. _c-roles: + +Cross-referencing C constructs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following roles create cross-references to C-language constructs if they +are defined in the documentation: + +.. rst:role:: c:member + c:data + c:var + c:func + c:macro + c:struct + c:union + c:enum + c:enumerator + c:type + + Reference a C declaration, as defined above. + Note that :rst:role:`c:member`, :rst:role:`c:data`, and + :rst:role:`c:var` are equivalent. + + .. versionadded:: 3.0 + The var, struct, union, enum, and enumerator roles. + + +Anonymous Entities +~~~~~~~~~~~~~~~~~~ + +C supports anonymous structs, enums, and unions. +For the sake of documentation they must be given some name that starts with +``@``, e.g., ``@42`` or ``@data``. +These names can also be used in cross-references, +though nested symbols will be found even when omitted. +The ``@...`` name will always be rendered as **[anonymous]** (possibly as a +link). + +Example:: + + .. c:struct:: Data + + .. c:union:: @data + + .. c:var:: int a + + .. c:var:: double b + + Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`. + +This will be rendered as: + +.. c:struct:: Data + :no-contents-entry: + :no-index-entry: + + .. c:union:: @data + :no-contents-entry: + :no-index-entry: + + .. c:var:: int a + :no-contents-entry: + :no-index-entry: + + .. c:var:: double b + :no-contents-entry: + :no-index-entry: + +Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`. + +.. versionadded:: 3.0 + + +Aliasing Declarations +~~~~~~~~~~~~~~~~~~~~~ + +.. c:namespace-push:: @alias + +Sometimes it may be helpful list declarations elsewhere than their main +documentation, e.g., when creating a synopsis of an interface. +The following directive can be used for this purpose. + +.. rst:directive:: .. c:alias:: name + + Insert one or more alias declarations. Each entity can be specified + as they can in the :rst:role:`c:any` role. + + For example:: + + .. c:var:: int data + .. c:function:: int f(double k) + + .. c:alias:: data + f + + becomes + + .. c:var:: int data + .. c:function:: int f(double k) + + .. c:alias:: data + f + + .. versionadded:: 3.2 + + + .. rubric:: Options + + .. rst:directive:option:: maxdepth: int + + Insert nested declarations as well, up to the total depth given. + Use 0 for infinite depth and 1 for just the mentioned declaration. + Defaults to 1. + + .. versionadded:: 3.3 + + .. rst:directive:option:: noroot + + Skip the mentioned declarations and only render nested declarations. + Requires ``maxdepth`` either 0 or at least 2. + + .. versionadded:: 3.5 + + +.. c:namespace-pop:: + + +Inline Expressions and Types +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. rst:role:: c:expr + c:texpr + + Insert a C expression or type either as inline code (``cpp:expr``) + or inline text (``cpp:texpr``). For example:: + + .. c:var:: int a = 42 + + .. c:function:: int f(int i) + + An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`). + + A type: :c:expr:`const Data*` + (or as text :c:texpr:`const Data*`). + + will be rendered as follows: + + .. c:var:: int a = 42 + :no-contents-entry: + :no-index-entry: + + .. c:function:: int f(int i) + :no-contents-entry: + :no-index-entry: + + An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`). + + A type: :c:expr:`const Data*` + (or as text :c:texpr:`const Data*`). + + .. versionadded:: 3.0 + + +Namespacing +~~~~~~~~~~~ + +.. versionadded:: 3.1 + +The C language it self does not support namespacing, but it can sometimes be +useful to emulate it in documentation, e.g., to show alternate declarations. +The feature may also be used to document members of structs/unions/enums +separate from their parent declaration. + +The current scope can be changed using three namespace directives. They manage +a stack declarations where ``c:namespace`` resets the stack and changes a given +scope. + +The ``c:namespace-push`` directive changes the scope to a given inner scope +of the current one. + +The ``c:namespace-pop`` directive undoes the most recent +``c:namespace-push`` directive. + +.. rst:directive:: .. c:namespace:: scope specification + + Changes the current scope for the subsequent objects to the given scope, and + resets the namespace directive stack. Note that nested scopes can be + specified by separating with a dot, e.g.:: + + .. c:namespace:: Namespace1.Namespace2.SomeStruct.AnInnerStruct + + All subsequent objects will be defined as if their name were declared with + the scope prepended. The subsequent cross-references will be searched for + starting in the current scope. + + Using ``NULL`` or ``0`` as the scope will change to global scope. + +.. rst:directive:: .. c:namespace-push:: scope specification + + Change the scope relatively to the current scope. For example, after:: + + .. c:namespace:: A.B + + .. c:namespace-push:: C.D + + the current scope will be ``A.B.C.D``. + +.. rst:directive:: .. c:namespace-pop:: + + Undo the previous ``c:namespace-push`` directive (*not* just pop a scope). + For example, after:: + + .. c:namespace:: A.B + + .. c:namespace-push:: C.D + + .. c:namespace-pop:: + + the current scope will be ``A.B`` (*not* ``A.B.C``). + + If no previous ``c:namespace-push`` directive has been used, but only a + ``c:namespace`` directive, then the current scope will be reset to global + scope. That is, ``.. c:namespace:: A.B`` is equivalent to:: + + .. c:namespace:: NULL + + .. c:namespace-push:: A.B + +Configuration Variables +~~~~~~~~~~~~~~~~~~~~~~~ + +See :ref:`c-config`. + + +.. _cpp-domain: + +The C++ Domain +-------------- + +The C++ domain (name **cpp**) supports documenting C++ projects. + +Directives for Declaring Entities +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following directives are available. All declarations can start with a +visibility statement (``public``, ``private`` or ``protected``). + +.. rst:directive:: .. cpp:class:: class specifier + .. cpp:struct:: class specifier + + Describe a class/struct, possibly with specification of inheritance, e.g.,:: + + .. cpp:class:: MyClass : public MyBase, MyOtherBase + + The difference between :rst:dir:`cpp:class` and :rst:dir:`cpp:struct` is + only cosmetic: the prefix rendered in the output, and the specifier shown + in the index. + + The class can be directly declared inside a nested scope, e.g.,:: + + .. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase + + A class template can be declared:: + + .. cpp:class:: template<typename T, std::size_t N> std::array + + or with a line break:: + + .. cpp:class:: template<typename T, std::size_t N> \ + std::array + + Full and partial template specialisations can be declared:: + + .. cpp:class:: template<> \ + std::array<bool, 256> + + .. cpp:class:: template<typename T> \ + std::array<T, 42> + + .. versionadded:: 2.0 + The :rst:dir:`cpp:struct` directive. + +.. rst:directive:: .. cpp:function:: (member) function prototype + + Describe a function or member function, e.g.,:: + + .. cpp:function:: bool myMethod(int arg1, std::string arg2) + + A function with parameters and types. + + .. cpp:function:: bool myMethod(int, double) + + A function with unnamed parameters. + + .. cpp:function:: const T &MyClass::operator[](std::size_t i) const + + An overload for the indexing operator. + + .. cpp:function:: operator bool() const + + A casting operator. + + .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept + + A constexpr function. + + .. cpp:function:: MyClass::MyClass(const MyClass&) = default + + A copy constructor with default implementation. + + Function templates can also be described:: + + .. cpp:function:: template<typename U> \ + void print(U &&u) + + and function template specialisations:: + + .. cpp:function:: template<> \ + void print(int i) + + .. rst:directive:option:: single-line-parameter-list + :type: no value + + Ensures that the function's parameters will be emitted on a single logical + line, overriding :confval:`cpp_maximum_signature_line_length` and + :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + +.. rst:directive:: .. cpp:member:: (member) variable declaration + .. cpp:var:: (member) variable declaration + + Describe a variable or member variable, e.g.,:: + + .. cpp:member:: std::string MyClass::myMember + + .. cpp:var:: std::string MyClass::myOtherMember[N][M] + + .. cpp:member:: int a = 42 + + Variable templates can also be described:: + + .. cpp:member:: template<class T> \ + constexpr T pi = T(3.1415926535897932385) + +.. rst:directive:: .. cpp:type:: typedef declaration + .. cpp:type:: name + .. cpp:type:: type alias declaration + + Describe a type as in a typedef declaration, a type alias declaration, or + simply the name of a type with unspecified type, e.g.,:: + + .. cpp:type:: std::vector<int> MyList + + A typedef-like declaration of a type. + + .. cpp:type:: MyContainer::const_iterator + + Declaration of a type alias with unspecified type. + + .. cpp:type:: MyType = std::unordered_map<int, std::string> + + Declaration of a type alias. + + A type alias can also be templated:: + + .. cpp:type:: template<typename T> \ + MyContainer = std::vector<T> + + The example are rendered as follows. + + .. cpp:type:: std::vector<int> MyList + :no-contents-entry: + :no-index-entry: + + A typedef-like declaration of a type. + + .. cpp:type:: MyContainer::const_iterator + :no-contents-entry: + :no-index-entry: + + Declaration of a type alias with unspecified type. + + .. cpp:type:: MyType = std::unordered_map<int, std::string> + :no-contents-entry: + :no-index-entry: + + Declaration of a type alias. + + .. cpp:type:: template<typename T> \ + MyContainer = std::vector<T> + :no-contents-entry: + :no-index-entry: + +.. rst:directive:: .. cpp:enum:: unscoped enum declaration + .. cpp:enum-struct:: scoped enum declaration + .. cpp:enum-class:: scoped enum declaration + + Describe a (scoped) enum, possibly with the underlying type specified. Any + enumerators declared inside an unscoped enum will be declared both in the + enum scope and in the parent scope. Examples:: + + .. cpp:enum:: MyEnum + + An unscoped enum. + + .. cpp:enum:: MySpecificEnum : long + + An unscoped enum with specified underlying type. + + .. cpp:enum-class:: MyScopedEnum + + A scoped enum. + + .. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type + + A scoped enum with non-default visibility, and with a specified + underlying type. + +.. rst:directive:: .. cpp:enumerator:: name + .. cpp:enumerator:: name = constant + + Describe an enumerator, optionally with its value defined, e.g.,:: + + .. cpp:enumerator:: MyEnum::myEnumerator + + .. cpp:enumerator:: MyEnum::myOtherEnumerator = 42 + +.. rst:directive:: .. cpp:union:: name + + Describe a union. + + .. versionadded:: 1.8 + +.. rst:directive:: .. cpp:concept:: template-parameter-list name + + .. warning:: The support for concepts is experimental. It is based on the + current draft standard and the Concepts Technical Specification. + The features may change as they evolve. + + Describe a concept. It must have exactly 1 template parameter list. The name + may be a nested name. Example:: + + .. cpp:concept:: template<typename It> std::Iterator + + Proxy to an element of a notional sequence that can be compared, + indirected, or incremented. + + **Notation** + + .. cpp:var:: It r + + An lvalue. + + **Valid Expressions** + + - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable. + - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when + :cpp:expr:`r` is incrementable. + + This will render as follows: + + .. cpp:concept:: template<typename It> std::Iterator + + Proxy to an element of a notional sequence that can be compared, + indirected, or incremented. + + **Notation** + + .. cpp:var:: It r + + An lvalue. + + **Valid Expressions** + + - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable. + - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when :cpp:expr:`r` + is incrementable. + + .. versionadded:: 1.5 + + +Options +^^^^^^^ + +Some directives support options: + +- ``:no-index-entry:`` and ``:no-contents-entry:``, see :ref:`basic-domain-markup`. +- ``:tparam-line-spec:``, for templated declarations. + If specified, each template parameter will be rendered on a separate line. + + .. versionadded:: 1.6 + +Anonymous Entities +~~~~~~~~~~~~~~~~~~ + +C++ supports anonymous namespaces, classes, enums, and unions. +For the sake of documentation they must be given some name that starts with +``@``, e.g., ``@42`` or ``@data``. +These names can also be used in cross-references and (type) expressions, +though nested symbols will be found even when omitted. +The ``@...`` name will always be rendered as **[anonymous]** (possibly as a +link). + +Example:: + + .. cpp:class:: Data + + .. cpp:union:: @data + + .. cpp:var:: int a + + .. cpp:var:: double b + + Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`. + +This will be rendered as: + +.. cpp:class:: Data + :no-contents-entry: + :no-index-entry: + + .. cpp:union:: @data + :no-contents-entry: + :no-index-entry: + + .. cpp:var:: int a + :no-contents-entry: + :no-index-entry: + + .. cpp:var:: double b + :no-contents-entry: + :no-index-entry: + +Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`. + +.. versionadded:: 1.8 + + +Aliasing Declarations +~~~~~~~~~~~~~~~~~~~~~ + +Sometimes it may be helpful list declarations elsewhere than their main +documentation, e.g., when creating a synopsis of a class interface. +The following directive can be used for this purpose. + +.. rst:directive:: .. cpp:alias:: name or function signature + + Insert one or more alias declarations. Each entity can be specified + as they can in the :rst:role:`cpp:any` role. + If the name of a function is given (as opposed to the complete signature), + then all overloads of the function will be listed. + + For example:: + + .. cpp:alias:: Data::a + overload_example::C::f + + becomes + + .. cpp:alias:: Data::a + overload_example::C::f + + whereas:: + + .. cpp:alias:: void overload_example::C::f(double d) const + void overload_example::C::f(double d) + + becomes + + .. cpp:alias:: void overload_example::C::f(double d) const + void overload_example::C::f(double d) + + .. versionadded:: 2.0 + + + .. rubric:: Options + + .. rst:directive:option:: maxdepth: int + + Insert nested declarations as well, up to the total depth given. + Use 0 for infinite depth and 1 for just the mentioned declaration. + Defaults to 1. + + .. versionadded:: 3.5 + + .. rst:directive:option:: noroot + + Skip the mentioned declarations and only render nested declarations. + Requires ``maxdepth`` either 0 or at least 2. + + .. versionadded:: 3.5 + + +Constrained Templates +~~~~~~~~~~~~~~~~~~~~~ + +.. warning:: The support for concepts is experimental. It is based on the + current draft standard and the Concepts Technical Specification. + The features may change as they evolve. + +.. note:: Sphinx does not currently support ``requires`` clauses. + +Placeholders +^^^^^^^^^^^^ + +Declarations may use the name of a concept to introduce constrained template +parameters, or the keyword ``auto`` to introduce unconstrained template +parameters:: + + .. cpp:function:: void f(auto &&arg) + + A function template with a single unconstrained template parameter. + + .. cpp:function:: void f(std::Iterator it) + + A function template with a single template parameter, constrained by the + Iterator concept. + +Template Introductions +^^^^^^^^^^^^^^^^^^^^^^ + +Simple constrained function or class templates can be declared with a `template +introduction` instead of a template parameter list:: + + .. cpp:function:: std::Iterator{It} void advance(It &it) + + A function template with a template parameter constrained to be an + Iterator. + + .. cpp:class:: std::LessThanComparable{T} MySortedContainer + + A class template with a template parameter constrained to be + LessThanComparable. + +They are rendered as follows. + +.. cpp:function:: std::Iterator{It} void advance(It &it) + :no-contents-entry: + :no-index-entry: + + A function template with a template parameter constrained to be an Iterator. + +.. cpp:class:: std::LessThanComparable{T} MySortedContainer + :no-contents-entry: + :no-index-entry: + + A class template with a template parameter constrained to be + LessThanComparable. + +Note however that no checking is performed with respect to parameter +compatibility. E.g., ``Iterator{A, B, C}`` will be accepted as an introduction +even though it would not be valid C++. + +Inline Expressions and Types +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. rst:role:: cpp:expr + cpp:texpr + + Insert a C++ expression or type either as inline code (``cpp:expr``) + or inline text (``cpp:texpr``). For example:: + + .. cpp:var:: int a = 42 + + .. cpp:function:: int f(int i) + + An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`). + + A type: :cpp:expr:`const MySortedContainer<int>&` + (or as text :cpp:texpr:`const MySortedContainer<int>&`). + + will be rendered as follows: + + .. cpp:var:: int a = 42 + :no-contents-entry: + :no-index-entry: + + .. cpp:function:: int f(int i) + :no-contents-entry: + :no-index-entry: + + An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`). + + A type: :cpp:expr:`const MySortedContainer<int>&` + (or as text :cpp:texpr:`const MySortedContainer<int>&`). + + .. versionadded:: 1.7 + The :rst:role:`cpp:expr` role. + + .. versionadded:: 1.8 + The :rst:role:`cpp:texpr` role. + +Namespacing +~~~~~~~~~~~ + +Declarations in the C++ domain are as default placed in global scope. The +current scope can be changed using three namespace directives. They manage a +stack declarations where ``cpp:namespace`` resets the stack and changes a given +scope. + +The ``cpp:namespace-push`` directive changes the scope to a given inner scope +of the current one. + +The ``cpp:namespace-pop`` directive undoes the most recent +``cpp:namespace-push`` directive. + +.. rst:directive:: .. cpp:namespace:: scope specification + + Changes the current scope for the subsequent objects to the given scope, and + resets the namespace directive stack. Note that the namespace does not need + to correspond to C++ namespaces, but can end in names of classes, e.g.,:: + + .. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass + + All subsequent objects will be defined as if their name were declared with + the scope prepended. The subsequent cross-references will be searched for + starting in the current scope. + + Using ``NULL``, ``0``, or ``nullptr`` as the scope will change to global + scope. + + A namespace declaration can also be templated, e.g.,:: + + .. cpp:class:: template<typename T> \ + std::vector + + .. cpp:namespace:: template<typename T> std::vector + + .. cpp:function:: std::size_t size() const + + declares ``size`` as a member function of the class template + ``std::vector``. Equivalently this could have been declared using:: + + .. cpp:class:: template<typename T> \ + std::vector + + .. cpp:function:: std::size_t size() const + + or:: + + .. cpp:class:: template<typename T> \ + std::vector + +.. rst:directive:: .. cpp:namespace-push:: scope specification + + Change the scope relatively to the current scope. For example, after:: + + .. cpp:namespace:: A::B + + .. cpp:namespace-push:: C::D + + the current scope will be ``A::B::C::D``. + + .. versionadded:: 1.4 + +.. rst:directive:: .. cpp:namespace-pop:: + + Undo the previous ``cpp:namespace-push`` directive (*not* just pop a scope). + For example, after:: + + .. cpp:namespace:: A::B + + .. cpp:namespace-push:: C::D + + .. cpp:namespace-pop:: + + the current scope will be ``A::B`` (*not* ``A::B::C``). + + If no previous ``cpp:namespace-push`` directive has been used, but only a + ``cpp:namespace`` directive, then the current scope will be reset to global + scope. That is, ``.. cpp:namespace:: A::B`` is equivalent to:: + + .. cpp:namespace:: nullptr + + .. cpp:namespace-push:: A::B + + .. versionadded:: 1.4 + +Info field lists +~~~~~~~~~~~~~~~~~ + +All the C++ directives for declaring entities support the following +info fields (see also :ref:`info-field-lists`): + +* ``tparam``: Description of a template parameter. + +The :rst:dir:`cpp:function` directive additionally supports the +following fields: + +* ``param``, ``parameter``, ``arg``, ``argument``: Description of a parameter. +* ``returns``, ``return``: Description of a return value. +* ``retval``, ``retvals``: An alternative to ``returns`` for describing + the result of the function. +* `throws`, `throw`, `exception`: Description of a possibly thrown exception. + +.. versionadded:: 4.3 + The ``retval`` field type. + +.. _cpp-roles: + +Cross-referencing +~~~~~~~~~~~~~~~~~ + +These roles link to the given declaration types: + +.. rst:role:: cpp:any + cpp:class + cpp:struct + cpp:func + cpp:member + cpp:var + cpp:type + cpp:concept + cpp:enum + cpp:enumerator + + Reference a C++ declaration by name (see below for details). The name must + be properly qualified relative to the position of the link. + + .. versionadded:: 2.0 + The :rst:role:`cpp:struct` role as alias for the :rst:role:`cpp:class` + role. + +.. admonition:: Note on References with Templates Parameters/Arguments + + These roles follow the Sphinx :ref:`xref-syntax` rules. This means care must + be taken when referencing a (partial) template specialization, e.g. if the + link looks like this: ``:cpp:class:`MyClass<int>```. + This is interpreted as a link to ``int`` with a title of ``MyClass``. + In this case, escape the opening angle bracket with a backslash, + like this: ``:cpp:class:`MyClass\<int>```. + + When a custom title is not needed it may be useful to use the roles for + inline expressions, :rst:role:`cpp:expr` and :rst:role:`cpp:texpr`, where + angle brackets do not need escaping. + +Declarations without template parameters and template arguments +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For linking to non-templated declarations the name must be a nested name, e.g., +``f`` or ``MyClass::f``. + + +Overloaded (member) functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When a (member) function is referenced using just its name, the reference +will point to an arbitrary matching overload. +The :rst:role:`cpp:any` and :rst:role:`cpp:func` roles use an alternative +format, which simply is a complete function declaration. +This will resolve to the exact matching overload. +As example, consider the following class declaration: + +.. cpp:namespace-push:: overload_example +.. cpp:class:: C + + .. cpp:function:: void f(double d) const + .. cpp:function:: void f(double d) + .. cpp:function:: void f(int i) + .. cpp:function:: void f() + +References using the :rst:role:`cpp:func` role: + +- Arbitrary overload: ``C::f``, :cpp:func:`C::f` +- Also arbitrary overload: ``C::f()``, :cpp:func:`C::f()` +- Specific overload: ``void C::f()``, :cpp:func:`void C::f()` +- Specific overload: ``void C::f(int)``, :cpp:func:`void C::f(int)` +- Specific overload: ``void C::f(double)``, :cpp:func:`void C::f(double)` +- Specific overload: ``void C::f(double) const``, + :cpp:func:`void C::f(double) const` + +Note that the :confval:`add_function_parentheses` configuration variable +does not influence specific overload references. + +.. cpp:namespace-pop:: + + +Templated declarations +^^^^^^^^^^^^^^^^^^^^^^ + +Assume the following declarations. + +.. cpp:class:: Wrapper + + .. cpp:class:: template<typename TOuter> \ + Outer + + .. cpp:class:: template<typename TInner> \ + Inner + +In general the reference must include the template parameter declarations, +and template arguments for the prefix of qualified names. For example: + +- ``template\<typename TOuter> Wrapper::Outer`` + (:cpp:class:`template\<typename TOuter> Wrapper::Outer`) +- ``template\<typename TOuter> template\<typename TInner> Wrapper::Outer<TOuter>::Inner`` + (:cpp:class:`template\<typename TOuter> template\<typename TInner> Wrapper::Outer<TOuter>::Inner`) + +Currently the lookup only succeed if the template parameter identifiers are +equal strings. That is, ``template\<typename UOuter> Wrapper::Outer`` will not +work. + +As a shorthand notation, if a template parameter list is omitted, +then the lookup will assume either a primary template or a non-template, +but not a partial template specialisation. +This means the following references work as well: + +- ``Wrapper::Outer`` + (:cpp:class:`Wrapper::Outer`) +- ``Wrapper::Outer::Inner`` + (:cpp:class:`Wrapper::Outer::Inner`) +- ``template\<typename TInner> Wrapper::Outer::Inner`` + (:cpp:class:`template\<typename TInner> Wrapper::Outer::Inner`) + +(Full) Template Specialisations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Assume the following declarations. + +.. cpp:class:: template<typename TOuter> \ + Outer + + .. cpp:class:: template<typename TInner> \ + Inner + +.. cpp:class:: template<> \ + Outer<int> + + .. cpp:class:: template<typename TInner> \ + Inner + + .. cpp:class:: template<> \ + Inner<bool> + +In general the reference must include a template parameter list for each +template argument list. The full specialisation above can therefore be +referenced with ``template\<> Outer\<int>`` (:cpp:class:`template\<> +Outer\<int>`) and ``template\<> template\<> Outer\<int>::Inner\<bool>`` +(:cpp:class:`template\<> template\<> Outer\<int>::Inner\<bool>`). As a +shorthand the empty template parameter list can be omitted, e.g., +``Outer\<int>`` (:cpp:class:`Outer\<int>`) and ``Outer\<int>::Inner\<bool>`` +(:cpp:class:`Outer\<int>::Inner\<bool>`). + +Partial Template Specialisations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Assume the following declaration. + +.. cpp:class:: template<typename T> \ + Outer<T*> + +References to partial specialisations must always include the template +parameter lists, e.g., ``template\<typename T> Outer\<T*>`` +(:cpp:class:`template\<typename T> Outer\<T*>`). Currently the lookup only +succeed if the template parameter identifiers are equal strings. + +Configuration Variables +~~~~~~~~~~~~~~~~~~~~~~~ + +See :ref:`cpp-config`. + +.. _domains-std: + +The Standard Domain +------------------- + +The so-called "standard" domain collects all markup that doesn't warrant a +domain of its own. Its directives and roles are not prefixed with a domain +name. + +The standard domain is also where custom object descriptions, added using the +:func:`~sphinx.application.Sphinx.add_object_type` API, are placed. + +There is a set of directives allowing documenting command-line programs: + +.. rst:directive:: .. option:: name args, name args, ... + + Describes a command line argument or switch. Option argument names should + be enclosed in angle brackets. Examples:: + + .. option:: dest_dir + + Destination directory. + + .. option:: -m <module>, --module <module> + + Run a module as a script. + + The directive will create cross-reference targets for the given options, + referenceable by :rst:role:`option` (in the example case, you'd use something + like ``:option:`dest_dir```, ``:option:`-m```, or ``:option:`--module```). + + .. versionchanged:: 5.3 + + One can cross-reference including an option value: ``:option:`--module=foobar```, + ,``:option:`--module[=foobar]``` or ``:option:`--module foobar```. + + Use :confval:`option_emphasise_placeholders` for parsing of + "variable part" of a literal text (similarly to the :rst:role:`samp` role). + + ``cmdoption`` directive is a deprecated alias for the ``option`` directive. + +.. rst:directive:: .. envvar:: name + + Describes an environment variable that the documented code or program uses + or defines. Referenceable by :rst:role:`envvar`. + +.. rst:directive:: .. program:: name + + Like :rst:dir:`py:currentmodule`, this directive produces no output. + Instead, it serves to notify Sphinx that all following :rst:dir:`option` + directives document options for the program called *name*. + + If you use :rst:dir:`program`, you have to qualify the references in your + :rst:role:`option` roles by the program name, so if you have the following + situation :: + + .. program:: rm + + .. option:: -r + + Work recursively. + + .. program:: svn + + .. option:: -r <revision> + + Specify the revision to work upon. + + then ``:option:`rm -r``` would refer to the first option, while + ``:option:`svn -r``` would refer to the second one. + + If ``None`` is passed to the argument, the directive will reset the + current program name. + + The program name may contain spaces (in case you want to document + subcommands like ``svn add`` and ``svn commit`` separately). + + .. versionadded:: 0.5 + +There is also a very generic object description directive, which is not tied to +any domain: + +.. rst:directive:: .. describe:: text + .. object:: text + + This directive produces the same formatting as the specific ones provided by + domains, but does not create index entries or cross-referencing targets. + Example:: + + .. describe:: PAPER + + You can set this variable to select a paper size. + + +The JavaScript Domain +--------------------- + +The JavaScript domain (name **js**) provides the following directives: + +.. rst:directive:: .. js:module:: name + + This directive sets the module name for object declarations that follow + after. The module name is used in the global module index and in cross + references. This directive does not create an object heading like + :rst:dir:`py:class` would, for example. + + By default, this directive will create a linkable entity and will cause an + entry in the global module index, unless the ``no-index`` option is + specified. If this option is specified, the directive will only update the + current module name. + + .. versionadded:: 1.6 + .. versionchanged:: 5.2 + + Module directives support body content. + +.. rst:directive:: .. js:function:: name(signature) + + Describes a JavaScript function or method. If you want to describe + arguments as optional use square brackets as :ref:`documented <signatures>` + for Python signatures. + + You can use fields to give more details about arguments and their expected + types, errors which may be thrown by the function, and the value being + returned:: + + .. js:function:: $.getJSON(href, callback[, errback]) + + :param string href: An URI to the location of the resource. + :param callback: Gets called with the object. + :param errback: + Gets called in case the request fails. And a lot of other + text so we need multiple lines. + :throws SomeError: For whatever reason in that case. + :returns: Something. + + This is rendered as: + + .. js:function:: $.getJSON(href, callback[, errback]) + :no-index: + + :param string href: An URI to the location of the resource. + :param callback: Gets called with the object. + :param errback: + Gets called in case the request fails. And a lot of other + text so we need multiple lines. + :throws SomeError: For whatever reason in that case. + :returns: Something. + + .. rst:directive:option:: single-line-parameter-list + :type: no value + + Ensures that the function's parameters will be emitted on a single logical + line, overriding :confval:`javascript_maximum_signature_line_length` and + :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + +.. rst:directive:: .. js:method:: name(signature) + + This directive is an alias for :rst:dir:`js:function`, however it describes + a function that is implemented as a method on a class object. + + .. versionadded:: 1.6 + + .. rst:directive:option:: single-line-parameter-list + :type: no value + + Ensures that the function's parameters will be emitted on a single logical + line, overriding :confval:`javascript_maximum_signature_line_length` and + :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + +.. rst:directive:: .. js:class:: name + + Describes a constructor that creates an object. This is basically like a + function but will show up with a `class` prefix:: + + .. js:class:: MyAnimal(name[, age]) + + :param string name: The name of the animal + :param number age: an optional age for the animal + + This is rendered as: + + .. js:class:: MyAnimal(name[, age]) + :no-index: + + :param string name: The name of the animal + :param number age: an optional age for the animal + + .. rst:directive:option:: single-line-parameter-list + :type: no value + + Ensures that the function's parameters will be emitted on a single logical + line, overriding :confval:`javascript_maximum_signature_line_length` and + :confval:`maximum_signature_line_length`. + + .. versionadded:: 7.1 + +.. rst:directive:: .. js:data:: name + + Describes a global variable or constant. + +.. rst:directive:: .. js:attribute:: object.name + + Describes the attribute *name* of *object*. + +.. _js-roles: + +These roles are provided to refer to the described objects: + +.. rst:role:: js:mod + js:func + js:meth + js:class + js:data + js:attr + + +The reStructuredText domain +--------------------------- + +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:: + + .. rst:directive:: foo + + Foo description. + + .. rst:directive:: .. bar:: baz + + Bar description. + + will be rendered as: + + .. rst:directive:: foo + :no-index: + + Foo description. + + .. rst:directive:: .. bar:: baz + :no-index: + + Bar description. + +.. rst:directive:: .. rst:directive:option:: name + + Describes an option for reST directive. The *name* can be a single option + name or option name with arguments which separated with colon (``:``). + For example:: + + .. rst:directive:: toctree + + .. rst:directive:option:: caption: caption of ToC + + .. rst:directive:option:: glob + + will be rendered as: + + .. rst:directive:: toctree + :no-index: + + .. rst:directive:option:: caption: caption of ToC + :no-index: + + .. rst:directive:option:: glob + :no-index: + + .. rubric:: options + + .. rst:directive:option:: type: description of argument + :type: text + + Describe the type of option value. + + For example:: + + .. rst:directive:: toctree + + .. rst:directive:option:: maxdepth + :type: integer or no value + + .. versionadded:: 2.1 + +.. rst:directive:: .. rst:role:: name + + Describes a reST role. For example:: + + .. rst:role:: foo + + Foo description. + + will be rendered as: + + .. rst:role:: foo + :no-index: + + Foo description. + +.. _rst-roles: + +These roles are provided to refer to the described objects: + +.. rst:role:: rst:dir + rst:role + +.. _math-domain: + +The Math Domain +--------------- + +The math domain (name **math**) provides the following roles: + +.. rst:role:: math:numref + + Role for cross-referencing equations defined by :rst:dir:`math` directive + via their label. Example:: + + .. math:: e^{i\pi} + 1 = 0 + :label: euler + + Euler's identity, equation :math:numref:`euler`, was elected one of the + most beautiful mathematical formulas. + + .. versionadded:: 1.8 + +More domains +------------ + +The sphinx-contrib_ repository contains more domains available as extensions; +currently Ada_, CoffeeScript_, Erlang_, HTTP_, Lasso_, MATLAB_, PHP_, and Ruby_ +domains. Also available are domains for `Chapel`_, `Common Lisp`_, dqn_, Go_, +Jinja_, Operation_, and Scala_. + +.. _sphinx-contrib: https://github.com/sphinx-contrib + +.. _Ada: https://pypi.org/project/sphinxcontrib-adadomain/ +.. _Chapel: https://pypi.org/project/sphinxcontrib-chapeldomain/ +.. _CoffeeScript: https://pypi.org/project/sphinxcontrib-coffee/ +.. _Common Lisp: https://pypi.org/project/sphinxcontrib-cldomain/ +.. _dqn: https://pypi.org/project/sphinxcontrib-dqndomain/ +.. _Erlang: https://pypi.org/project/sphinxcontrib-erlangdomain/ +.. _Go: https://pypi.org/project/sphinxcontrib-golangdomain/ +.. _HTTP: https://pypi.org/project/sphinxcontrib-httpdomain/ +.. _Jinja: https://pypi.org/project/sphinxcontrib-jinjadomain/ +.. _Lasso: https://pypi.org/project/sphinxcontrib-lassodomain/ +.. _MATLAB: https://pypi.org/project/sphinxcontrib-matlabdomain/ +.. _Operation: https://pypi.org/project/sphinxcontrib-operationdomain/ +.. _PHP: https://pypi.org/project/sphinxcontrib-phpdomain/ +.. _Ruby: https://github.com/sphinx-contrib/rubydomain +.. _Scala: https://pypi.org/project/sphinxcontrib-scaladomain/ diff --git a/doc/usage/restructuredtext/field-lists.rst b/doc/usage/restructuredtext/field-lists.rst new file mode 100644 index 0000000..5fc897d --- /dev/null +++ b/doc/usage/restructuredtext/field-lists.rst @@ -0,0 +1,78 @@ +.. highlight:: rst + +=========== +Field Lists +=========== + +:ref:`As previously discussed <rst-field-lists>`, field lists are sequences of +fields marked up like this:: + + :fieldname: Field content + +Sphinx extends standard docutils behavior for field lists and adds some extra +functionality that is covered in this section. + +.. note:: + + The values of field lists will be parsed as + strings. You cannot use Python collections such as lists or dictionaries. + + +.. _metadata: + +File-wide metadata +------------------ + +A field list near the top of a file is normally parsed by docutils as the +*docinfo* and shown on the page. However, in Sphinx, a field list preceding +any other markup is moved from the *docinfo* to the Sphinx environment as +document metadata, and is not displayed in the output. + +.. note:: + + A field list appearing after the document title *will* be part of the + *docinfo* as normal and will be displayed in the output. + + +Special metadata fields +----------------------- + +Sphinx provides custom behavior for bibliographic fields compared to docutils. + +At the moment, these metadata fields are recognized: + +``tocdepth`` + The maximum depth for a table of contents of this file. :: + + :tocdepth: 2 + + .. 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. + + .. versionadded:: 0.4 + +``nocomments`` + If set, the web application won't display a comment form for a page + generated from this source file. :: + + :nocomments: + +``orphan`` + If set, warnings about this file not being included in any toctree will be + suppressed. :: + + :orphan: + + .. versionadded:: 1.0 + +``nosearch`` + If set, full text search for this file is disabled. :: + + :nosearch: + + .. note:: object search is still available even if `nosearch` option is set. + + .. versionadded:: 3.0 diff --git a/doc/usage/restructuredtext/index.rst b/doc/usage/restructuredtext/index.rst new file mode 100644 index 0000000..87b6ed6 --- /dev/null +++ b/doc/usage/restructuredtext/index.rst @@ -0,0 +1,24 @@ +.. _rst-index: + +================ +reStructuredText +================ + +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`__. + +__ https://docutils.sourceforge.io/rst.html + +.. toctree:: + :maxdepth: 2 + + basics + roles + directives + field-lists + domains diff --git a/doc/usage/restructuredtext/roles.rst b/doc/usage/restructuredtext/roles.rst new file mode 100644 index 0000000..e468de9 --- /dev/null +++ b/doc/usage/restructuredtext/roles.rst @@ -0,0 +1,536 @@ +.. highlight:: rst + +===== +Roles +===== + +Sphinx uses interpreted text roles to insert semantic markup into documents. +They are written as ``:rolename:`content```. + +.. note:: + + The default role (```content```) has no special meaning by default. You are + free to use it for anything you like, e.g. variable names; use the + :confval:`default_role` config value to set it to a known role -- the + :rst:role:`any` role to find anything or the :rst:role:`py:obj` role to find + Python objects are very useful for this. + +See :doc:`/usage/restructuredtext/domains` for roles added by domains. + + +.. _xref-syntax: + +Cross-referencing syntax +------------------------ + +Cross-references are generated by many semantic interpreted text roles. +Basically, you only need to write ``:role:`target```, and a link will be +created to the item named *target* of the type indicated by *role*. The link's +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*. + +* If you prefix the content with ``!``, no reference/hyperlink will be created. + +* If you prefix the content with ``~``, the link text will only be the last + component of the target. For example, ``:py:meth:`~Queue.Queue.get``` will + refer to ``Queue.Queue.get`` but only display ``get`` as the link text. This + does not work with all cross-reference roles, but is domain specific. + + In HTML output, the link's ``title`` attribute (that is e.g. shown as a + tool-tip on mouse-hover) will always be the full target name. + + +.. _any-role: + +Cross-referencing anything +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. rst:role:: any + + .. versionadded:: 1.3 + + This convenience role tries to do its best to find a valid target for its + reference text. + + * First, it tries standard cross-reference targets that would be referenced + by :rst:role:`doc`, :rst:role:`ref` or :rst:role:`option`. + + Custom objects added to the standard domain by extensions (see + :meth:`.Sphinx.add_object_type`) are also searched. + + * Then, it looks for objects (targets) in all loaded domains. It is up to + the domains how specific a match must be. For example, in the Python + domain a reference of ``:any:`Builder``` would match the + ``sphinx.builders.Builder`` class. + + If none or multiple targets are found, a warning will be emitted. In the + case of multiple targets, you can change "any" to a specific role. + + This role is a good candidate for setting :confval:`default_role`. If you + do, you can write cross-references without a lot of markup overhead. For + example, in this Python function documentation:: + + .. function:: install() + + This function installs a `handler` for every signal known by the + `signal` module. See the section `about-signals` for more information. + + there could be references to a glossary term (usually ``:term:`handler```), a + Python module (usually ``:py:mod:`signal``` or ``:mod:`signal```) and a + section (usually ``:ref:`about-signals```). + + The :rst:role:`any` role also works together with the + :mod:`~sphinx.ext.intersphinx` extension: when no local cross-reference is + found, all object types of intersphinx inventories are also searched. + +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-role: + +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: + + * If you place a label directly before a section title, you can reference to + it with ``:ref:`label-name```. For example:: + + .. _my-reference-label: + + Section to cross-reference + -------------------------- + + This is the text of the section. + + It refers to the section itself, see :ref:`my-reference-label`. + + The ``:ref:`` role would then generate a link to the section, with the + link title being "Section to cross-reference". This works just as well + when section and reference are in different source files. + + Automatic labels also work with figures. For example:: + + .. _my-figure: + + .. figure:: whatever + + Figure caption + + In this case, a reference ``:ref:`my-figure``` would insert a reference + to the figure with link text "Figure caption". + + The same works for tables that are given an explicit caption using the + :dudir:`table` directive. + + * Labels that aren't placed before a section title can still be referenced, + but you must give the link an explicit title, using this syntax: + ``:ref:`Link title <label-name>```. + + .. note:: + + Reference labels must start with an underscore. When referencing a label, + the underscore must be omitted (see examples above). + + Using :rst:role:`ref` is advised over standard reStructuredText links to + sections (like ```Section title`_``) because it works across files, when + section headings are changed, will raise warnings if incorrect, and works + for all builders that support cross-references. + + +Cross-referencing documents +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 0.6 + +There is also a way to directly link to documents: + +.. rst:role:: doc + + Link to the specified document; the document name can be specified in + absolute or relative fashion. For example, if the reference + ``:doc:`parrot``` occurs in the document ``sketches/index``, then the link + refers to ``sketches/parrot``. If the reference is ``:doc:`/people``` or + ``:doc:`../people```, the link refers to ``people``. + + If no explicit link text is given (like usual: ``:doc:`Monty Python members + </people>```), the link caption will be the title of the given document. + + +Referencing downloadable files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 0.6 + +.. 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. + + When you use this role, the referenced file is automatically marked for + inclusion in the output when building (obviously, for HTML output only). + All downloadable files are put into a ``_downloads/<unique hash>/`` + subdirectory of the output directory; duplicate filenames are handled. + + An example:: + + See :download:`this example script <../example.py>`. + + The given filename is usually relative to the directory the current source + file is contained in, but if it absolute (starting with ``/``), it is taken + as relative to the top source directory. + + The ``example.py`` file will be copied to the output directory, and a + suitable link generated to it. + + Not to show unavailable download links, you should wrap whole paragraphs that + have this role:: + + .. only:: builder_html + + See :download:`this example script <../example.py>`. + +Cross-referencing figures by figure number +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 1.3 + +.. versionchanged:: 1.5 + `numref` role can also refer sections. + And `numref` allows `{name}` for the link text. + +.. 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 + the figure with link text by its figure number like "Fig. 1.1". + + If an explicit link text is given (as usual: ``:numref:`Image of Sphinx (Fig. + %s) <my-figure>```), the link caption will serve as title of the reference. + As placeholders, `%s` and `{number}` get replaced by the figure + number and `{name}` by the figure caption. + If no explicit link text is given, the :confval:`numfig_format` setting is + used as fall-back default. + + If :confval:`numfig` is ``False``, figures are not numbered, + so this role inserts not a reference but the label or the link text. + +Cross-referencing other items of interest +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following roles do possibly create a cross-reference, but do not refer to +objects: + +.. rst:role:: envvar + + An environment variable. Index entries are generated. Also generates a link + to the matching :rst:dir:`envvar` directive, if it exists. + +.. rst:role:: token + + The name of a grammar token (used to create links between + :rst:dir:`productionlist` directives). + +.. rst:role:: keyword + + The name of a keyword in Python. This creates a link to a reference label + with that name, if it exists. + +.. rst:role:: option + + A command-line option to an executable program. This generates a link to + a :rst:dir:`option` directive, if it exists. + + +The following role creates a cross-reference to a term in a +:ref:`glossary <glossary-directive>`: + +.. rst:role:: term + + Reference to a term in a glossary. A glossary is created using the + ``glossary`` directive containing a definition list with terms and + definitions. It does not have to be in the same file as the ``term`` markup, + for example the Python docs have one global glossary in the ``glossary.rst`` + file. + + If you use a term that's not explained in a glossary, you'll get a warning + during build. + +Inline code highlighting +------------------------ + +.. rst:role:: code + + An *inline* code example. When used directly, this role just displays the + text *without* syntax highlighting, as a literal. + + .. code-block:: rst + + By default, inline code such as :code:`1 + 2` just displays without + highlighting. + + Displays: By default, inline code such as :code:`1 + 2` just displays without + highlighting. + + Unlike the :rst:dir:`code-block` directive, this role does not respect the + default language set by the :rst:dir:`highlight` directive. + + To enable syntax highlighting, you must first use the Docutils :dudir:`role` + directive to define a custom role associated with a specific language: + + .. code-block:: rst + + .. role:: python(code) + :language: python + + In Python, :python:`1 + 2` is equal to :python:`3`. + + To display a multi-line code example, use the :rst:dir:`code-block` directive + instead. + +Math +---- + +.. rst:role:: math + + Role for inline math. Use like this:: + + Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`. + + Displays: Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`. + +.. rst:role:: eq + + Same as :rst:role:`math:numref`. + + +Other semantic markup +--------------------- + +The following roles don't do anything special except formatting the text in a +different style: + +.. rst:role:: abbr + + An abbreviation. If the role content contains a parenthesized explanation, + it will be treated specially: it will be shown in a tool-tip in HTML, and + output only once in LaTeX. + + For example: ``:abbr:`LIFO (last-in, first-out)``` displays + :abbr:`LIFO (last-in, first-out)`. + + .. versionadded:: 0.6 + +.. rst:role:: command + + The name of an OS-level command, such as ``rm``. + + For example: :command:`rm` + +.. rst:role:: dfn + + Mark the defining instance of a term in the text. (No index entries are + generated.) + + For example: :dfn:`binary mode` + +.. rst:role:: file + + The name of a file or directory. Within the contents, you can use curly + braces to indicate a "variable" part, for example:: + + ... is installed in :file:`/usr/lib/python3.{x}/site-packages` ... + + Displays: ... is installed in :file:`/usr/lib/python3.{x}/site-packages` ... + + In the built documentation, the ``x`` will be displayed differently to + indicate that it is to be replaced by the Python minor version. + +.. rst:role:: guilabel + + Labels presented as part of an interactive user interface should be marked + using ``guilabel``. This includes labels from text-based interfaces such as + those created using :mod:`curses` or other text-based libraries. Any label + used in the interface should be marked with this role, including button + labels, window titles, field names, menu and menu selection names, and even + values in selection lists. + + .. versionchanged:: 1.0 + An accelerator key for the GUI label can be included using an ampersand; + this will be stripped and displayed underlined in the output (for example: + ``:guilabel:`&Cancel``` displays :guilabel:`&Cancel`). To include a literal + ampersand, double it. + +.. rst:role:: kbd + + Mark a sequence of keystrokes. What form the key sequence takes may depend + on platform- or application-specific conventions. When there are no + relevant conventions, the names of modifier keys should be spelled out, to + improve accessibility for new users and non-native speakers. For example, + an *xemacs* key sequence may be marked like ``:kbd:`C-x C-f```, but without + reference to a specific application or platform, the same sequence should be + marked as ``:kbd:`Control-x Control-f```, displaying :kbd:`C-x C-f` and + :kbd:`Control-x Control-f` respectively. + +.. rst:role:: mailheader + + The name of an RFC 822-style mail header. This markup does not imply that + the header is being used in an email message, but can be used to refer to + any header of the same "style." This is also used for headers defined by + the various MIME specifications. The header name should be entered in the + same way it would normally be found in practice, with the camel-casing + conventions being preferred where there is more than one common usage. For + example: ``:mailheader:`Content-Type``` displays :mailheader:`Content-Type`. + +.. rst:role:: makevar + + The name of a :command:`make` variable. + + For example: :makevar:`help` + +.. rst:role:: manpage + + A reference to a Unix manual page including the section, e.g. + ``:manpage:`ls(1)``` displays :manpage:`ls(1)`. Creates a hyperlink to an + external site rendering the manpage if :confval:`manpages_url` is defined. + +.. rst:role:: menuselection + + Menu selections should be marked using the ``menuselection`` role. This is + used to mark a complete sequence of menu selections, including selecting + submenus and choosing a specific operation, or any subsequence of such a + sequence. The names of individual selections should be separated by + ``-->``. + + For example, to mark the selection "Start > Programs", use this markup:: + + :menuselection:`Start --> Programs` + + Displays: :menuselection:`Start --> Programs` + + When including a selection that includes some trailing indicator, such as + the ellipsis some operating systems use to indicate that the command opens a + dialog, the indicator should be omitted from the selection name. + + ``menuselection`` also supports ampersand accelerators just like + :rst:role:`guilabel`. + +.. rst:role:: mimetype + + The name of a MIME type, or a component of a MIME type (the major or minor + portion, taken alone). + + For example: :mimetype:`text/plain` + +.. rst:role:: newsgroup + + The name of a Usenet newsgroup. + + For example: :newsgroup:`comp.lang.python` + +.. todo:: Is this not part of the standard domain? + +.. rst:role:: program + + The name of an executable program. This may differ from the file name for + the executable for some platforms. In particular, the ``.exe`` (or other) + extension should be omitted for Windows programs. + + For example: :program:`curl` + +.. rst:role:: regexp + + A regular expression. Quotes should not be included. + + For example: :regexp:`([abc])+` + +.. rst:role:: samp + + A piece of literal text, such as code. Within the contents, you can use + curly braces to indicate a "variable" part, as in :rst:role:`file`. For + example, in ``:samp:`print 1+{variable}```, the part ``variable`` would be + emphasized: :samp:`print 1+{variable}` + + If you don't need the "variable part" indication, use the standard + :rst:role:`code` role instead. + + .. versionchanged:: 1.8 + Allowed to escape curly braces with backslash + +There is also an :rst:role:`index` role to generate index entries. + +The following roles generate external links: + +.. rst:role:: pep + + A reference to a Python Enhancement Proposal. This generates appropriate + index entries. The text "PEP *number*\ " is generated; in the HTML output, + this text is a hyperlink to an online copy of the specified PEP. You can + link to a specific section by saying ``:pep:`number#anchor```. + + For example: :pep:`8` + +.. rst:role:: rfc + + A reference to an Internet Request for Comments. This generates appropriate + index entries. The text "RFC *number*\ " is generated; in the HTML output, + this text is a hyperlink to an online copy of the specified RFC. You can + link to a specific section by saying ``:rfc:`number#anchor```. + + 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. + + +.. _default-substitutions: + +Substitutions +------------- + +The documentation system provides three substitutions that are defined by +default. They are set in the build configuration file. + +.. describe:: |release| + + Replaced by the project release the documentation refers to. This is meant + to be the full version string including alpha/beta/release candidate tags, + e.g. ``2.5.2b3``. Set by :confval:`release`. + +.. describe:: |version| + + Replaced by the project version the documentation refers to. This is meant to + consist only of the major and minor version parts, e.g. ``2.5``, even for + version 2.5.1. Set by :confval:`version`. + +.. describe:: |today| + + Replaced by either today's date (the date on which the document is read), or + the date set in the build configuration file. Normally has the format + ``April 14, 2007``. Set by :confval:`today_fmt` and :confval:`today`. + +.. describe:: |translation progress| + + Replaced by the translation progress of the document. + This substitution is intented for use by document translators + as a marker for the translation progress of the document. diff --git a/doc/usage/theming.rst b/doc/usage/theming.rst new file mode 100644 index 0000000..c33c7d4 --- /dev/null +++ b/doc/usage/theming.rst @@ -0,0 +1,364 @@ +.. highlight:: python + +.. _html-themes: + +HTML Theming +============ + +Sphinx provides a number of builders for HTML and HTML-based formats. + +Builders +-------- + +.. todo:: Populate when the 'builders' document is split up. + + +Themes +------ + +.. versionadded:: 0.6 + +.. note:: + + This section provides information about using pre-existing HTML themes. If + you wish to create your own theme, refer to + :doc:`/development/theming`. + +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. +Additionally, it has a configuration file which specifies from which theme to +inherit, which highlighting style to use, and what options exist for customizing +the theme's look and feel. + +Themes are meant to be project-unaware, so they can be used for different +projects without change. + +Using a theme +~~~~~~~~~~~~~ + +Using a :ref:`theme provided with Sphinx <builtin-themes>` is easy. Since these +do not need to be installed, you only need to set the :confval:`html_theme` +config value. For example, to enable the ``classic`` theme, add the following +to :file:`conf.py`:: + + html_theme = "classic" + +You can also set theme-specific options using the :confval:`html_theme_options` +config value. These options are generally used to change the look and feel of +the theme. For example, to place the sidebar on the right side and a black +background for the relation bar (the bar with the navigation links at the +page's top and bottom), add the following :file:`conf.py`:: + + html_theme_options = { + "rightsidebar": "true", + "relbarbgcolor": "black" + } + +If the theme does not come with Sphinx, it can be in two static forms or as a +Python package. For the static forms, either a directory (containing +:file:`theme.conf` and other needed files), or a zip file with the same +contents is supported. The directory or zipfile must be put where Sphinx can +find it; for this there is the config value :confval:`html_theme_path`. This +can be a list of directories, relative to the directory containing +:file:`conf.py`, that can contain theme directories or zip files. For example, +if you have a theme in the file :file:`blue.zip`, you can put it right in the +directory containing :file:`conf.py` and use this configuration:: + + html_theme = "blue" + html_theme_path = ["."] + +The third form is a Python package. If a theme you want to use is distributed +as a Python package, you can use it after installing + +.. code-block:: console + + # installing theme package + $ pip install sphinxjp.themes.dotted + +Once installed, this can be used in the same manner as a directory or +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`. + +.. _builtin-themes: + +Builtin themes +~~~~~~~~~~~~~~ + +.. cssclass:: longtable, standard + ++--------------------+--------------------+ +| **Theme overview** | | ++--------------------+--------------------+ +| |alabaster| | |classic| | +| | | +| *alabaster* | *classic* | ++--------------------+--------------------+ +| |sphinxdoc| | |scrolls| | +| | | +| *sphinxdoc* | *scrolls* | ++--------------------+--------------------+ +| |agogo| | |traditional| | +| | | +| *agogo* | *traditional* | ++--------------------+--------------------+ +| |nature| | |haiku| | +| | | +| *nature* | *haiku* | ++--------------------+--------------------+ +| |pyramid| | |bizstyle| | +| | | +| *pyramid* | *bizstyle* | ++--------------------+--------------------+ + +.. |alabaster| image:: /_static/themes/alabaster.png +.. |classic| image:: /_static/themes/classic.png +.. |sphinxdoc| image:: /_static/themes/sphinxdoc.png +.. |scrolls| image:: /_static/themes/scrolls.png +.. |agogo| image:: /_static/themes/agogo.png +.. |traditional| image:: /_static/themes/traditional.png +.. |nature| image:: /_static/themes/nature.png +.. |haiku| image:: /_static/themes/haiku.png +.. |pyramid| image:: /_static/themes/pyramid.png +.. |bizstyle| image:: /_static/themes/bizstyle.png + +Sphinx comes with a selection of themes to choose from. + +Note that from these themes only the Alabaster and Scrolls themes are +mobile-optimated, the other themes resort to horizontal scrolling +if the screen is too narrow. + +.. cssclass:: clear + +These themes are: + +**basic** + This is a basically unstyled layout used as the base for the + other themes, and usable as the base for custom themes as well. The HTML + contains all important elements like sidebar and relation bar. There are + these options (which are inherited by the other themes): + + - **nosidebar** (true or false): Don't include the sidebar. Defaults to + ``False``. + + - **sidebarwidth** (int or str): Width of the sidebar in pixels. + This can be an int, which is interpreted as pixels or a valid CSS + dimension string such as '70em' or '50%'. Defaults to 230 pixels. + + - **body_min_width** (int or str): Minimal width of the document body. + This can be an int, which is interpreted as pixels or a valid CSS + dimension string such as '70em' or '50%'. Use 0 if you don't want + a width limit. Defaults may depend on the theme (often 450px). + + - **body_max_width** (int or str): Maximal width of the document body. + This can be an int, which is interpreted as pixels or a valid CSS + dimension string such as '70em' or '50%'. Use 'none' if you don't + want a width limit. Defaults may depend on the theme (often 800px). + + - **navigation_with_keys** (true or false): Allow navigating + with the following keyboard shortcuts: + + - :kbd:`Left arrow`: previous page + - :kbd:`Right arrow`: next page + + Defaults to ``False``. + + - **enable_search_shortcuts** (true or false): Allow jumping to the search box + with :kbd:`/` and allow removal of search highlighting with :kbd:`Esc`. + + Defaults to ``True``. + + - **globaltoc_collapse** (true or false): Only expand subsections + of the current document in ``globaltoc.html`` + (see :confval:`html_sidebars`). + Defaults to ``True``. + + .. versionadded:: 3.1 + + - **globaltoc_includehidden** (true or false): Show even those + subsections in ``globaltoc.html`` (see :confval:`html_sidebars`) + which have been included with the ``:hidden:`` flag of the + :rst:dir:`toctree` directive. + Defaults to ``False``. + + .. versionadded:: 3.1 + + - **globaltoc_maxdepth** (int): The maximum depth of the toctree in + ``globaltoc.html`` (see :confval:`html_sidebars`). Set it to -1 to allow + unlimited depth. Defaults to the max depth selected in the toctree directive. + + .. versionadded:: 3.2 + +**alabaster** + `Alabaster theme`_ is a modified "Kr" Sphinx theme from @kennethreitz + (especially as used in his Requests project), which was itself originally + based on @mitsuhiko's theme used for Flask & related projects. Refer to its + `installation page`_ for information on how to configure + :confval:`html_sidebars` for its use. + + .. _Alabaster theme: https://pypi.org/project/alabaster/ + .. _installation page: https://alabaster.readthedocs.io/en/latest/installation.html + +**classic** + This is the classic theme, which looks like `the Python 2 + documentation <https://docs.python.org/2/>`_. It can be customized via + these options: + + - **rightsidebar** (true or false): Put the sidebar on the right side. + Defaults to ``False``. + + - **stickysidebar** (true or false): Make the sidebar "fixed" so that it + doesn't scroll out of view for long body content. This may not work well + with all browsers. Defaults to ``False``. + + - **collapsiblesidebar** (true or false): Add an *experimental* JavaScript + snippet that makes the sidebar collapsible via a button on its side. + Defaults to ``False``. + + - **externalrefs** (true or false): Display external links differently from + internal links. Defaults to ``False``. + + There are also various color and font options that can change the color scheme + without having to write a custom stylesheet: + + - **footerbgcolor** (CSS color): Background color for the footer line. + - **footertextcolor** (CSS color): Text color for the footer line. + - **sidebarbgcolor** (CSS color): Background color for the sidebar. + - **sidebarbtncolor** (CSS color): Background color for the sidebar collapse + button (used when *collapsiblesidebar* is ``True``). + - **sidebartextcolor** (CSS color): Text color for the sidebar. + - **sidebarlinkcolor** (CSS color): Link color for the sidebar. + - **relbarbgcolor** (CSS color): Background color for the relation bar. + - **relbartextcolor** (CSS color): Text color for the relation bar. + - **relbarlinkcolor** (CSS color): Link color for the relation bar. + - **bgcolor** (CSS color): Body background color. + - **textcolor** (CSS color): Body text color. + - **linkcolor** (CSS color): Body link color. + - **visitedlinkcolor** (CSS color): Body color for visited links. + - **headbgcolor** (CSS color): Background color for headings. + - **headtextcolor** (CSS color): Text color for headings. + - **headlinkcolor** (CSS color): Link color for headings. + - **codebgcolor** (CSS color): Background color for code blocks. + - **codetextcolor** (CSS color): Default text color for code blocks, if not + set differently by the highlighting style. + + - **bodyfont** (CSS font-family): Font for normal text. + - **headfont** (CSS font-family): Font for headings. + +**sphinxdoc** + The theme originally used by this documentation. It features + a sidebar on the right side. There are currently no options beyond + *nosidebar* and *sidebarwidth*. + + .. note:: + + The Sphinx documentation now uses + `an adjusted version of the sphinxdoc theme + <https://github.com/sphinx-doc/sphinx/tree/master/doc/_themes/sphinx13>`_. + +**scrolls** + A more lightweight theme, based on `the Jinja documentation + <https://jinja.palletsprojects.com/>`_. The following color options are + available: + + - **headerbordercolor** + - **subheadlinecolor** + - **linkcolor** + - **visitedlinkcolor** + - **admonitioncolor** + +**agogo** + A theme created by Andi Albrecht. The following options are supported: + + - **bodyfont** (CSS font family): Font for normal text. + - **headerfont** (CSS font family): Font for headings. + - **pagewidth** (CSS length): Width of the page content, default 70em. + - **documentwidth** (CSS length): Width of the document (without sidebar), + default 50em. + - **sidebarwidth** (CSS length): Width of the sidebar, default 20em. + - **rightsidebar** (true or false): Put the sidebar on the right side. + Defaults to ``True``. + - **bgcolor** (CSS color): Background color. + - **headerbg** (CSS value for "background"): background for the header area, + default a grayish gradient. + - **footerbg** (CSS value for "background"): background for the footer area, + default a light gray gradient. + - **linkcolor** (CSS color): Body link color. + - **headercolor1**, **headercolor2** (CSS color): colors for <h1> and <h2> + headings. + - **headerlinkcolor** (CSS color): Color for the backreference link in + headings. + - **textalign** (CSS *text-align* value): Text alignment for the body, default + is ``justify``. + +**nature** + A greenish theme. There are currently no options beyond + *nosidebar* and *sidebarwidth*. + +**pyramid** + A theme from the Pyramid web framework project, designed by Blaise Laflamme. + There are currently no options beyond *nosidebar* and *sidebarwidth*. + +**haiku** + A theme without sidebar inspired by the `Haiku OS user guide + <https://www.haiku-os.org/docs/userguide/en/contents.html>`_. The following + options are supported: + + - **full_logo** (true or false, default ``False``): If this is true, the + header will only show the :confval:`html_logo`. Use this for large logos. + If this is false, the logo (if present) will be shown floating right, and + the documentation title will be put in the header. + + - **textcolor**, **headingcolor**, **linkcolor**, **visitedlinkcolor**, + **hoverlinkcolor** (CSS colors): Colors for various body elements. + +**traditional** + A theme resembling the old Python documentation. There are + currently no options beyond *nosidebar* and *sidebarwidth*. + +**epub** + A theme for the epub builder. This theme tries to save visual + space which is a sparse resource on ebook readers. The following options + are supported: + + - **relbar1** (true or false, default ``True``): If this is true, the + `relbar1` block is inserted in the epub output, otherwise it is omitted. + + - **footer** (true or false, default ``True``): If this is true, the + `footer` block is inserted in the epub output, otherwise it is omitted. + +**bizstyle** + A simple bluish theme. The following options are supported + beyond *nosidebar* and *sidebarwidth*: + + - **rightsidebar** (true or false): Put the sidebar on the right side. + Defaults to ``False``. + +.. versionadded:: 1.3 + 'alabaster', 'sphinx_rtd_theme' and 'bizstyle' theme. + +.. versionchanged:: 1.3 + The 'default' theme has been renamed to 'classic'. 'default' is still + available, however it will emit a notice that it is an alias for the new + 'alabaster' theme. + +.. _third-party-themes: + +Third Party Themes +~~~~~~~~~~~~~~~~~~ + +There are many third-party themes created for Sphinx. Some of these are for +general use, while others are specific to an individual project. + +sphinx-themes.org__ is a gallery that showcases various themes for Sphinx, +with demo documentation rendered under each theme. Themes can also be found +on PyPI__ (using the classifier ``Framework :: Sphinx :: Theme``), GitHub__ +and GitLab__. + +.. __: https://sphinx-themes.org/ +.. __: https://pypi.org/search/?q=&o=&c=Framework+%3A%3A+Sphinx+%3A%3A+Theme +.. __: https://github.com/search?utf8=%E2%9C%93&q=sphinx+theme +.. __: https://gitlab.com/explore?name=sphinx+theme |
